An Introduction to the Jena API
CraigTrim 110000G799 Visits (19257)
What's the point?
I am having a hard time here. I get triples. I get that I want to work with a collection of triples. But what are the main, important differences between a Model, DataSource, Dataset, Graph, and DataSetGraph? What are their lifecycles? Which are designed to be kept alive for a long time, and which should be transient? What triples get persisted, and when? What stays in memory? And how are triples shared (if at all) across these five things? I'll take an RTFM answer, if there's a simple summary that contrasts these five. Most references I have found are down in the weeds and I need the forest view.
Creating a Dataset
How do I create a dataset?
Dataset ds = TDBF
A Dataset contains a default model A Dataset can likewise contain 0.. named models.
A SPARQL query over the Dataset can be
A Jena Dataset wraps and extends the functionality of a DatasetGraph.
The underlying DatasetGraph can be obtained from a Dataset at any time, via this call:
Though this is not likely to be necessary in a typical development scenario.
Read the "Jena Architectural Overview" for a distinction on the Jena SPI (Graph Layer) and Jena API (Model Layer)
Create a Named Model
We're going to be loading data from the IBM PTI Catalog1, so let's create a named model for this data:
Dataset ds = TDBF
Triples always have to be loaded into a Model. We could choose to use the "default model" through this call:
But it's good practice to use a named model. A named model functions as a "logical partition" for data. It's a way of logically containing data. One advantage to this approach is query efficiency. If there are multiple models, any given model will represent a subset of all available triples. The smaller the model, the faster the query.
Named models can also be merged in a very simple operation:
Model merged = model.add(model);
You can merge as many models as you want into a single model for querying purposes.
Think of models like building blocks. A dataset might contain four models:
"D" represents the "Default Model". If you prefer not to work with named models, then you would simply make this call:
Model model = data
The default model always exists (default) in the Dataset. It will exist even if it is not used. I recommend ignoring the default model and focus on creating named models.
The graph name is actually an RDF Node. A named graph is like a logical partition to the dataset. Some triples belong to one named graph; other triples belong to another named graph, etc. Behind the scenes, Jena is creating a "Quad".
Recall that a triple is:
Subject, Predicate, Object
A quad is:
Subject, Predicate, Object, Context
A quad functions just like a triple, with the addition of a context node. In this case, every triple we create in this tutorial (just one in this example) will have an associated "4th node" - this is the node that represents the named graph. Note that when you write a triple to the default model, you are creating a triple. There is no "fourth node" in this case. Quads only apply where named models are present.
Consider this triple:
Shakespeare authorOf Hamlet
If we request Jena to add this triple to the named model called "plays", a Quad will be created that looks like this:
Shakespare authorOf Hamlet +plays
If we request Jena to add this to the default model, it will look like this:
Shakespare authorOf Hamlet
Each quad is stored in the DatasetGraph. Rather than using a more complex containment strategy, this is simply a method of "indexing" each triple with a fourth node that provides context. Note that this is an implementation of the W3 RDF standard, and not a Jena-specific extension. This does not affect how you have to think about the "triple store", nor does it affect how you write SPARQL queries.
The SPARQL query:
?subject ?predicate ?object
will work the same way against a named model (quads) as it will against a default model (triples).
Note that a named model will not exist until you create it:
Model model1 = data
When you make a call to the "getNamedModel", the model will be located and returned. If the model does not exist, it will be created and returned.
A query could be executed against the entire dataset:
Model union = data
This method call is computationally "free". Jena simply provides a model that contains all the triples across the entire dataset.
A query could be executed against certain models in the dataset:
Model merged = data
Such a model can be either persisted to the file system if necesssary.
Let's return to our original code. Changes to the dataset (such as writing or deleting triples) are surrounded with a try/finally pattern:
Dataset dataset = TDBF
This pattern should be used when data is inserted or updated to a Dataset or Model.
There is a performance hit to this pattern. Don't use it a granular level, for each and every update and/or insertion. Try to batch up inserts within a single try/finally block.
If this try/finally pattern is not used, the data will still be written to file. However, the model will be inconsistent, and iteration over the model could provoke a "NoS
Create a Triple
When using the model layer in Jena, a triple is composed of:
an instance of
The object of a triple can be any of the three types above:
Examples of a Literal:
The subject of a triple is limited to either of:
It is possible to make assertions about properties in the form of a triple. For example, if we create a predicate called "partOf" we might want to make this a transitive property. We would do so by creating the triple:
partOf rdf:type owl:
On the other hand, such an assertion could be dangerous:
finger partOf hand partOf body partOf Craig partOf IBM
which might lead one to believe:
finger partOf IBM
(perhaps this is true)
Let's get to the code already ...
The following code will create three disconnected "nodes" in Jena.
String ns = "htt
Namespaces in RDF
Note the use of
Every resource in the model (should) be qualified by a namespace. This is pretty standard when dealing with data – not just RDF. The reasons we might have for qualifying a resource with a namespace in a triple store are the same reasons we might have for qualifying a resource with a namespace in XML. The use of a qualified name helps ensure a unique name.
You might have to merge your triple store with a triple store that you found online, or from another company. Two resources may have the same name, and may even (conceptually) have similar meanings, but they will not necessarily be used the same way.
One developer might assert that the use of "partOf" is transitive. Another developer might assert that the use of "partOf" is not transitive. Both properties mean the same thing, but clearly you would want to have these properties qualified with namespaces, so that the correct property could be used for each situation. For example, let us assume that
ns1:partOf rdf:type owl:
and that ns2:partOf is not transitive.
We could then correctly model this scenario:
finger ns1:partOf hand ns1:partOf body ns1:partOf Craig ns2:partOf IBM
Craig is "part of" IBM and finger is "part of" Craig, but finger is not "part of" IBM.
... back to the code
So now we've created 3 RDFNodes in our Jena named model.
If you're thinking something doesn't look right here, you're right. These nodes are disconnected. We haven't actually created a triple yet. We've just created two Resources and a Property.
You might not find yourself in a situation where you are creating properties at runtime. A triple store could be initialized with an Ontology model, which would itself explictly define the predicates and their usage. The triple store would then reference these pre-existing properties.
However, there are valid situations where properties could created automatically. Text analytics on a large corpus and finding verbs (actions) that connect entities; the verbs could be modeled as predicates, and the results queried once complete.
Connect the Nodes
In order to actually connect these values as a triple, we need to call this code:
connect(subject, predicate, object);
Of course, you don't actually have to use my code above. But it is a lot easier to put a method around these two Jena methods (add and createStatement). And of course, all of this occurs within the context of the try/finally block discussed earlier.
And then we get this:
It's perfectly valid to write resources to a model without connecting them to other resources. The connections may occur over time.
Triple Store vs Relational Store
Relationships in a triple store can and should surprise you. You'll never design an Entity Relationship Diagram (ERD) and use a Relational Database (RDBMS) – and wake up one morning to find that there is a new relationship between table a and table b. This just doesn't happen. Primary keys, Foreign keys, Alternate keys – these are all the result of foresight and careful design of a well understood domain. The better the domain is understood, the better the relational database will be designed. If the structure of a relational database change, this can have a severe impact on the consumers of the data store.
But a triple store is designed for change. If the domain is so large, and so dynamic, that it can never be fully understood, or fully embraced – then an ERD may not be the right choice. An Ontology and Triple Store may be better suited. As more data is added, relationships will begin to occur between nodes, and queries that execute against the triple store will return results where the relationships between entities in the result set may not have been anticipated.
Saving the Results
Triples are held in a dataset which is either transient (in memory) or persisted (on disk). In the example we've just completed, the created triple was stored in Jena TDB.
The first call we looked at:
Dataset dataset = TDBF
actually creates a triple store on disk, at the location specified. If a triple store already existed at that location, this factory method would simply return the dataset for that triple store. Database setup doesn't get any easier than this. And TDB is a serious triple store – suitable for enterprise applications that require scalability2 and performance.
But what if we want to see what is actually in the triple store? Actually look at the data? We need the equivalent of a database dump. Fortunately, the Jena API makes it quite trivial to serialize model contents to file:
Notice the use of the string literal "RDF/XML" as the second parameter of the write() method. There are multiple serialization types for RDF.
Some of the more common ones are:
TTL and N3 are among the easiest to read. RDF/XML is one of the original formats. If you cut your teeth on RDF by reading the RDF/XML format (still very common for online examples and tutorials) you may prefer that. But if you are new to this technology, you'll likely find TTL the most readable of all these formats.
If we execute the above code on the triple we created, we'll end up with these serializations:
Note that RDF/XML-ABBREV will show nesting (similar to an XML document). Since we only have a single triple in this demo, there's nothing to show for the serialization.