You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2016/10/23 01:59:01 UTC
incubator-commonsrdf git commit: RDFFactory -> RDF in user guide
Repository: incubator-commonsrdf
Updated Branches:
refs/heads/COMMONSRDF-46 fa27a1789 -> 9c191fc2f
RDFFactory -> RDF in user guide
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/9c191fc2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/9c191fc2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/9c191fc2
Branch: refs/heads/COMMONSRDF-46
Commit: 9c191fc2f4ae00b6537e213d2681821b14104293
Parents: fa27a17
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Sun Oct 23 02:58:01 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Sun Oct 23 02:58:01 2016 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 257 +++++++++++++++++++-----------------
1 file changed, 134 insertions(+), 123 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/9c191fc2/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 8451ab9..6191889 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -28,8 +28,8 @@ Commons RDF [API](apidocs/).
* [RDF concepts](#RDF_concepts)
* [Using Commons RDF from Maven](#Using_Commons_RDF_from_Maven)
* [Creating Commons RDF instances](#Creating_Commons_RDF_instances)
- * [Creating a RDFFactory](#Creating_a_RDFFactory)
- * [Using a RDFFactory](#Using_a_RDFFactory)
+ * [Finding an RDF implementation](#Finding_an_RDF_implementation)
+ * [Using an RDF implementation](#Using_an_RDF_implementation)
* [RDF terms](#RDF_terms)
* [N-Triples string](#N-Triples_string)
* [IRI](#IRI)
@@ -146,25 +146,26 @@ see the [download page](download.html) for the latest version._
To create instances of Commons RDF interfaces like
[`Graph`](apidocs/org/apache/commons/rdf/api/Graph.html) and
[`IRI`](apidocs/org/apache/commons/rdf/api/IRI.html) you will need a
-[RDFFactory](apidocs/org/apache/commons/rdf/api/RDFFactory.html).
+[RDF](apidocs/org/apache/commons/rdf/api/RDF.html) implementation.
-### Creating a RDFFactory
+### Finding an RDF implementation
-How to get an instance of this factory is implementation-specific, for the
-_simple_ implementation, you can construct the
-[SimpleRDFFactory](apidocs/org/apache/commons/rdf/simple/SimpleRDFFactory.html):
+The [implementations](implementations.md) of `RDF` can usually be
+created using a normal Java constructor, for instance the
+_simple_ implementation from
+[SimpleRDF](apidocs/org/apache/commons/rdf/simple/SimpleRDF.html):
```java
import org.apache.commons.rdf.api.*;
-import org.apache.commons.rdf.simple.SimpleRDFFactory;
+import org.apache.commons.rdf.simple.SimpleRDF;
// ...
-RDFFactory factory = new SimpleRDFFactory();
+RDF rdf = new SimpleRDF();
```
-If you don't want to depend on instantiating a concrete implementation,
-you can alternatively use the
+If you don't want to depend on instantiating a concrete `RDF`
+implementation, you can alternatively use the
[ServiceLoader](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html)
-to lookup any `RDFFactory` implementations found on the classpath:
+to lookup any `RDF` implementations found on the classpath:
```java
import java.util.Iterator;
@@ -172,43 +173,47 @@ import java.util.ServiceLoader;
import org.apache.commons.rdf.api.*;
// ...
-ServiceLoader<RDFFactory> loader = ServiceLoader.load(RDFFactory.class);
-Iterator<RDFFactory> iterator = loader.iterator();
-RDFFactory factory = iterator.next();
+ServiceLoader<RDF> loader = ServiceLoader.load(RDF.class);
+Iterator<RDF> iterator = loader.iterator();
+RDF rdf = iterator.next();
```
Note that the `ServiceLoader` approach above might not work well within
split classloader systems like OSGi.
+When using the factory method
+[createBlankNode(String)](apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode-java.lang.String-)
+from different sources,
+care should be taken to create correspondingly different `RDF` instances.
-### Using a RDFFactory
-Using the factory you can construct
+### Using an RDF implementation
+
+Using the `RDF` implementation you can construct
any [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html), e.g. to create a
[BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html),
[IRI](apidocs/org/apache/commons/rdf/api/IRI.html) and
[Literal](apidocs/org/apache/commons/rdf/api/Literal.html):
```java
-BlankNode aliceBlankNode = factory.createBlankNode();
-IRI nameIri = factory.createIRI("http://example.com/name");
-Literal aliceLiteral = factory.createLiteral("Alice");
+BlankNode aliceBlankNode = rdf.createBlankNode();
+IRI nameIri = rdf.createIRI("http://example.com/name");
+Literal aliceLiteral = rdf.createLiteral("Alice");
```
You can also create a stand-alone [Triple](apidocs/org/apache/commons/rdf/api/Triple.html):
```java
-Triple triple = factory.createTriple(aliceBlankNode, nameIri, aliceLiteral);
+Triple triple = rdf.createTriple(aliceBlankNode, nameIri, aliceLiteral);
```
-The [RDFFactory](apidocs/org/apache/commons/rdf/api/RDFFactory.html) also
+The [RDF](apidocs/org/apache/commons/rdf/api/RDF.html) interface 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 `RDFFactory`. More likely, implementation-specific methods might create these
-objects as part of data parsing, storage lookup and queries.
-
+In addition, the [implementations](implementations.md) of `RDF` may add
+specific converter methods and implementation-specific
+subtypes for interoperability with their underlying RDF framework's API.
## RDF terms
@@ -217,7 +222,7 @@ objects as part of data parsing, storage lookup and queries.
the super-interface for instances that can be used as subject, predicate and
object of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html).
-The RDF term interfaces are arranged in this class hierarchy:
+The RDF term interfaces are arranged in this ty[e hierarchy:
* [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html)
* [BlankNodeOrIRI](apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html)
@@ -243,7 +248,7 @@ System.out.println(aliceLiteral.ntriplesString());
> ``"Alice"``
This returns the [N-Triples](http://www.w3.org/TR/n-triples) canonical form
-of the term, which can be useful both for debugging and simple serialization.
+of the term, which can be useful for debugging or simple serialization.
_Note: The `.toString()` of the `simple` implementation used in
some of these examples use `ntriplesString()` internally, but Commons RDF
@@ -292,10 +297,10 @@ _predicate_ or _object_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.
[Quad](apidocs/org/apache/commons/rdf/api/Quad.html),
where it can also be used a _graph name_.
-To create an `IRI` instance from a `RDFFactory`, use [createIRI](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createIRI-java.lang.String-):
+To create an `IRI` instance from an `RDF` implementation, use [createIRI](apidocs/org/apache/commons/rdf/api/RDF.html#createIRI-java.lang.String-):
```java
-IRI iri = factory.createIRI("http://example.com/alice");
+IRI iri = rdf.createIRI("http://example.com/alice");
```
You can retrieve the IRI string using [getIRIString](apidocs/org/apache/commons/rdf/api/IRI.html#getIRIString--):
@@ -316,14 +321,14 @@ Two IRI instances can be compared using the
method, which uses [simple string comparison](http://tools.ietf.org/html/rfc3987#section-5.3.1):
```java
-IRI iri2 = factory.createIRI("http://example.com/alice");
+IRI iri2 = rdf.createIRI("http://example.com/alice");
System.out.println(iri.equals(iri2));
```
> `true`
```java
-IRI iri3 = factory.createIRI("http://example.com/alice/./");
+IRI iri3 = rdf.createIRI("http://example.com/alice/./");
System.out.println(iri.equals(iri3));
```
@@ -335,7 +340,7 @@ instances of [IRI](apidocs/org/apache/commons/rdf/api/IRI.html):
```java
System.out.println(iri.equals("http://example.com/alice"));
-System.out.println(iri.equals(factory.createLiteral("http://example.com/alice")));
+System.out.println(iri.equals(rdf.createLiteral("http://example.com/alice")));
```
> `false`
>
@@ -353,11 +358,11 @@ where it can also be used a _graph name_.
To create a new
[BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html) instance from a
-`RDFFactory`, use
-[createBlankNode](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createBlankNode--):
+`RDF` implementation, use
+[createBlankNode](apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode--):
```java
-BlankNode bnode = factory.createBlankNode();
+BlankNode bnode = rdf.createBlankNode();
```
Every call to `createBlankNode()` returns a brand new blank node
@@ -368,7 +373,7 @@ to itself:
```java
System.out.println(bnode.equals(bnode));
-System.out.println(bnode.equals(factory.createBlankNode()));
+System.out.println(bnode.equals(rdf.createBlankNode()));
```
> `true`
@@ -377,13 +382,13 @@ System.out.println(bnode.equals(factory.createBlankNode()));
Sometimes it can be beneficial to create a blank node based on a
localized _name_, without needing to keep object references
-to earlier `BlankNode` instances. For that purpose, `RDFFactory`
-may support the
-[expanded createBlankNode](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createBlankNode-java.lang.String-)
+to earlier `BlankNode` instances. For that purpose, the
+`RDF` interface provides the
+[expanded createBlankNode](apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode-java.lang.String-)
method:
```java
-BlankNode b1 = factory.createBlankNode("b1");
+BlankNode b1 = rdf.createBlankNode("b1");
```
Note that there is no requirement for the
@@ -398,22 +403,22 @@ System.out.println(b1.ntriplesString());
-Any later `createBlankNode("b1")` **on the same factory instance**
+Any later `createBlankNode("b1")` **on the same `RDF` instance**
returns a `BlankNode` which are
[equal](apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-)
to the previous b1:
```java
-System.out.println(b1.equals(factory.createBlankNode("b1")));
+System.out.println(b1.equals(rdf.createBlankNode("b1")));
```
> `true`
-That means that care should be taken to create a new `RDFFactory` if making
-"different" blank nodes (e.g. parsed from a different RDF file)
+That means that care should be taken to create a new `RDF` instance
+if making "different" blank nodes (e.g. parsed from a different RDF file)
which accidfentally might have the same name:
```java
-System.out.println(b1.equals(new SimpleRDFFactory().createBlankNode("b1")));
+System.out.println(b1.equals(new SimpleRDF().createBlankNode("b1")));
```
> `false`
@@ -455,11 +460,11 @@ an _object_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html#getObje
or [Quad](apidocs/org/apache/commons/rdf/api/Quad.html#getObject--)
To create a [Literal](apidocs/org/apache/commons/rdf/api/Literal.html) instance
-from an `RDFFactory`, use
-[createLiteral](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createLiteral-java.lang.String-):
+from an `RDF` implementation, use
+[createLiteral](apidocs/org/apache/commons/rdf/api/RDF.html#createLiteral-java.lang.String-):
```java
-Literal literal = factory.createLiteral("Hello world!");
+Literal literal = rdf.createLiteral("Hello world!");
System.out.println(literal.ntriplesString());
```
@@ -515,11 +520,11 @@ literal</a> data type.
To create a literal with any other
[datatype](http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri) (e.g. `xsd:double`),
then create the datatype `IRI` and pass it to the expanded
-[createLiteral](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createLiteral-java.lang.String-org.apache.commons.rdf.api.IRI-):
+[createLiteral](apidocs/org/apache/commons/rdf/api/RDF.html#createLiteral-java.lang.String-org.apache.commons.rdf.api.IRI-):
```java
-IRI xsdDouble = factory.createIRI("http://www.w3.org/2001/XMLSchema#double");
-Literal literalDouble = factory.createLiteral("13.37", xsdDouble);
+IRI xsdDouble = rdf.createIRI("http://www.w3.org/2001/XMLSchema#double");
+Literal literalDouble = rdf.createLiteral("13.37", xsdDouble);
System.out.println(literalDouble.ntriplesString());
```
@@ -536,7 +541,7 @@ XML Schema datatypes like `xsd:dateTime` and `xsd:float`. Using `Types`,
the above example can be simplified to:
```java
-Literal literalDouble2 = factory.createLiteral("13.37", Types.XSD_DOUBLE);
+Literal literalDouble2 = rdf.createLiteral("13.37", Types.XSD_DOUBLE);
```
As the constants in `Types` are all instances of `IRI`, so they can
@@ -552,10 +557,10 @@ System.out.println(Types.XSD_STRING.equals(literal.getDatatype()));
Literals may be created with an associated
[language tag](http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string)
-using the expanded [createLiteral](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createLiteral-java.lang.String-java.lang.String-):
+using the expanded [createLiteral](apidocs/org/apache/commons/rdf/api/RDF.html#createLiteral-java.lang.String-java.lang.String-):
```java
-Literal inSpanish = factory.createLiteral("�Hola, Mundo!", "es");
+Literal inSpanish = rdf.createLiteral("�Hola, Mundo!", "es");
System.out.println(inSpanish.ntriplesString());
System.out.println(inSpanish.getLexicalForm());
```
@@ -609,15 +614,15 @@ RDF 1.1 consists of:
* The [object](apidocs/org/apache/commons/rdf/api/Triple.html#getObject--), which is an [IRI](apidocs/org/apache/commons/rdf/api/IRI.html), a [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html) or a [Literal](apidocs/org/apache/commons/rdf/api/Literal.html)
-To construct a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html) from a
-`RDFFactory`, use
-[createTriple](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createTriple-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
+To construct a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html) from an
+`RDF` implementation, use
+[createTriple](apidocs/org/apache/commons/rdf/api/RDF.html#createTriple-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
```java
-BlankNodeOrIRI subject = factory.createBlankNode();
-IRI predicate = factory.createIRI("http://example.com/says");
-RDFTerm object = factory.createLiteral("Hello");
-Triple triple = factory.createTriple(subject, predicate, object);
+BlankNodeOrIRI subject = rdf.createBlankNode();
+IRI predicate = rdf.createIRI("http://example.com/says");
+RDFTerm object = rdf.createLiteral("Hello");
+Triple triple = rdf.createTriple(subject, predicate, object);
```
The subject of the triple can be retrieved
@@ -675,7 +680,7 @@ to another `Triple` if each of their subject, predicate and object are
equal:
```java
-System.out.println(triple.equals(factory.createTriple(subj, pred, obj)));
+System.out.println(triple.equals(rdf.createTriple(subj, pred, obj)));
```
> `true`
@@ -700,14 +705,14 @@ Commons RDF represents such statements using the class [Quad](apidocs/org/apache
* The [graph name](apidocs/org/apache/commons/rdf/api/Quad.html#getGraphName--), which is an [IRI](apidocs/org/apache/commons/rdf/api/IRI.html) or a [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html); wrapped as an `java.util.Optional`
-To create a `Quad`, use [createQuad](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
+To create a `Quad`, use [createQuad](apidocs/org/apache/commons/rdf/api/RDF.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
```
-BlankNodeOrIRI graph = factory.createIRI("http://example.com/graph");
-BlankNodeOrIRI subject = factory.createBlankNode();
-IRI predicate = factory.createIRI("http://example.com/says");
-RDFTerm object = factory.createLiteral("Hello");
-Quad quad = factory.createQuad(graph, subject, predicate, object);
+BlankNodeOrIRI graph = rdf.createIRI("http://example.com/graph");
+BlankNodeOrIRI subject = rdf.createBlankNode();
+IRI predicate = rdf.createIRI("http://example.com/says");
+RDFTerm object = rdf.createLiteral("Hello");
+Quad quad = rdf.createQuad(graph, subject, predicate, object);
```
The subject, predicate and object are accessible just like in a `Triple`:
@@ -747,7 +752,7 @@ To create a quad in the _default graph_, supply `null` as the graph name
to the factory method:
```
-Quad otherQuad = factory.createQuad(null, subject, predicate, object);
+Quad otherQuad = rdf.createQuad(null, subject, predicate, object);
System.out.println(otherQuad.getGraphName().isPresent());
```
@@ -769,7 +774,7 @@ BlankNodeOrIRI g = quad.getGraphName().orElse(null);
if (g == null) {
System.out.println("In default graph");
}
-factory.createQuad(g,s,p,o);
+rdf.createQuad(g,s,p,o);
```
@@ -810,13 +815,13 @@ System.out.println(quadAsTriple.equals(otherQuad.asTriple());
> `true`
To create a triple from a quad, you will need to use
-[RDFFactory.createQuad](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+[RDF.createQuad](apidocs/org/apache/commons/rdf/api/RDF.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
providing the desired graph name:
```
Triple t; // ..
BlankNodeOrIRI g; // ..
-Quad q = factory.createQuad(g, t.getSubject(), t.getPredicate(), t.getObject());
+Quad q = rdf.createQuad(g, t.getSubject(), t.getPredicate(), t.getObject());
```
@@ -867,11 +872,11 @@ A [graph](http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph)
is a collection of triples.
To create a [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) instance
-from a `RDFFactory`, use
-[createGraph()](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createGraph--):
+from a `RDF` implementation, use
+[createGraph()](apidocs/org/apache/commons/rdf/api/RDF.html#createGraph--):
```java
-Graph graph = factory.createGraph();
+Graph graph = rdf.createGraph();
```
Implementations will typically also have other ways of retrieving a `Graph`,
@@ -892,9 +897,9 @@ _subject/predicate/object_ form of
[Graph.add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
```java
-IRI bob = factory.createIRI("http://example.com/bob");
-IRI nameIri = factory.createIRI("http://example.com/name");
-Literal bobName = factory.createLiteral("Bob");
+IRI bob = rdf.createIRI("http://example.com/bob");
+IRI nameIri = rdf.createIRI("http://example.com/name");
+Literal bobName = rdf.createLiteral("Bob");
graph.add(bob, nameIRI, bobName);
```
@@ -1037,11 +1042,11 @@ A [dataset](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
is a collection of quads, or if you like, a collection of `Graph`s.
To create a [Dataset](apidocs/org/apache/commons/rdf/api/Dataset.html) instance
-from a `RDFFactory`, use
-[createDataset()](apidocs/org/apache/commons/rdf/api/RDFFactory.html#createDataset--):
+from a `RDF` implementation, use
+[createDataset()](apidocs/org/apache/commons/rdf/api/RDF.html#createDataset--):
```java
-Dataset dataset = factory.createDataset();
+Dataset dataset = rdf.createDataset();
```
Implementations will typically also have other ways of retrieving a `Dataset`,
@@ -1065,7 +1070,7 @@ dataset.remove(quad);
The convenience method [add(g,s,p,o)](apidocs/org/apache/commons/rdf/api/Dataset.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-) take an additional `BlankNodeOrIRI` parameter for the
-graph name - matching `RDFFactory.createQuad(g,s,p,o)`.
+graph name - matching `RDF.createQuad(g,s,p,o)`.
Note that the expanded pattern methods like [contains(g,s,p,o)](apidocs/org/apache/commons/rdf/api/Dataset.html#contains-java.util.Optional-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-) and
[stream(g,s,p,o)](apidocs/org/apache/commons/rdf/api/Dataset.html#stream-java.util.Optional-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-) uses `null` as a wildcard pattern, and
@@ -1073,7 +1078,7 @@ therefore an explicit _graph name_ parameter must be supplied as [Optional.empty
or wrapped using [Optional.of(g)](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#of-T-):
```
-Literal foo = factory.createLiteral("Foo");
+Literal foo = rdf.createLiteral("Foo");
// Match Foo in any graph, any subject, any predicate
if (dataset.contains(null, null, null, foo)) {
System.out.println("Foo literal found");
@@ -1085,7 +1090,7 @@ if (dataset.contains(Optional.empty(), null, null, foo)) {
}
-BlankNodeOrIRI g1 = factory.createIRI("http://example.com/graph1");
+BlankNodeOrIRI g1 = rdf.createIRI("http://example.com/graph1");
// Match Foo in named graph, any subject, any predicate
if (dataset.contains(Optional.of(g1), null, null, foo)) {
System.out.println("Foo literal found in default graph");
@@ -1110,7 +1115,7 @@ It is possible to retrieve these graphs from a `Dataset` using:
```
Graph defaultGraph = dataset.getGraph();
-BlankNodeOrIRI graphName = factory.createIRI("http://example.com/graph");
+BlankNodeOrIRI graphName = rdf.createIRI("http://example.com/graph");
Optional<Graph> otherGraph = dataset.getGraph(graphName);
```
@@ -1198,43 +1203,44 @@ is a set of Java interfaces, which can be implemented by several Java RDF
frameworks. See the [implementations](implementations.html) 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` - 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 defines a `RDF` interface as a factory for
+using a particular implementations' `RDFTerm`, `Triple`, `Quad`,
+`Graph` and `Dataset`. The `RDF` implementations
+also add adapter/converter methods to facilitate interoperability with their
+underlying framework's API.
-Commons RDF provides a `RDFFactory` 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).
+Note that some RDF frameworks have several possibilities for creating a backend
+for a `Graph` or `Dataset`, which configuration is implementation-specific.
### 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:
+While different frameworks have their own classes implementing the Commons
+RDF interfaces, Commons RDF objects are cross-compatible. Thus a
+client is able to mix and match objects from multiple implementations:
```java
-import com.example.foo.FooRDFFactory;
-import net.example.bar.BarGraph;
+import org.apache.commons.rdf.rdf4j.RDF4J;
+import org.apache.commons.rdf.jena.JenaRDF;
+
+RDF rdf4j = new RDF4J();
+JenaRDF jena = new JenaRDF();
+
+JenaGraph jenaGraph = jena.createGraph();
+// Jena-specific load method
+jenaGraph.asJenaModel().read("dataset.ttl");
-RDFFactory fooFactory = new FooRDFFactory();
-FooGraph g1 = (FooGraph) fooFactory.createGraph();
-// Foo-specific load method
-g1.load("dataset.ttl");
// Another Graph, from a different implementation
-Graph g2 = new BarGraph("localhost", 1337);
+Graph rdf4jGraph = rdf4j.createGraph();
-// Any factory can be used
-IRI iri1 = fooFactory.createIRI("http://example.com/property1");
+// Any RDF implementation can make RDFTerms
+IRI rdfIRI = rdf4j.createIRI("http://example.com/property1");
+// and used added to a different implementation's
+jenaGraph.add(rdfIRI,rdfIRI,rdfIRI);
// Both Triple and RDFTerm instances can be used
-//
+// with interoperability
for (Triple t1: g1.stream(null, iri1, null)) {
if (g2.contains(t1.getSubject(), null, t1.getObject())) {
g2.remove(t1);
@@ -1242,24 +1248,29 @@ for (Triple t1: g1.stream(null, iri1, null)) {
}
```
-_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](apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--).
- See
-[COMMONSRDF-15](https://issues.apache.org/jira/browse/COMMONSRDF-15)._
-
-The `.equals()` methods of `RDFTerm` interfaces are explicitly defined, so
-their instances can be compared across implementations.
+It is however generally recommended to use the matching `RDF` implementation
+for operations on a `Graph` or `Dataset` as it avoids unnecessary
+conversion round-trips.
_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._
+specific types, e.g. using the appropriate adapter method from the
+desired `RDF` implementation._
+
+The `.equals()` methods of `RDFTerm`, `Triple` and `Quad`
+are explicitly defined, so their instances can be compared
+across implementations, and thus can safely
+be used for instance as keys in a `java.util.Map` or `java.util.Set`.
+
+_Note: Special care might need to be taken for cross-interoperability of
+`BlankNode` instances. While multiple triples/quads with the same
+"foreign" `BlankNode` can be added without breaking their
+connections, the `Graph`/`Quad` is not required to
+**return** blank node instances that `.equals()` those previously
+inserted - specifically implementations are **not** expected to persist the
+blank node [uniqueReference](apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--)._
## Complete example