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)_