GitHub user stain opened a pull request:
https://github.com/apache/incubator-commonsrdf/pull/19
Add Quad and Dataset
As [discussed on
dev](http://mail-archives.apache.org/mod_mbox/incubator-commonsrdf-dev/201604.mbox/%3CCAMBJEmVTP27fb-sxqTgJgJ5YP6ZKAjaWobOpWiyTbE%2BOPfODtw%40mail.gmail.com%3E)
it would be good to have a `Quad` and `Dataset` types added, corresponding to
the [RDF concept
Dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset) and [Quad
semantics](https://www.w3.org/TR/2014/NOTE-rdf11-datasets-20140225/#quad-semantics).
Generated Javadocs from this branch of the new interfaces:
http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Quad.html
http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Dataset.html
http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/GraphOrDataset.html
http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/TripleOrQuad.html
The discussion on dev concluded that although Quad looks like Triple
(`getSubject()` `getPredicate()` and `getObject()` - a Quad necessarily have
different `.equals()` semantics. Allowing a Quad to pretend it is a Triple
leads to some murky equivalence questions - so instead this branch rather makes
a common interface `TripleOrQuad` (modelled after `BlankNodeOrIRI`) which
contains the subject/predicate/object methods - while `Triple` and `Quad` have
different equals - that is
[Quad.equals](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-)
require to also match on
[getGraphName](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Quad.html#getGraphName--).
I modelled
[getGraphName](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Quad.html#getGraphName--)
as an `Optional<BlankNodeOrIRI` - where `Optional.empty()` represents the
default graph. An alternative would be to make a `DEFAULT_GRAPH`
BlankNodeOrIRI constant -- but should this have a `ntriplesString()==null` - or
would we need yet another upper interface, `BlankNodeOrIRIOrDefaultGraph` ?
The use of `Optional` makes it a bit inconsistent in `Dataset` if we also
follow the advice that `Optional` should not normally appear as a parameter
argument - -
[Dataset.add](http://stain.github.io/incubator-commonsrdf/quad/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-)
uses `graphName=null` to indicate the default graph - while in
[contains](http://stain.github.io/incubator-commonsrdf/quad/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
[remove](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Dataset.html#remove-java.util.Optional-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
we use `null` as a wildcard, and
`Optional.empty()` to mean the empty graph.
If we also have an equivalent common interface
[GraphOrDataset](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/GraphOrDataset.html)
- and allow the expanded filter methods in there, then those would operate on
the default graph in the Dataset. Thus you would have two routes to filter on
the default graph.
We can reduce which methods should be included in GraphOrDataset - to only
have the generic `T`-typed methods - and not force
[getTriples()](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/GraphOrDataset.html#getTriples--)
onto Dataset - where it would need to call
[Quad.asTriple](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/Quad.html#asTriple--)
to return `Triple` instances.
## Upper interfaces
The two "ducktyping" interfaces
[GraphOrDataset](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/GraphOrDataset.html)
and
[TripleOrQuad](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/TripleOrQuad.html)
could be removed as their signatures are duplicated in `Graph` and `Dataset` -
I intended them for any kind of generic usage that can handle both Graph and
Dataset - e.g. parsers and serializers.
[TripleOrQuad](http://stain.github.io/incubator-commonsrdf/quad/org/apache/commons/rdf/api/TripleOrQuad.html)
could be generalized to return `RDFTerm` on all of `getSubject()`,
`getPredicate()` and `getObject()` - I know both Jena and JSON-LD can
potentially have generalized RDF triples. But this could be out of scope and
force additional casting for anyone using `TripleOrQuad` interface.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/apache/incubator-commonsrdf quad
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-commonsrdf/pull/19.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #19
----
commit 7639fd7c9de649361a7eaeeb3c9d8b620dc54afc
Author: Stian Soiland-Reyes <[email protected]>
Date: 2016-04-08T13:24:11Z
Add Quad and TripleOrQuad
commit 93f99826ac704d7804e78fe3e2dcbd7604614ace
Author: Stian Soiland-Reyes <[email protected]>
Date: 2016-04-08T13:25:09Z
GraphOrDataset superinterface
commit 63745d33b66d0ff28ab54e0c8edf65d76dbab931
Author: Stian Soiland-Reyes <[email protected]>
Date: 2016-04-08T13:25:49Z
Added Dataset (copy-paste of Graph)
commit 5e952b5f6e1b9fdf95fb0f4ae2e83470e4169f0d
Author: Stian Soiland-Reyes <[email protected]>
Date: 2016-04-08T13:52:44Z
added createDataset() and createQuad()
commit 220f75f19f3dfb730a9626292ac25e11807f4f31
Author: Stian Soiland-Reyes <[email protected]>
Date: 2016-04-08T14:13:16Z
javadoc typos
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
