The <version> above might not be up to date, see the [/download.html](download page) for the latest version.

Creating Commons RDF instances

To create instances of Commons RDF interfaces like Graph and IRI you will need a RDFTermFactory.

How to get an instance of this factory is implementation specific, for the simple implementation, you can construct the SimpleRDFTermFactory:

@@ -394,7 +403,9 @@ Literal aliceLiteral = factory.createLit

Triple triple = factory.createTriple(aliceBlankNode, nameIri, aliceLiteral);

The RDFTermFactory also contains more specific variants of some of the methods above, e.g. to create a typed literal.

Note that for any given implementation, RDFTerm instances need not be created using a RDFTermFactory. More likely, implementation-specific methods might create these objects as part of data parsing, storage lookup and queries.

RDF terms

RDFTerm is the super-interface for instances that can be used as subject, predicate and object of a Triple.

The RDF term interfaces are arranged in this class hierarchy:

@@ -416,6 +427,8 @@ Literal aliceLiteral = factory.createLit

Literal

N-Triples string

All of the RDFTerm types support the ntriplesString() method:

@@ -456,7 +469,9 @@ Example output: > `_:ef136d20-f1ee-3830-a54b-cd5e489d50fb "Alice" .` > -> ` "Bob" .` --> +> ` "Bob" .` -->

IRI

An IRI is a representation of an Internationalized Resource Identifier, e.g. http://example.com/alice or http://ns.example.org/vocab#term.

@@ -512,7 +527,9 @@ System.out.println(iri.equals(factory.cr

false

false
-
+

Blank node

A blank node is a resource which, unlike an IRI, is not directly identified. Blank nodes can be used as subject or object of a Triple Triple.

To create a new BlankNode instance from a RDFTermFactory, use createBlankNode:

@@ -560,6 +577,8 @@ System.out.println(b1.equals(new SimpleR

true

false

Blank node reference

While blank nodes are distinct from IRIs, and don’t have inherent universal identifiers, it can nevertheless be useful for debugging and testing to have a unique reference string for a particular blank node. For that purpose, BlankNode exposes the uniqueReference method:

@@ -571,7 +590,9 @@ System.out.println(b1.equals(new SimpleR

735d5e63-96a4-488b-8613-7037b82c74a5

While this reference string might for the simple implementation also be seen within the BlankNode.ntriplesString() result, there is no such guarantee from the Commons RDF API. Clients who need a globally unique reference for a blank node should therefore use the uniqueReference() method.

Note: While it is recommended for this string to be (or contain) a UUID string, implementations are free to use any scheme to ensure their blank node references are globally unique. Therefore no assumptions should be made about this string except that it is unique per blank node.

Literal

A literal in RDF is a value such as a string, number or a date. A Literal can only be used as an object of a Triple.

To create a Literal instance from an RDFTermFactory, use createLiteral:

@@ -595,6 +616,8 @@ System.out.println(lexical);

Hello world!

Datatype

All literals in RDF 1.1 have a datatype IRI, which can be retrieved using Literal.getDatatype():

@@ -634,6 +657,8 @@ System.out.println(literalDouble.ntriple

"13.37"^^<http://www.w3.org/2001/XMLSchema#double>

Types

The class Types, which is part of the simple implementation, provides IRI constants for the standard XML Schema datatypes like xsd:dateTime and xsd:float. Using Types, the above example can be simplified to:

@@ -649,7 +674,9 @@ System.out.println(literalDouble.ntriple

true
-

Language

Literals may be created with an associated language tag using the expanded createLiteral:

@@ -697,7 +724,9 @@ System.out.println(literalDouble.getLang

false

false
-

Triple

A triple in RDF 1.1 consists of:

true
-

Graph

A graph is a collection of triples.

To create a Graph instance from a RDFTermFactory, use createGraph():

@@ -783,6 +814,8 @@ if (obj instanceof Literal) {

Graph graph = factory.createGraph();

Implementations will typically also have other ways of retrieving a Graph, e.g. by parsing a Turtle file or connecting to a storage backend.

Adding triples

Note: Some Graph implementations are immutable, in which case the below may throw an UnsupportedOperationException.

Any Triple can be added to the graph using the add method:

@@ -799,7 +832,9 @@ IRI nameIri = factory.createIRI("ht Literal bobName = factory.createLiteral("Bob"); graph.add(bob, nameIRI, bobName);

It is not necessary to check if a triple already exist in the graph, as the underlying implementation will ignore duplicate triples.

Finding triples

You can check if the graph contains a triple:

@@ -819,7 +854,9 @@ graph.add(bob, nameIRI, bobName);

true
-

Size

The size of a graph is the count of unique triples:

@@ -829,7 +866,9 @@ graph.add(bob, nameIRI, bobName);

2
-

Iterating over triples

The iterate method can be used to sequentially iterate over all the triples of the graph:

@@ -854,7 +893,9 @@ graph.add(bob, nameIRI, bobName);

<http://example.com/name>
-

Stream of triples

For processing of larger graphs, and to access more detailed filtering and processing, the getTriples method return a Java 8 Stream.

@@ -880,7 +921,9 @@ System.out.println(namedB.map(t -> t.

<http://example.com/bob>
-

Removing triples

Note: Some Graph implementations are immutable, in which case the below may throw an UnsupportedOperationException.

Triples can be removed from a graph:

@@ -905,7 +948,9 @@ System.out.println(graph.contains(null,

false
-

Mutability and thread safety

Note: This section is subject to change - see discussion on COMMONSRDF-7

In Commons RDF, all instances of Triple and RDFTerm (e.g. IRI, BlankNode, Literal) are considered immutable. That is, their content does not change, and so calling a method like IRI.getIRIString or Literal.getDatatype will always have return values that are .equal() to any earlier return values. Being immutable, the Triple and RDFTerm types should be considered thread-safe.

A Graph may be mutable, particular if it supports methods like Graph.add and Graph.remove. That means that responses to methods like size and contains might change during its lifetime.

@@ -926,10 +971,14 @@ synchronized(graph) { // ... } } -

Implementations

The Commons RDF API is a set of Java interfaces, with implementations provided by several Java RDF frameworks. See the implementations page for an updated list of providers.

Implementations are free to choose their level of integration with Commons RDF. Several methods defined in Commons RDF therefore explicitly note the possibility of throwing a UnsupportedOperationException.

Different RDF frameworks might have different mechanisms to retrieve a Commons RDF objects like Graph or Triple (e.g. returned from a query). Commons RDF provides a RDFTermFactory interface as a way to create new instances, but does not mandate how the factory itself should be instantiated (e.g. a factory might be returned for an open network connection).

Cross-compatibility

While different frameworks will have their own classes implementing the Commons RDF interfaces, Commons RDF objects are intended to be cross-compatible. Thus a client would be able to mix and match objects from multiple implementations:

@@ -959,8 +1008,10 @@ for (Triple t1: g1.getTriples(null, iri1

Note: Special care might need to be taken for cross-interoperability of BlankNode instances. This is currently under discussion. See COMMONSRDF-15

The .equals() methods of RDFTerm interfaces are explicitly defined, so their instances can be compared across implementations.

Note: The Graph implementation is not required to keep the JVM object reference, e.g. after g2.add(subj1, pred, obj) it is not required to later return the same subj1 implementation in g2.getTriples(). Special care should be taken if returned values are needs to be casted to implementation specific types.

The .hashCode() is not currently explicitly defined, hence special care should be taken for cross-interoperability within hashing data structures like HashMap. See COMMONSRDF-14

The complete source code for the examples used in this user guide can be browsed in UserGuideTest.java within the examples folder of the Commons RDF source code repository.

The .hashCode() is not currently explicitly defined, hence special care should be taken for cross-interoperability within hashing data structures like HashMap. See COMMONSRDF-14

Complete example

The complete source code for the examples used in this user guide can be browsed in UserGuideTest.java within the examples folder of the Commons RDF source code repository.

Introduction

RDF concepts

Using Commons RDF from Maven

Creating Commons RDF instances

RDF terms

N-Triples string

IRI

Blank node

Blank node reference

Literal

Datatype

Types

Language

Triple

Graph

Adding triples

Finding triples

Size

Iterating over triples

Stream of triples

Removing triples

Mutability and thread safety

Implementations

Cross-compatibility

Complete example