COMMONSRDF-37 Describe Quad/Dataset updated UML diagram
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/25663998 Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/25663998 Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/25663998 Branch: refs/heads/rdf4j Commit: 25663998f086c802c76114b3bed8edb6dfdf0307 Parents: d7e4cbe Author: Stian Soiland-Reyes <st...@apache.org> Authored: Wed Sep 7 03:22:54 2016 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Wed Sep 7 03:22:54 2016 +0100 ---------------------------------------------------------------------- src/site/markdown/index.md | 58 ++++++++++++++----- src/site/resources/images/class-diagram.nomnoml | 49 +++++++++++++--- src/site/resources/images/class-diagram.png | Bin 57632 -> 56161 bytes 3 files changed, 85 insertions(+), 22 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/25663998/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 4e01ed6..71b0b68 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -61,25 +61,58 @@ which may be included in Commons RDF, specifically: * [Graph](apidocs/index.html?org/apache/commons/rdf/api/Graph.html): a graph, a set of RDF triples. * [Triple](apidocs/index.html?org/apache/commons/rdf/api/Triple.html): a - `(subject, predicate, object)` RDF triple. -* [RDFTerm](apidocs/index.html?org/apache/commons/rdf/api/RDFTerm.html): a RDF 1.1 - Term, where IRIs, literals and blank nodes are collectively known as RDF terms. + RDF triple with `getSubject()`, `getPredicate()`, `getObject()`. +* [Dataset](apidocs/index.html?org/apache/commons/rdf/api/Dataset.html): a dataset, + of RDF quads (or if you like, a set of named graphs). +* [Quad](apidocs/index.html?org/apache/commons/rdf/api/Quad.html): a + RDF quad with with `getGraphName()`, `getSubject()`, `getPredicate()`, `getObject()`. +* [RDFTerm](apidocs/index.html?org/apache/commons/rdf/api/RDFTerm.html): any RDF 1.1 + Term which can be part of a Triple or Quad. + IRIs, literals and blank nodes are collectively known as RDF terms. * [IRI](apidocs/index.html?org/apache/commons/rdf/api/IRI.html): an - Internationalized Resource Identifier. + Internationalized Resource Identifier (e.g. representing `<http://example.com/>`) * [BlankNode](apidocs/index.html?org/apache/commons/rdf/api/BlankNode.html): a - RDF-1.1 Blank Node, where they are disjoint from IRIs and literals. + RDF-1.1 Blank Node, e.g. representing `_:b1`. Disjoint from IRIs and literals. * [BlankNodeOrIRI](apidocs/index.html?org/apache/commons/rdf/api/BlankNodeOrIRI.html): this interface represents the RDF Terms that may be used in the subject position of an RDF 1.1 `Triple`, including `BlankNode` and `IRI`. -* [Literal](apidocs/index.html?org/apache/commons/rdf/api/Literal.html): a RDF-1.1 literal. -* [RDFTermFactory](apidocs/index.html?org/apache/commons/rdf/api/RDFTermFactory.html): - factory for creating `RDFTerm` and `Graph` instances. +* [Literal](apidocs/index.html?org/apache/commons/rdf/api/Literal.html): a RDF-1.1 literal, e.g. + representing `"Hello there"@en`. The design of the [API](apidocs/index.html?org/apache/commons/rdf/api/package-summary.html) follows the terminology as defined by [RDF 1.1 Concepts and Abstract Syntax](http://www.w3.org/TR/rdf11-concepts/), a W3C Recommendation published on 25 February 2014. The idea is that Commons RDF -will provide a common library for RDF 1.1 that could be implemented by systems -on the Java Virtual Machine, allowing the portability across different implementations. +provide a common library for RDF 1.1 with multiple implementions for +the Java Virtual Machine, allowing the portability across different +Commons RDF implementations. + + +Commons RDF is designed for compatibility between different +[implementations](implementations.html), e.g. by defining +strong equality and hash code semantics (e.g. for +[triple](apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-) +and [literals](fapidocs/org/apache/commons/rdf/api/Literal.html#equals-java.lang.Object-) ); +this allows users of Commons RDF to "mix and match", for instance querying a `FooGraphImpl` +and directly adding its `FooTripleImpl`s to a `BarGraphImpl` without any +explicit convertion. + +To create such instances without hard-coding an implementation, one can use: + +* [RDFTermFactory](apidocs/index.html?org/apache/commons/rdf/api/RDFTermFactory.html): + factory interface for creating instances of the above types + (e.g. `LiteralImpl` and `GraphImpl`). + + +The API also includes a couple of "upper" interfaces which do not have +the above equality semantics and bridge the graph/quad duality: + +* [TripleLike](apidocs/index.html?org/apache/commons/rdf/api/TripleLike.html): + common super-interface of `Triple` and `Quad` (also a generalised triple). +* [QuadLike](apidocs/index.html?org/apache/commons/rdf/api/QuadLike.html): + a `TripleLike` that also has `getGraphName()` (a generalized quad) +* [GraphLike](apidocs/index.html?org/apache/commons/rdf/api/GraphLike.html): + common super-interface of `Graph` and `Dataset`. + See the the [user guide](userguide.html) for examples of how to interact with these interfaces. @@ -98,9 +131,8 @@ where version `x.y.z` of `Simple` implements version `x.y` of the `API`; i.e., the version `z` are backwards-compatible patches of the implementation. -External [implementations of the Commons RDF API](implementations.html) are -being developed as part of their retrospective projects. -[Contributions welcome!](contributing.html) +[Implementations of the Commons RDF API](implementations.html) are +being developed as additional modules. [Contributions welcome!](contributing.html) ## Contributing http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/25663998/src/site/resources/images/class-diagram.nomnoml ---------------------------------------------------------------------- diff --git a/src/site/resources/images/class-diagram.nomnoml b/src/site/resources/images/class-diagram.nomnoml index b309423..67278bf 100644 --- a/src/site/resources/images/class-diagram.nomnoml +++ b/src/site/resources/images/class-diagram.nomnoml @@ -17,12 +17,43 @@ // To render, see http://www.nomnoml.com #fill: #bbccdd; #aabbcc -[<abstract>RDFTermFactory]--[<abstract>Graph] -[RDFTermFactory]--[<abstract>Triple] -[RDFTermFactory]--[<abstract>RDFTerm] -[Graph]->[Triple] -[Triple]->[RDFTerm] -[RDFTerm]<:-[<abstract>Literal] -[RDFTerm]<:-[<abstract>BlankNodeOrIRI] -[BlankNodeOrIRI]<:-[<abstract>BlankNode] -[BlankNodeOrIRI]<:-[<abstract>IRI] +#title: class-diagram + +#.like: fill=#fff italics + + +[<like>GraphLike] +[<like>TripleLike] +[<like>QuadLike] + +[<like>RDFTerm] +[<like>BlankNodeOrIRI] + +[<abstract>Graph] +[<abstract>Dataset] +[<abstract>Triple] +[<abstract>Quad] +[<abstract>Graph] + + +[<abstract>Literal] +[<abstract>IRI] +[<abstract>BlankNode] + +[GraphLike] -> 0..* [TripleLike] +[GraphLike]<:-[Graph] +[GraphLike]<:-[Dataset] +[Graph] -> 0..* [Triple] +[Dataset] -> 0..* [Quad] +[Triple] -> 3 [RDFTerm] +[Quad]->4 [RDFTerm] +[<abstract>TripleLike]<:-[Triple] +[<abstract>QuadLike]<:-[Quad] +[TripleLike]<:-[QuadLike] +[RDFTerm]<:-[Literal] +[RDFTerm]<:-[BlankNodeOrIRI] +[BlankNodeOrIRI]<:-[BlankNode] +[BlankNodeOrIRI]<:-[IRI] + +#.factory: fill=#ccbbdd italics +[<factory>RDFTermFactory||createGraph()|createDataset()|createTriple(..)|createQuad(..)|..] http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/25663998/src/site/resources/images/class-diagram.png ---------------------------------------------------------------------- diff --git a/src/site/resources/images/class-diagram.png b/src/site/resources/images/class-diagram.png index 16b9c3b..b725b65 100644 Binary files a/src/site/resources/images/class-diagram.png and b/src/site/resources/images/class-diagram.png differ