In RDF, an IRI identifies a resource that can be used as a subject, predicate or object of a Triple.

An IRI identifies a resource that can be used as a subject, predicate or object of a Triple or Quad, where it can also be used a graph name.

@@ -515,7 +515,7 @@ Example output:

http://example.com/alice

Note: The IRI string might contain non-ASCII characters which must be %-encoded for applications that expect an URI. It is currently out of scope for Commons RDF to perform such a conversion, however implementations might provide separate methods for that purpose.

Note: The IRI string might contain non-ASCII characters which must be %-encoded for applications that expect an URI. It is currently out of scope for Commons RDF to perform such a conversion, however implementations might provide separate methods for that purpose.

Two IRI instances can be compared using the equals method, which uses simple string comparison:

@@ -551,7 +551,7 @@ System.out.println(iri.equals(factory.cr

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.

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 or Quad, where it can also be used a graph name.

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

@@ -591,11 +591,19 @@ System.out.println(bnode.equals(factory.

System.out.println(b1.equals(factory.createBlankNode("b1")));
-System.out.println(b1.equals(new SimpleRDFTermFactory().createBlankNode("b1")));

true
+

That means that care should be taken to create a new RDFTermFactory if making “different” blank nodes (e.g. parsed from a different RDF file) which accidfentally might have the same name:

+ +

System.out.println(b1.equals(new SimpleRDFTermFactory().createBlankNode("b1")));
+

+ +

false

@@ -614,7 +622,7 @@ System.out.println(b1.equals(new SimpleR

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.

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 or Quad

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

@@ -626,7 +634,7 @@ System.out.println(literal.ntriplesStrin

"Hello world!"

The lexical value (what is inside the quotes) can be retrieved using getLexicalForm():

The lexical value (what is inside the quotes) can be retrieved using getLexicalForm():

@@ -666,7 +674,7 @@ which case you might find Literalplain literal data type.

-To create a literal with any other datatype, then first create the datatype IRI and pass it to the expanded createLiteral: +To create a literal with any other datatype (e.g. xsd:double), then create the datatype IRI and pass it to the expanded createLiteral: @@ -686,11 +694,11 @@ System.out.println(literalDouble.ntriple Literal literalDouble2 = factory.createLiteral("13.37", Types.XSD_DOUBLE); -As the constants in Types are all instances of IRI, they can also be used for comparisons: +As the constants in Types are all instances of IRI, so they can also be used for comparisons: -System.out.println(literal.getDatatype().equals(Types.XSD_STRING)); +System.out.println(Types.XSD_STRING.equals(literal.getDatatype())); @@ -734,7 +742,7 @@ if (tag.isPresent()) { es -The language tag is behind an Optional as it cannot be present for any other datatypes than http://www.w3.org/1999/02/22-rdf-syntax-ns#langString: +The language tag is behind an Optional as it won’t be present for any other datatypes than http://www.w3.org/1999/02/22-rdf-syntax-ns#langString: @@ -824,7 +832,8 @@ if (obj instanceof Literal) { true - + +This equality is true even across implementations, as Commons RDF has specified equality semantics for Triples, Quads, IRIs, Literals and even BlankNodes. Graph A graph is a collection of triples. @@ -837,7 +846,6 @@ if (obj instanceof Literal) { 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: @@ -866,7 +874,7 @@ graph.add(bob, nameIRI, bobName); true -The expanded subject/predicate/object call for Graph.contains() can be used without needing to create a Triple first, and also allow null as a wildcard parameters: +The expanded subject/predicate/object call for Graph.contains() can be used without needing to create a Triple first, and also allow null as a wildcard parameter: @@ -917,13 +925,16 @@ graph.add(bob, nameIRI, bobName); Stream of triples -For processing of larger graphs, and to access more detailed filtering and processing, the getTriples method return a Java 8 Stream. +For processing of larger graphs, and to access more detailed filtering and processing, the stream method return a Java 8 Stream. +Some of the implementations (e.g. RDF4J) might require resources to be closed after the stream has been processed, so .stream() should be used within a try-with-resources block. -Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject()); -String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" ")); -System.out.println(s); +try (Stream<? extends Triple> triples = graph.stream()) { + Stream<RDFTerm> subjects = triples.map(t -> t.getObject()); + String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" ")); + System.out.println(s); +} @@ -931,13 +942,15 @@ System.out.println(s); For details about what can be done with a stream, see the java.util.stream documentation. Note that by default the stream will be parallel, use .sequential() if your stream operations need to interact with objects that are not thread-safe. -Streams allow advanced filter predicates, but you may find that simple subject/predicate/object patterns are handled more efficiently by the expanded getTriples method. These can of course be combined: +Streams allow advanced filter predicates, but you may find that simple subject/predicate/object patterns are handled more efficiently by the implementation when using the expanded stream method. These can of course be combined: -Stream<? extends Triple> namedB = graph.getTriples(null, nameIri, null). - filter(t -> t.getObject().ntriplesString().contains("B")); -System.out.println(namedB.map(t -> t.getSubject()).findAny().get()); +try (Stream<? extends Triple> named = graph.stream(null, nameIri, null)) { + Stream<? extends Triple> namedB = named.filter( + t -> t.getObject().ntriplesString().contains("B")); + System.out.println(namedB.map(t -> t.getSubject()).findAny().get()); + } @@ -945,7 +958,6 @@ System.out.println(namedB.map(t -> t. Removing triples -Note: Some Graph implementations are immutable, in which case the below may throw an UnsupportedOperationException. Triples can be removed from a graph: @@ -980,7 +992,7 @@ System.out.println(graph.contains(null, 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 have a return value which .equals() any earlier return values. Being immutable, the Triple and RDFTerm types should be considered thread-safe. Similarly their hashCode() should be considered stable, so any RDFTerm or Triple can be used in hashing collections like HashMap. 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. A mutable Graph might also be modified by operations outside Commons RDF, e.g. because it is backed by a shared datastore with multiple clients. Implementations of Commons RDF may specify the (im)mutability of Graph in further details in their documentation. If a graph is immutable, the methods add and remove may throw a UnsupportedOperationException. -Commons RDF does not specify if methods on a Graph are thread-safe. Iterator methods like iterate and getTriples might throw a ConcurrentModificationException if it detects a thread concurrency modification, although this behaviour is not guaranteed. Implementations of Commons RDF may specify more specific thread-safety considerations. +Commons RDF does not specify if methods on a Graph are thread-safe. Iterator methods like iterate and stream might throw a ConcurrentModificationException if it detects a thread concurrency modification, although this behaviour is not guaranteed. Implementations of Commons RDF may specify more specific thread-safety considerations. If an implementation does not specify any thread-safety support, then all potentially concurrent access to a Graph must be synchronized, e.g.: @@ -1000,8 +1012,9 @@ synchronized(graph) { Implementations The Commons RDF API is a set of Java interfaces, which can be implemented 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). +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 - however the implementations provided by Commons RDF +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 an interoperable 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: @@ -1024,7 +1037,7 @@ IRI iri1 = fooFactory.createIRI("ht // Both Triple and RDFTerm instances can be used // -for (Triple t1: g1.getTriples(null, iri1, null)) { +for (Triple t1: g1.stream(null, iri1, null)) { if (g2.contains(t1.getSubject(), null, t1.getObject())) { g2.remove(t1); } @@ -1032,7 +1045,7 @@ for (Triple t1: g1.getTriples(null, iri1 Note: Special care might need to be taken for cross-interoperability of BlankNode instances. While multiple triples with the same “foreign” BlankNode can be added without breaking their connections, the Graph is not required to return blank node instances that .equals() those inserted - specifically it is not required to persist the blank node uniqueReference. 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 needs to be casted to implementation specific types. +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.stream(). Special care should be taken if returned values needs to be casted to implementation specific types. 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.

User Guide

Blank node

Literal

Graph

Adding triples

Stream of triples

Removing triples

Implementations

Cross-compatibility

Complete example