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
