View this as a presesentation (requires javascript).

Topaz Overview

Contents

• Motivations
• What is Topaz?
• Simple Example
• Mapping to RDF
• Handling Blobs

Motivations

• We are using RDF to store all the application's data (except for Blob's)
• Need to insert, remove, update, and query for objects, not just individual triples
• Writing TQL by hand becomes really tedious really quickly
• Writing TQL by hand is error prone and brittle

What is Topaz?

• An Object-Tripples-Mapping library
• Modeled on Hibernate
• Define Java classes and annotate them to describe mapping into RDF
• Provides automatic persistence and retrieval of objects as a whole
• Provides a higher-level query languages (Oql and Criteria) based on objects
• Provides support for storing Blob's to a separate Blob store

Simple Example

Annotated java class (definition of Account not shown here):

@Entity(type = "foaf:Person", model = "people")
public class Person {
  @Id
  public URI id;

  @Predicate(uri = "foaf:name")
  public String name;

  @Predicate(uri = "foaf:holdsAccount")
  public Account acc;

  @Predicate(uri = "foaf:weblog")
  public URI blog;
}

Simple Example (Continued)

Work with it:

Session sess = sf.openSession();
Transaction txn = sess.beginTransaction();

Person p1 = new Person(...);
sess.saveOrUpdate(p1);

Person p2 = sess.get(Person.class,
                     "http://some.org/people/john");

Results r = sess.createQuery(
    "select p from Person p where p.name = 'John Bentley';")
    .execute();
while (r.next())
  Person p = r.get("p")

txn.commit();

Simple Example Explained

@Entity(type = "foaf:Person", model = "people")
public class Person {
  @Id
  public URI id;

• @Entity marks the class as eligible for persistence
  • type specifies the rdf type
  • model specifies the model (named graph) in which instances are to be stored and found
• @Id tells the mapper which field holds the id (subject-uri) of the instance

Simple Example Explained (Continued)

  @Predicate(uri = "foaf:name")
  public String name;

  @Predicate(uri = "foaf:holdsAccount")
  public Account acc;

• @Predicate configures how the field is mapped to RDF statements
  • uri specifies the predicate-uri the field maps to
  • the field type determines whether the field value is stored as a literal or a URI, based on a (configurable) list of serializers

Mapping to RDF

Java (application) code:

Person p1 = new Person();
p1.id   = new URI("my:id1");
p1.name = "John Bentley";
p1.blog = new URI("http://cool.blogs.com/john");
p1.acc  = new Account(new URI("my:accnt1"), "jbentley");
sess.saveOrUpdate(p1);

Resulting RDF (in N-Triples format):

<my:id1> <rdf:type> <foaf:Person> .
<my:id1> <foaf:name> "John Bentley" .
<my:id1> <foaf:weblog> <http://cool.blogs.com/john> .
<my:id1> <foaf:holdsAccount> <my:accnt1> .
<my:accnt1> <rdf:type> <foaf:OnlineAccount> .
<my:accnt1> <foaf:accountName> "jbentley" .

Handling Blobs

@Entity(type = "foaf:Person", model = "people")
public class Person {
  @Id
  public URI id;

  ...

  @Predicate(uri = "foaf:img")
  public Image pic;
}

@Entity(type = "foaf:Image", model = "people")
public class Image {
  @Id
  public URI id;

  @Blob
  public byte[] data;
}

Handling Blobs (Continued)

Work with it - just like other fields and classes:

Session sess = sf.openSession();
Transaction txn = sess.beginTransaction();

Person p1 = new Person(...);
p1.pic      = new Image();
p1.pic.id   = ...
p1.pic.data = ...
sess.saveOrUpdate(p1);

Person p2 = sess.get(Person.class,
                     "http://some.org/people/john");
display(p2.pic.data);

txn.commit();

Handling Blobs Explained

@Entity(type = "foaf:Image", model = "people")
public class Image {
  @Id
  public URI id;

  @Blob
  public byte[] data;
}

• @Blob marks the field that holds the "contents" of the object; that is, the @Id field is (also) the id of the blob in the blob-store. For this reason only one field in a class may be marked with @Blob.
• currently only byte[] is supported for @Blob fields.
• An entity may contain both @Predicate fields as well as an @Blob field - for a use-case see http://esw.w3.org/topic/ImageDescriptionRdfExamples .