Mailing-List: contact commits-help@commonsrdf.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commonsrdf.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: stain@apache.org
To: commits@commonsrdf.incubator.apache.org
Date: Wed, 07 Sep 2016 02:23:51 -0000
Message-Id: <e4efdf44bcca4cf5aacef9d24a2a0232@git.apache.org>
In-Reply-To: <21f9d5f8460b4aa98b7763218cd8054a@git.apache.org>
References: <21f9d5f8460b4aa98b7763218cd8054a@git.apache.org>
Subject: [5/6] incubator-commonsrdf git commit: COMMONSRDF-37 Describe
 Quad/Dataset
archived-at: Wed, 07 Sep 2016 02:23:55 -0000

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/master
Commit: 25663998f086c802c76114b3bed8edb6dfdf0307
Parents: d7e4cbe
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Wed Sep 7 03:22:54 2016 +0100
Committer: Stian Soiland-Reyes <stain@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