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/18 11:36:41 UTC
[1/5] incubator-commonsrdf git commit: about quads
Repository: incubator-commonsrdf
Updated Branches:
refs/heads/master f2de2c507 -> 5aa8d6cb7
about quads
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/425be6e8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/425be6e8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/425be6e8
Branch: refs/heads/master
Commit: 425be6e805cfcb9add9233bdc2fe3e403c2a112b
Parents: f2de2c5
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Oct 18 10:15:32 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Oct 18 10:15:32 2016 +0100
----------------------------------------------------------------------
examples/src/example/UserGuideTest.java | 43 ++++++++++
src/site/markdown/userguide.md | 112 ++++++++++++++++++++++++++-
2 files changed, 154 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/425be6e8/examples/src/example/UserGuideTest.java
----------------------------------------------------------------------
diff --git a/examples/src/example/UserGuideTest.java b/examples/src/example/UserGuideTest.java
index 3849b53..ee8ad97 100644
--- a/examples/src/example/UserGuideTest.java
+++ b/examples/src/example/UserGuideTest.java
@@ -29,9 +29,12 @@ import org.apache.commons.rdf.api.BlankNodeOrIRI;
import org.apache.commons.rdf.api.Graph;
import org.apache.commons.rdf.api.IRI;
import org.apache.commons.rdf.api.Literal;
+import org.apache.commons.rdf.api.Quad;
+import org.apache.commons.rdf.api.QuadLike;
import org.apache.commons.rdf.api.RDFTerm;
import org.apache.commons.rdf.api.RDFTermFactory;
import org.apache.commons.rdf.api.Triple;
+import org.apache.commons.rdf.api.TripleLike;
import org.apache.commons.rdf.simple.SimpleRDFTermFactory;
import org.apache.commons.rdf.simple.Types;
import org.junit.Before;
@@ -150,9 +153,49 @@ public class UserGuideTest {
System.out.println(type);
}
+ // Equal triples must have same s,p,o
System.out.println(triple.equals(factory.createTriple(subj, pred, obj)));
}
+ @Test
+ public void quad() throws Exception {
+ 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);
+
+ Optional<BlankNodeOrIRI> g = quad.getGraphName();
+ if (g.isPresent()) {
+ System.out.println(g.get().ntriplesString());
+ }
+
+ BlankNodeOrIRI subj = quad.getSubject();
+ System.out.println(subj.ntriplesString());
+
+ // null means default graph
+ Quad otherQuad = factory.createQuad(null, subject, predicate, object);
+ // Equal quads must have same g,s,p,o
+ System.out.println(quad.equals(otherQuad));
+
+ // all quads can be viewed as triples - "stripping" the graph
+ Triple asTriple = quad.asTriple();
+ Triple otherAsTriple = quad.asTriple();
+ System.out.println(asTriple.equals(otherAsTriple));
+
+ // NOTE: Quad does NOT extend Triple, however both Triple and Quad
+ // extend TripleLike
+
+ TripleLike a = quad;
+ TripleLike b = quad.asTriple();
+ // Unlike Triple and Quad, TripleLike does not mandate any .equals(),
+ // it just provides common access to getSubject(), getPredicate(), getObject()
+
+
+ // TripleLike supports generalized RDF - therefore all s/p/o are of type RDFTerm
+ RDFTerm s = a.getSubject();
+ }
+
@Test
public void graph() throws Exception {
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/425be6e8/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 33ca66a..13ff828 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -697,7 +697,117 @@ Commons RDF represents such statements using the class [Quad](apidocs/org/apache
* The [object](apidocs/org/apache/commons/rdf/api/Quad.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)
* 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`
-The graph name is represented as an [Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html?is-external=true), where `Optional.empty()` indicates that the quad is in the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph)
+
+To create a `Quad`, use [createQuad](apidocs/org/apache/commons/rdf/api/RDFTermFactory.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);
+```
+
+The subject, predicate and object are accessible just like in a `Triple`:
+
+```
+BlankNodeOrIRI subj = quad.getSubject();
+System.out.println(subj.ntriplesString());
+```
+
+### Graph name
+
+In addition the _graph name_ is accessible using
+[getGraphName()](apidocs/org/apache/commons/rdf/api/Quad.html#getGraphName--):
+
+```
+Optional<BlankNodeOrIRI> g = quad.getGraphName();
+if (g.isPresent()) {
+ System.out.println(g.get().ntriplesString());
+}
+```
+
+The graph name is represented as an [Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html?is-external=true), where `Optional.empty()` indicates that the quad is in the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph), or
+`g.get()` retrieves the `BlankNodeOrIRI`.
+
+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 equality
+
+A `Quad` is considered
+[equal](apidocs/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-)
+to another `Quad` if each of the graph name, subject, predicate and
+object are also equal:
+
+```
+System.out.println(quad.equals(otherQuad));
+```
+
+> `false`
+
+
+### Converting quads to triples
+
+All quads can be viewed as triples - in a way "stripping" the graph name:
+
+```
+Triple quadAsTriple = quad.asTriple();
+```
+
+This can be utilized to compare quads at triple-level (considering just s/p/o):
+
+```
+System.out.println(quadAsTriple.equals(otherQuad.asTriple());
+```
+
+> `true`
+
+
+
+### TripleLike
+
+Note that the class [Quad](apidocs/org/apache/commons/rdf/api/Quad.html)
+does **not** extend the class
+[Triple](apidocs/org/apache/commons/rdf/api/Triple.html),
+as they have different equality semantics.
+
+Both `Triple` and `Quad` do however extend the "duck-typing" interface
+[TripleLike](apidocs/org/apache/commons/rdf/api/TripleLike.html):
+
+
+```
+TripleLike a = quad;
+TripleLike b = quad.asTriple();
+```
+
+Unlike Triple and Quad, TripleLike does not mandate any specific
+`.equals()`, it just provides common access to
+[getSubject()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getSubject--)
+[getPredicate()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getPredicate--) and
+[getObject()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getObject--).
+
+
+TripleLike can also be used for
+[generalized RDF](https://www.w3.org/TR/rdf11-concepts/#section-generalized-rdf)
+therefore all of these are return as [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html).
+
+```
+RDFTerm s = a.getSubject();
+RDFTerm p = a.getPredicate();
+RDFTerm o = a.getObject();
+```
+
+For generalized quads there is also the
+[QuadLike](apidocs/org/apache/commons/rdf/api/QuadLike.html) interface that
+adds
+[getGraphName()](apidocs/org/apache/commons/rdf/api/QuadLike.html#getGraphName--)
+as an `Optional<T extends RDFTerm>`.
+
## Graph
[4/5] incubator-commonsrdf git commit: about dataset
Posted by st...@apache.org.
about dataset
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/3bbe8051
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/3bbe8051
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/3bbe8051
Branch: refs/heads/master
Commit: 3bbe8051771ee698078d0475ca8ba4b67c648119
Parents: 86a3b51
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Oct 18 10:57:52 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Oct 18 10:57:52 2016 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 43 +++++++++++++++++++++++++++++++++++++
1 file changed, 43 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/3bbe8051/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index f1da36b..9901a56 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -1073,6 +1073,49 @@ if (dataset.contains(Optional.of(g1), null, null, foo)) {
```
+### Graphs in the dataset
+
+An [RDF Dataset](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
+is defined as:
+
+> An RDF dataset is a collection of RDF graphs, and comprises:
+
+> * Exactly one default graph, being an RDF graph. The default graph does not have a name and may be empty.
+> * Zero or more named graphs. Each named graph is a pair consisting of an IRI or a blank node (the graph name), and an RDF graph. Graph names are unique within an RDF dataset.
+
+It is possible to retrieve these graphs from a `Dataset` using:
+
+* [getGraph()](apidocs/org/apache/commons/rdf/api/Dataset.html#getGraph--) for the _default graph_
+* [getGraph(blankNodeOrIRI)](apidocs/org/apache/commons/rdf/api/Dataset.html#getGraph-org.apache.commons.rdf.api.BlankNodeOrIRI-) for a named graph
+
+```
+Graph defaultGraph = dataset.getGraph();
+BlankNodeOrIRI graphName = factory.createIRI("http://example.com/graph");
+Optional<Graph> otherGraph = dataset.getGraph(graphName);
+```
+
+These `Graph`s provide a `Triple` **view** onto the `Quad`s in the `Dataset`:
+
+```
+System.out.println(defaultGraph.contains(otherQuad.asTriple()));
+System.out.println(defaultGraph.size());
+```
+
+> `true`
+> `1`
+
+It is unspecified if modifications to the returned Graph are
+reflected in the Dataset.
+
+Note that it is unspecified if requesting an unknown graph name will
+return `Optional.empty()` or create a new (empty) `Graph`.
+
+Some implementations may also support a _union graph_, a `Graph` that contains
+all triples regardless of their graph names. _simple_ provides
+[DatasetGraphView](apidocs/org/apache/commons/rdf/simple/DatasetGraphView.html)
+which can be used with any `Dataset` for this purpose.
+
+
## Mutability and thread safety
[5/5] incubator-commonsrdf git commit: markdown fixes
Posted by st...@apache.org.
markdown fixes
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/5aa8d6cb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/5aa8d6cb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/5aa8d6cb
Branch: refs/heads/master
Commit: 5aa8d6cb7123da5505cd587e067ad70562938ebd
Parents: 3bbe805
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Oct 18 12:36:05 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Oct 18 12:36:05 2016 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 50 ++++++++++++++++++++++++++-----------
1 file changed, 35 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5aa8d6cb/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 9901a56..a18436d 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -671,7 +671,7 @@ In Commons RDF, `BlankNodeOrIRI` instances are always one of `BlankNode` or
A `Triple` is considered
[equal](apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-)
-to another `Triple` if each of their subject, predicate and object are also
+to another `Triple` if each of their subject, predicate and object are
equal:
```java
@@ -721,7 +721,7 @@ System.out.println(pred.ntriplesString());
### Graph name
-In addition the _graph name_ is accessible using
+The quad's _graph name_ is accessible using
[getGraphName()](apidocs/org/apache/commons/rdf/api/Quad.html#getGraphName--):
```
@@ -743,7 +743,6 @@ if (g.isPresent()) {
> `<http://example.com/graph>`
-
To create a quad in the _default graph_, supply `null` as the graph name
to the factory method:
@@ -762,6 +761,17 @@ Java 8 functional programming patterns like:
String str = quad.map(BlankNodeOrIRI::ntriplesString).orElse("");
```
+As the `createQuad` method does not expect an `Optional`, you might
+use this `orElse` pattern to represent the default graph as `null`:
+
+```
+BlankNodeOrIRI g = quad.getGraphName().orElse(null);
+if (g == null) {
+ System.out.println("In default graph");
+}
+factory.createQuad(g,s,p,o);
+```
+
Care should be taken with regards when accessing
graph named with `BlankNode`s,
@@ -774,7 +784,7 @@ as the graph name will be compared using
A `Quad` is considered
[equal](apidocs/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-)
to another `Quad` if each of the graph name, subject, predicate and
-object are also equal:
+object are equal:
```
System.out.println(quad.equals(otherQuad));
@@ -799,6 +809,16 @@ System.out.println(quadAsTriple.equals(otherQuad.asTriple());
> `true`
+To create a triple from a quad, you will need to use
+[RDFTermFactory.createQuad](apidocs/org/apache/commons/rdf/api/RDFTermFactory.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());
+```
+
### TripleLike
@@ -808,7 +828,7 @@ does **not** extend the class
[Triple](apidocs/org/apache/commons/rdf/api/Triple.html),
as they have different equality semantics.
-Both `Triple` and `Quad` do however extend the "duck-typing" interface
+Both `Triple` and `Quad` do however share a common "duck-typing" interface
[TripleLike](apidocs/org/apache/commons/rdf/api/TripleLike.html):
@@ -817,26 +837,26 @@ TripleLike a = quad;
TripleLike b = quad.asTriple();
```
-Unlike Triple and Quad, TripleLike does not mandate any specific
+Unlike `Triple` and `Quad`, `TripleLike` does not mandate any specific
`.equals()`, it just provides common access to
[getSubject()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getSubject--)
[getPredicate()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getPredicate--) and
[getObject()](apidocs/org/apache/commons/rdf/api/TripleLike.html#getObject--).
-TripleLike can also be used for
-[generalized RDF](https://www.w3.org/TR/rdf11-concepts/#section-generalized-rdf)
-therefore all of these are return as [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html).
-
```
RDFTerm s = a.getSubject();
RDFTerm p = a.getPredicate();
RDFTerm o = a.getObject();
```
-For generalized quads there is also the
-[QuadLike](apidocs/org/apache/commons/rdf/api/QuadLike.html) interface that
-adds
+TripleLike can also be used for
+[generalized RDF](https://www.w3.org/TR/rdf11-concepts/#section-generalized-rdf)
+therefore all of its parts are returned as [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html).
+
+For generalized quads the
+[QuadLike](apidocs/org/apache/commons/rdf/api/QuadLike.html) interface extends `TripleLike` to
+add
[getGraphName()](apidocs/org/apache/commons/rdf/api/QuadLike.html#getGraphName--)
as an `Optional<T extends RDFTerm>`.
@@ -1050,7 +1070,7 @@ graph name - matching `RDFTermFactory.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
therefore an explicit _graph name_ parameter must be supplied as [Optional.empty()](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#empty--) (default graph)
-or wrapped using [Optional.of(blankNodeOrIRI](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#of-T-):
+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");
@@ -1094,7 +1114,7 @@ BlankNodeOrIRI graphName = factory.createIRI("http://example.com/graph");
Optional<Graph> otherGraph = dataset.getGraph(graphName);
```
-These `Graph`s provide a `Triple` **view** onto the `Quad`s in the `Dataset`:
+These provide a `Graph` **view** of the corresponding `Triple`s in the `Dataset`:
```
System.out.println(defaultGraph.contains(otherQuad.asTriple()));
[2/5] incubator-commonsrdf git commit: about Dataset
Posted by st...@apache.org.
about Dataset
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/7fec8388
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/7fec8388
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/7fec8388
Branch: refs/heads/master
Commit: 7fec8388f4454e9edde707f81915010ee63de4f5
Parents: 425be6e
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Oct 18 10:32:44 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Oct 18 10:32:44 2016 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 63 +++++++++++++++++++++++++++++++++++++
1 file changed, 63 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/7fec8388/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 13ff828..08d977b 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -979,6 +979,69 @@ System.out.println(graph.contains(null, null, null));
```
> `false`
+## Dataset
+
+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 `RDFTermFactory`, use
+[createDataset()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createDataset--):
+
+```java
+Dataset dataset = factory.createDataset();
+```
+
+Implementations will typically also have other ways of retrieving a `Dataset`,
+e.g. by parsing a JSON-LD file or connecting to a storage backend.
+
+### Dataset operations
+
+`Dataset` operations match their equivalent operations on `Graph`, except that
+methods like [add(q)](apidocs/org/apache/commons/rdf/api/Dataset.html#add-org.apache.commons.rdf.api.Quad-)
+and [remove(q)](apidocs/org/apache/commons/rdf/api/Dataset.html#remove-org.apache.commons.rdf.api.Quad-)
+use
+[Quad](apidocs/org/apache/commons/rdf/api/Quad.html) instead of `Triple`.
+
+```
+dataset.add(quad);
+System.out.println(dataset.contains(quad));
+dataset.remove(quad);
+```
+
+> `true`
+
+
+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 `RDFTermFactory.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
+therefore an explicit _graph name_ parameter must be supplied as [Optional.empty()](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#empty--) (default graph)
+or wrapped using [Optional.of(blankNodeOrIRI](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#of-T-):
+
+```
+Literal foo = factory.createLiteral("Foo");
+// Match Foo in any graph, any subject, any predicate
+if (dataset.contains(null, null, null, foo)) {
+ System.out.println("Foo literal found");
+}
+
+// Match Foo in default graph, any subject, any predicate
+if (dataset.contains(Optional.empty(), null, null, foo)) {
+ System.out.println("Foo literal found in default graph");
+}
+
+
+BlankNodeOrIRI g1 = factory.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");
+}
+```
+
+
+
## Mutability and thread safety
_Note: This section is subject to change - see discussion on [COMMONSRDF-7](https://issues.apache.org/jira/browse/COMMONSRDF-7)_
[3/5] incubator-commonsrdf git commit: about graphName() Optional
Posted by st...@apache.org.
about graphName() Optional
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/86a3b518
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/86a3b518
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/86a3b518
Branch: refs/heads/master
Commit: 86a3b518e68a4dbcecfc986410969886ad3e81a9
Parents: 7fec838
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Oct 18 10:44:18 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Oct 18 10:44:18 2016 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 44 ++++++++++++++++++++++++++++++++-----
1 file changed, 38 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/86a3b518/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 08d977b..f1da36b 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -48,6 +48,8 @@ Commons RDF [API](apidocs/).
* [Iterating over triples](#Iterating_over_triples)
* [Stream of triples](#Stream_of_triples)
* [Removing triples](#Removing_triples)
+* [Dataset](#Dataset)
+ * [Dataset operations](#Dataset_operations)
* [Mutability and thread safety](#Mutability_and_thread_safety)
* [Implementations](#Implementations)
* [Cross-compatibility](#Cross-compatibility)
@@ -711,10 +713,12 @@ Quad quad = factory.createQuad(graph, subject, predicate, object);
The subject, predicate and object are accessible just like in a `Triple`:
```
-BlankNodeOrIRI subj = quad.getSubject();
-System.out.println(subj.ntriplesString());
+IRI pred = quad.getPredicate();
+System.out.println(pred.ntriplesString());
```
+> `<http://example.com/says>`
+
### Graph name
In addition the _graph name_ is accessible using
@@ -722,21 +726,49 @@ In addition the _graph name_ is accessible using
```
Optional<BlankNodeOrIRI> g = quad.getGraphName();
+```
+
+The graph name is represented as an [Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html),
+where `Optional.empty()` indicates that the quad is in the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph), while
+if the [Optional.isPresent()](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#isPresent--) then the
+graph name `BlankNodeOrIRI` is accessible with `g.get()`:
+
+```
if (g.isPresent()) {
- System.out.println(g.get().ntriplesString());
+ BlankNodeOrIRI graphName = g.get();
+ System.out.println(graphName.ntriplesString());
}
```
-The graph name is represented as an [Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html?is-external=true), where `Optional.empty()` indicates that the quad is in the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph), or
-`g.get()` retrieves the `BlankNodeOrIRI`.
+> `<http://example.com/graph>`
+
-To create a quad in the default graph, supply `null` as the graph name
+
+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);
+System.out.println(otherQuad.getGraphName().isPresent());
```
+> `false`
+
+Note that a `Quad` will never return `null` on any of its getters, which is why
+the graph name is wrapped as an `Optional`. This also allows the use of
+Java 8 functional programming patterns like:
+
+```
+String str = quad.map(BlankNodeOrIRI::ntriplesString).orElse("");
+```
+
+
+Care should be taken with regards when accessing
+graph named with `BlankNode`s,
+as the graph name will be compared using
+[BlankNode's equality semantics](apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-).
+
+
### Quad equality
A `Quad` is considered