You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2015/04/28 02:10:27 UTC
[1/4] incubator-commonsrdf git commit: User guide: nicer CSS style
for tt/code
Repository: incubator-commonsrdf
Updated Branches:
refs/heads/master d4f483d5f -> 70a1ab438
User guide: nicer CSS style for tt/code
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/393c1b97
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/393c1b97
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/393c1b97
Branch: refs/heads/master
Commit: 393c1b9730e9ce1e463c75c5458df57e37669e22
Parents: d4f483d
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Apr 27 23:41:00 2015 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Apr 27 23:41:00 2015 +0100
----------------------------------------------------------------------
src/site/site.xml | 31 ++++++++++++++++++-------------
1 file changed, 18 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/393c1b97/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index b589dd3..c7f0fc4 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -50,19 +50,24 @@
<body>
<head>
- <style type="text/css"><![CDATA[
-
- /* Override prettify.css, nicer fonts for code examples */
- .source .source pre {
- font-family: Monaco,Menlo,Consolas,Inconsolata,monospace;
- }
- /* COMMONSSITE-82 workaround */
- .nav-list li.collapsed a {
- background-repeat: no-repeat;
- background-position: 16px 9px;
- }
- ]]>
- </style>
+ <style type="text/css"><![CDATA[
+
+ /* Override prettify.css, nicer fonts for code examples */
+ .content .source pre {
+ font-family: Monaco,Menlo,Consolas,Inconsolata,monospace;
+ }
+ .content tt, .content code {
+ font-family: Monaco,Menlo,Consolas,Inconsolata,monospace;
+ color: #333;
+ }
+
+ /* COMMONSSITE-82 workaround */
+ .nav-list li.collapsed a {
+ background-repeat: no-repeat;
+ background-position: 16px 9px;
+ }
+ ]]>
+ </style>
</head>
<links>
<item name="Incubator" href="http://incubator.apache.org/" />
[4/4] incubator-commonsrdf git commit: User guide: About Triple
Posted by st...@apache.org.
User guide: About Triple
Also a draft about thread safety - some of this might
later be applicable to move into the actual Javadoc
in respect of https://issues.apache.org/jira/browse/COMMONSRDF-7
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/70a1ab43
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/70a1ab43
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/70a1ab43
Branch: refs/heads/master
Commit: 70a1ab43899d3edddae257d2f2a80327b63a34cf
Parents: e397475
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Apr 28 01:09:31 2015 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Apr 28 01:09:31 2015 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 143 +++++++++++++++++++++++++++++++++---
1 file changed, 134 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/70a1ab43/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index b177fc6..1c71d94 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -22,6 +22,7 @@ Commons RDF [API](apidocs/).
* [Iterating over triples](#Iterating_over_triples)
* [Stream of triples](#Stream_of_triples)
* [Removing triples](#Removing_triples)
+* [Mutability and thread safety](#Mutability_and_thread_safety)
## Using Commons RDF from Maven
@@ -510,14 +511,94 @@ System.out.println(literalDouble.getLanguageTag().isPresent());
## Triple
-**TODO:** [Triple](apidocs/org/apache/commons/rdf/api/Triple.html)
+A [triple](http://www.w3.org/TR/rdf11-concepts/#section-triples) in
+RDF 1.1 consists of:
+
+* The [subject](apidocs/org/apache/commons/rdf/api/Triple.html#getSubject--), which is an [IRI](apidocs/org/apache/commons/rdf/api/IRI.html) or a [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html)
+* The [predicate](apidocs/org/apache/commons/rdf/api/Triple.html#getPredicate--), which is an [IRI](apidocs/org/apache/commons/rdf/api/IRI.html)
+* The [object](apidocs/org/apache/commons/rdf/api/Triple.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)
+
+
+To construct a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html) from a
+`RDFTermFactory`, use
+[createTriple](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createTriple-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-):
+
+```java
+BlankNodeOrIRI subject = factory.createBlankNode();
+IRI predicate = factory.createIRI("http://example.com/says");
+RDFTerm object = factory.createLiteral("Hello");
+Triple triple = factory.createTriple(subject, predicate, object);
+```
+
+The subject of the triple can be retrieved
+using [getSubject](apidocs/org/apache/commons/rdf/api/Triple.html#getSubject--):
+
+```java
+BlankNodeOrIRI subj = triple.getSubject();
+System.out.println(subj.ntriplesString());
+```
+
+> `_:7b914fbe-aa2a-4551-b71c-8ac0e2b52b26`
+
+Likewise the predicate using
+[getPredicate](apidocs/org/apache/commons/rdf/api/Triple.html#getPredicate--):
+
+```java
+IRI pred = triple.getPredicate();
+System.out.println(pred.getIRIString());
+```
+> `http://example.com/says`
+
+Finally, the object of the triple is returned with
+[getObject](apidocs/org/apache/commons/rdf/api/Triple.html#getObject--):
+
+```java
+RDFTerm obj = triple.getObject();
+System.out.println(obj.ntriplesString());
+```
+
+> `"Hello"`
+
+For the subject and object you might find it useful to do
+Java type checking and casting from the types
+[BlankNodeOrIRI](apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html)
+and [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html):
+
+```java
+if (subj instanceof IRI) {
+ String s = ((IRI) subj).getIRIString();
+ System.out.println(s);
+}
+// ..
+if (obj instanceof Literal) {
+ IRI type = ((Literal) obj).getDatatype();
+ System.out.println(type);
+}
+```
+
+In Commons RDF, `BlankNodeOrIRI` instances are always one of `BlankNode` or
+`IRI`, and `RDFTerm` instances one of `BlankNode`, `IRI` or `Literal`.
+
+A `Triple` is considered
+[equal](apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-)
+to another `Triple` if each of their subject, predicate and object are also
+equal:
+
+```java
+System.out.println(triple.equals(factory.createTriple(subj, pred, obj)));
+```
+
+> `true`
+
## Graph
-A [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) is a collection of
-[Triple](apidocs/org/apache/commons/rdf/api/Triple.html)s.
+A [graph](http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph)
+is a collection of triples.
-To create a graph from a `RDFTermFactory`, use [createGraph()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--):
+To create a [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) instance
+from a `RDFTermFactory`, use
+[createGraph()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--):
```java
Graph graph = factory.createGraph();
@@ -531,9 +612,10 @@ e.g. by parsing a Turtle file or connecting to a storage backend.
_Note: Some `Graph` implementations are immutable, in which case the below
may throw an `UnsupportedOperationException`_.
-Given the [previous example](#Creating_RDFTerm_instances), we can
+Any [Triple](apidocs/org/apache/commons/rdf/api/Triple.html) can be added to the
+graph using the
[add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-)
-the triple to the graph:
+method:
```java
graph.add(triple);
@@ -563,7 +645,7 @@ System.out.println(graph.contains(triple));
```
> `true`
-The expanded subject/predicate/object call for [Graph.contains()](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+The expanded _subject/predicate/object_ call for [Graph.contains()](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
can be used without needing to create a `Triple` first, and also
allow `null` as a wildcard parameters:
@@ -582,8 +664,6 @@ System.out.println(graph.size());
```
> `2`
-_Note: In some implementations with large graphs, calculating the size can be an
-expensive operation._
### Iterating over triples
@@ -643,6 +723,7 @@ System.out.println(namedB.map(t -> t.getSubject()).findAny().get());
```
> `<http://example.com/bob>`
+
### Removing triples
_Note: Some `Graph` implementations are immutable, in which case the below
@@ -671,3 +752,47 @@ graph.clear();
System.out.println(graph.contains(null, null, null));
```
> false
+
+# Mutability and thread safety
+
+In Commons RDF, all instances of `Triple` and `RDFTerm` (e.g. `IRI`,
+`BlankNode`, `Literal`) are considered _immutable_. That is, their content does
+not change, and so calling a method like
+[IRI.getIRIString](apidocs/org/apache/commons/rdf/api/IRI.html#getIRIString--)
+or
+[Literal.getDatatype](apidocs/org/apache/commons/rdf/api/Literal.html#getDatatype--)
+will always have return values that are `.equal()` to any earlier return
+values. Being immutable, the `Triple` and `RDFTerm` types should be
+considered thread-safe.
+
+A `Graph` may be _mutable_, particular if it supports methods like
+[Graph.add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+and [Graph.remove](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-). That means that responses to methods like [size](apidocs/org/apache/commons/rdf/api/Graph.html#size--) and [contains](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-) might change during its lifetime.
+
+Implementations of Commons RDF may specify the (im)mutability of `Graph` in further details. If a graph is immutable, the methods `add` and `remove` may throw a `UnsupportedOperationException`.
+
+Commons RDF does not specify if methods on a `Graph` are thread-safe. Iterator
+methods like [iterate](apidocs/org/apache/commons/rdf/api/Graph.html#iterate--)
+and [getTriples](apidocs/org/apache/commons/rdf/api/Graph.html#getTriples-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+might throw a
+[ConcurrentModificationException](http://docs.oracle.com/javase/8/docs/api/java/util/ConcurrentModificationException.html)
+if it detects a thread concurrency modification, although this behaviour is not guaranteed.
+Implementations of Commons RDF may specify more specific thread-safety considerations.
+
+If an implementation does not specify any thread-safety support, then all
+potentially concurrent access to a `Graph` must be `synchronized`, e.g.:
+
+```java
+Graph graph;
+// ...
+synchronized(graph) {
+ graph.add(triple);
+}
+// ...
+synchronized(graph) {
+ for (Triple t : graph) {
+ // ...
+ }
+}
+```
+
[3/4] incubator-commonsrdf git commit: User guide: Graph section
moved to the end
Posted by st...@apache.org.
User guide: Graph section moved to the end
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/e3974754
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/e3974754
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/e3974754
Branch: refs/heads/master
Commit: e39747541e10f92c0d01dc18ce0b59a389b3f4b1
Parents: 6f17e31
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Tue Apr 28 00:05:49 2015 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Tue Apr 28 00:06:00 2015 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 385 ++++++++++++++++++------------------
1 file changed, 195 insertions(+), 190 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e3974754/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 62e1489..b177fc6 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -5,23 +5,23 @@ It was last updated for version `0.1-incubating-SNAPSHOT` of the
Commons RDF [API](apidocs/).
* [Using Commons RDF from Maven](#Using_Commons_RDF_from_Maven)
-* [Creating Commons RDF instances](#Creating_RDFTerm_instances)
-* [Graph](#Graph)
- * [Adding triples](#Adding_triples)
- * [Finding triples](#Finding_triples)
- * [Size](#Size)
- * [Iterating over triples](#Iterating_over_triples)
- * [Stream of triples](#Stream_of_triples)
- * [Removing triples](#Removing_triples)
+* [Creating Commons RDF instances](#Creating_Commons_RDF_instances)
* [RDF terms](#RDF_terms)
- * [IRI](#IRI)
- * [Blank node](#Blank_node)
- * [Blank node reference](#Blank_node_reference)
- * [Literal](#Literal)
- * [Datatype](#Datatype)
- * [Language](#Language)
- * [Types](#Types)
+ * [IRI](#IRI)
+ * [Blank node](#Blank_node)
+ * [Blank node reference](#Blank_node_reference)
+ * [Literal](#Literal)
+ * [Datatype](#Datatype)
+ * [Types](#Types)
+ * [Language](#Language)
* [Triple](#Triple)
+* [Graph](#Graph)
+ * [Adding triples](#Adding_triples)
+ * [Finding triples](#Finding_triples)
+ * [Size](#Size)
+ * [Iterating over triples](#Iterating_over_triples)
+ * [Stream of triples](#Stream_of_triples)
+ * [Removing triples](#Removing_triples)
## Using Commons RDF from Maven
@@ -92,9 +92,9 @@ _simple_ implementation, you can construct the
[SimpleRDFTermFactory](apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html):
```java
-import org.apache.commons.rdf.api.RDFTermFactory;
+import org.apache.commons.rdf.api.*;
import org.apache.commons.rdf.simple.SimpleRDFTermFactory;
-// ..
+// ...
RDFTermFactory rdfTermFactory = new SimpleRDFTermFactory();
```
@@ -128,175 +128,20 @@ objects as part of data parsing, storage lookup and queries.
-## Graph
-
-A [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) is a collection of
-[Triple](apidocs/org/apache/commons/rdf/api/Triple.html)s.
-
-To create a graph from a `RDFTermFactory`, use [createGraph()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--):
-
-```java
-Graph graph = factory.createGraph();
-```
-
-Implementations will typically also have other ways of retrieving a `Graph`,
-e.g. by parsing a Turtle file or connecting to a storage backend.
-
-### Adding triples
-
-_Note: Some `Graph` implementations are immutable, in which case the below
-may throw an `UnsupportedOperationException`_.
-
-Given the [previous example](#Creating_RDFTerm_instances), we can
-[add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-)
-the triple to the graph:
-
-```java
-graph.add(triple);
-```
-As an alternative to creating the `Triple` first, you can use the expanded
-_subject/predicate/object_ form of
-[Graph.add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-()):
-
-```java
-IRI bob = factory.createIRI("http://example.com/bob");
-Literal bobName = factory.createLiteral("Bob");
-graph.add(bob, iri, bobName);
-```
-
-It is not necessary to check if a triple already exist in the graph, as the
-underlying implementation will ignore duplicate triples.
-
-
-### Finding triples
-
-You can check if the graph
-[contains](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-)
-a triple:
-
-```java
-System.out.println(graph.contains(triple));
-```
-> `true`
-
-The expanded subject/predicate/object call for [Graph.contains()](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
-can be used without needing to create a `Triple` first, and also
-allow `null` as a wildcard parameters:
-
-```java
-System.out.println(graph.contains(null, iri, bobName));
-```
-> `true`
-
-### Size
-
-The [size](apidocs/org/apache/commons/rdf/api/Graph.html#size--) of a graph is
-the count of unique triples:
-
-```java
-System.out.println(graph.size());
-```
-> `2`
-
-_Note: In some implementations with large graphs, calculating the size can be an
-expensive operation._
-
-### Iterating over triples
-
-The [iterate](apidocs/org/apache/commons/rdf/api/Graph.html#iterate--) method
-can be used to sequentially iterate over all the triples of the graph:
-
-```java
-for (Triple t : graph.iterate()) {
- System.out.println(t.getObject());
-}
-```
-> `"Alice"`
->
-> `"Bob"`
-
-The expanded
-[iterate](apidocs/org/apache/commons/rdf/api/Graph.html#iterate-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
-method takes a _subject/predicate/object_ filter which permits the `null` wildcard:
-
-```java
-for (Triple t : graph.iterate(null, null, bobName)) {
- System.out.println(t.getPredicate());
-}
-```
-> `<http://example.com/name>`
-
-### Stream of triples
-
-For processing of larger graphs, and to access more detailed
-filtering and processing, the
-[getTriples](apidocs/org/apache/commons/rdf/api/Graph.html#getTriples--) method
-return a Java 8
-[Stream](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html).
-
-```java
-Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject());
-String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
-System.out.println(s);
-```
-> ``"Alice" "Bob"``
-
-For details about what can be done with a stream, see the
-[java.util.stream documentation](http://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html).
-
-Note that by default the stream will be parallel, use
-[.sequential()](http://docs.oracle.com/javase/8/docs/api/java/util/stream/BaseStream.html#sequential--)
-if your stream operations need to interact with objects that are not thread-safe.
-
-Streams allow advanced [filter predicates](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#filter-java.util.function.Predicate-), but you may find that simple _subject/predicate/object_ patterns
-are handled more efficiently by the expanded
-[getTriples](http://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/Graph.html#getTriples-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-) method. These can of course be combined:
-
-```java
-Stream<? extends Triple> namedB = graph.getTriples(null, nameIri, null).
- filter(t -> t.getObject().ntriplesString().contains("B"));
-System.out.println(namedB.map(t -> t.getSubject()).findAny().get());
-```
-> `<http://example.com/bob>`
-
-### Removing triples
-
-_Note: Some `Graph` implementations are immutable, in which case the below
-may throw an `UnsupportedOperationException`_.
-
-Triples can be [removed](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-) from a graph:
-
-```java
-graph.remove(triple);
-System.out.println(graph.contains(triple));
-```
-
-The expanded _subject/predicate/object_ form of
-[remove()](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
-can be used without needing to construct a `Triple` first. It also
-allow `null` as a wildcard pattern:
-
-```java
-graph.remove(null, iri, null);
-```
-
-To remove all triples, use [clear](apidocs/org/apache/commons/rdf/api/Graph.html#clear--):
-
-```java
-graph.clear();
-System.out.println(graph.contains(null, null, null));
-```
-> false
## RDF terms
-The core RDF terms are arranged in this class hierarchy:
+[RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html) is
+the super-interface for instances that can be used as subject, predicate and
+object of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html).
+
+The RDF term interfaces are arranged in this class hierarchy:
* [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html)
* [BlankNodeOrIRI](apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html)
- * [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html)
- * [IRI](apidocs/org/apache/commons/rdf/api/IRI.html)
+ * [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html)
+ * [IRI](apidocs/org/apache/commons/rdf/api/IRI.html)
* [Literal](apidocs/org/apache/commons/rdf/api/Literal.html)
### N-Triples string
@@ -325,8 +170,8 @@ places no such formal requirement on the `.toString()` method. Clients that
rely on a canonical N-Triples-compatible string should instead use
`ntriplesString()`._
-As an example of using `ntriplesString()`, here is how one could write a simple
-N-Triples compatible serialization of a
+As an example of using `ntriplesString()`, here is how one could write a basic
+N-Triples-compatible serialization of a
[Graph](apidocs/org/apache/commons/rdf/api/Graph.html):
```java
@@ -345,10 +190,9 @@ public class NTriplesSerializer {
Example output:
-```turtle
-_:ef136d20-f1ee-3830-a54b-cd5e489d50fb <http://example.com/name> "Alice" .
-<http://example.com/bob> <http://example.com/name> "Bob" .
-```
+> `_:ef136d20-f1ee-3830-a54b-cd5e489d50fb <http://example.com/name> "Alice" .`
+>
+> `<http://example.com/bob> <http://example.com/name> "Bob" .`
### IRI
@@ -360,7 +204,7 @@ e.g. `http://example.com/alice` or `http://ns.example.org/vocab#term`.
> IRIs in the RDF abstract syntax MUST be absolute, and MAY contain a fragment identifier.
In RDF, an IRI identifies a resource that can be used as a _subject_,
-_predicate_ or _object_ of a `Triple`.
+_predicate_ or _object_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html).
To create an `IRI` instance from a `RDFTermFactory`, use [createIRI](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createIRI-java.lang.String-):
@@ -416,7 +260,8 @@ System.out.println(iri.equals(factory.createLiteral("http://example.com/alice"))
A [blank node](http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes) is a
resource which, unlike an IRI, is not directly identified. Blank nodes can be
-used as _subject_ or _object_ of a `Triple`.
+used as _subject_ or _object_ of a `Triple`
+[Triple](apidocs/org/apache/commons/rdf/api/Triple.html).
To create a new
[BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html) instance from a
@@ -516,7 +361,7 @@ be made about this string except that it is unique per blank node._
A [literal](http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal) in RDF
is a value such as a string, number or a date. A `Literal` can only be used as
-_objects_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html#getObject--).
+an _object_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html#getObject--).
To create a [Literal](apidocs/org/apache/commons/rdf/api/Literal.html) instance
from an `RDFTermFactory`, use
@@ -592,7 +437,7 @@ System.out.println(typedLiteral.ntriplesString());
-#### Types
+##### Types
The class [Types](apidocs/org/apache/commons/rdf/simple/Types.html), which is
part of the _simple_ implementation, provides `IRI` constants for the standard
@@ -663,6 +508,166 @@ System.out.println(literalDouble.getLanguageTag().isPresent());
> `false`
-### Triple
+## Triple
**TODO:** [Triple](apidocs/org/apache/commons/rdf/api/Triple.html)
+
+## Graph
+
+A [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) is a collection of
+[Triple](apidocs/org/apache/commons/rdf/api/Triple.html)s.
+
+To create a graph from a `RDFTermFactory`, use [createGraph()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--):
+
+```java
+Graph graph = factory.createGraph();
+```
+
+Implementations will typically also have other ways of retrieving a `Graph`,
+e.g. by parsing a Turtle file or connecting to a storage backend.
+
+### Adding triples
+
+_Note: Some `Graph` implementations are immutable, in which case the below
+may throw an `UnsupportedOperationException`_.
+
+Given the [previous example](#Creating_RDFTerm_instances), we can
+[add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-)
+the triple to the graph:
+
+```java
+graph.add(triple);
+```
+As an alternative to creating the `Triple` first, you can use the expanded
+_subject/predicate/object_ form of
+[Graph.add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-()):
+
+```java
+IRI bob = factory.createIRI("http://example.com/bob");
+Literal bobName = factory.createLiteral("Bob");
+graph.add(bob, iri, bobName);
+```
+
+It is not necessary to check if a triple already exist in the graph, as the
+underlying implementation will ignore duplicate triples.
+
+
+### Finding triples
+
+You can check if the graph
+[contains](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-)
+a triple:
+
+```java
+System.out.println(graph.contains(triple));
+```
+> `true`
+
+The expanded subject/predicate/object call for [Graph.contains()](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+can be used without needing to create a `Triple` first, and also
+allow `null` as a wildcard parameters:
+
+```java
+System.out.println(graph.contains(null, iri, bobName));
+```
+> `true`
+
+### Size
+
+The [size](apidocs/org/apache/commons/rdf/api/Graph.html#size--) of a graph is
+the count of unique triples:
+
+```java
+System.out.println(graph.size());
+```
+> `2`
+
+_Note: In some implementations with large graphs, calculating the size can be an
+expensive operation._
+
+### Iterating over triples
+
+The [iterate](apidocs/org/apache/commons/rdf/api/Graph.html#iterate--) method
+can be used to sequentially iterate over all the triples of the graph:
+
+```java
+for (Triple t : graph.iterate()) {
+ System.out.println(t.getObject());
+}
+```
+> `"Alice"`
+>
+> `"Bob"`
+
+The expanded
+[iterate](apidocs/org/apache/commons/rdf/api/Graph.html#iterate-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+method takes a _subject/predicate/object_ filter which permits the `null` wildcard:
+
+```java
+for (Triple t : graph.iterate(null, null, bobName)) {
+ System.out.println(t.getPredicate());
+}
+```
+> `<http://example.com/name>`
+
+### Stream of triples
+
+For processing of larger graphs, and to access more detailed
+filtering and processing, the
+[getTriples](apidocs/org/apache/commons/rdf/api/Graph.html#getTriples--) method
+return a Java 8
+[Stream](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html).
+
+```java
+Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject());
+String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
+System.out.println(s);
+```
+> ``"Alice" "Bob"``
+
+For details about what can be done with a stream, see the
+[java.util.stream documentation](http://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html).
+
+Note that by default the stream will be parallel, use
+[.sequential()](http://docs.oracle.com/javase/8/docs/api/java/util/stream/BaseStream.html#sequential--)
+if your stream operations need to interact with objects that are not thread-safe.
+
+Streams allow advanced [filter predicates](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#filter-java.util.function.Predicate-), but you may find that simple _subject/predicate/object_ patterns
+are handled more efficiently by the expanded
+[getTriples](http://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/Graph.html#getTriples-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-) method. These can of course be combined:
+
+```java
+Stream<? extends Triple> namedB = graph.getTriples(null, nameIri, null).
+ filter(t -> t.getObject().ntriplesString().contains("B"));
+System.out.println(namedB.map(t -> t.getSubject()).findAny().get());
+```
+> `<http://example.com/bob>`
+
+### Removing triples
+
+_Note: Some `Graph` implementations are immutable, in which case the below
+may throw an `UnsupportedOperationException`_.
+
+Triples can be [removed](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-) from a graph:
+
+```java
+graph.remove(triple);
+System.out.println(graph.contains(triple));
+```
+
+The expanded _subject/predicate/object_ form of
+[remove()](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+can be used without needing to construct a `Triple` first. It also
+allow `null` as a wildcard pattern:
+
+```java
+graph.remove(null, iri, null);
+```
+
+To remove all triples, use [clear](apidocs/org/apache/commons/rdf/api/Graph.html#clear--):
+
+```java
+graph.clear();
+System.out.println(graph.contains(null, null, null));
+```
+> false
[2/4] incubator-commonsrdf git commit: User guide: Literal datatype
and language
Posted by st...@apache.org.
User guide: Literal datatype and language
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/6f17e31d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/6f17e31d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/6f17e31d
Branch: refs/heads/master
Commit: 6f17e31d441c448e61e818e653e9ab7ca937e44c
Parents: 393c1b9
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Apr 27 23:41:32 2015 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Apr 27 23:41:32 2015 +0100
----------------------------------------------------------------------
src/site/markdown/userguide.md | 146 ++++++++++++++++++++++++++++--------
1 file changed, 114 insertions(+), 32 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/6f17e31d/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index 2cb5096..62e1489 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -18,6 +18,8 @@ Commons RDF [API](apidocs/).
* [Blank node](#Blank_node)
* [Blank node reference](#Blank_node_reference)
* [Literal](#Literal)
+ * [Datatype](#Datatype)
+ * [Language](#Language)
* [Types](#Types)
* [Triple](#Triple)
@@ -233,8 +235,8 @@ return a Java 8
[Stream](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html).
```java
-Stream<Object> subjects = graph.getTriples().map(t -> t.getSubject());
-String s = subjects.map(Object::toString).collect(Collectors.joining(" "));
+Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject());
+String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
System.out.println(s);
```
> ``"Alice" "Bob"``
@@ -269,7 +271,7 @@ graph.remove(triple);
System.out.println(graph.contains(triple));
```
-The expanded subject/predicate/object form of
+The expanded _subject/predicate/object_ form of
[remove()](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
can be used without needing to construct a `Triple` first. It also
allow `null` as a wildcard pattern:
@@ -318,9 +320,9 @@ This returns the [N-Triples](http://www.w3.org/TR/n-triples) canonical form
of the term, which can be useful both for debugging and simple serialization.
_Note: The `.toString()` of the `simple` implementation used in
-these examples use `ntriplesString()` internally, but Commons RDF places no such
-formal requirement on the `.toString()` method. Clients that rely on
-a canonical N-Triples-compatible string should instead use
+some of these examples use `ntriplesString()` internally, but Commons RDF
+places no such formal requirement on the `.toString()` method. Clients that
+rely on a canonical N-Triples-compatible string should instead use
`ntriplesString()`._
As an example of using `ntriplesString()`, here is how one could write a simple
@@ -514,71 +516,151 @@ be made about this string except that it is unique per blank node._
A [literal](http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal) in RDF
is a value such as a string, number or a date. A `Literal` can only be used as
-_objects_ of a `Triple`
+_objects_ of a [Triple](apidocs/org/apache/commons/rdf/api/Triple.html#getObject--).
To create a [Literal](apidocs/org/apache/commons/rdf/api/Literal.html) instance
from an `RDFTermFactory`, use
[createLiteral](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createLiteral-java.lang.String-):
```java
-Literal literal = factory.createLiteral("Hello world");
-System.out.println(literal);
+Literal literal = factory.createLiteral("Hello world!");
+System.out.println(literal.ntriplesString());
```
-> `"Hello world"`
+> `"Hello world!"`
-In RDF 1.1, a _plain literal_ as created above always have the type
-`http://www.w3.org/2001/XMLSchema#string`:
+The lexical value (what is inside the quotes) can be retrieved
+using [getLexicalForm()](apidocs/org/apache/commons/rdf/api/Literal.html#getLexicalForm--):
```java
-System.out.println(literal.getDatatype());
+String lexical = literal.getLexicalForm();
+System.out.println(lexical);
```
-> `<http://www.w3.org/2001/XMLSchema#string>`
+> `Hello world!`
+#### Datatype
-Literals may be created with an associated language tag:
+All literals in RDF 1.1 have a
+[datatype](http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri) `IRI`, which
+can be retrieved using
+[Literal.getDatatype()](apidocs/org/apache/commons/rdf/api/Literal.html#getDatatype--):
```java
-Literal inSpanish = factory.createLiteral("¡Hola, Mundo!", "es");
-System.out.println(inSpanish);
+IRI datatype = literal.getDatatype();
+System.out.println(datatype.ntriplesString());
```
-> `"¡Hola, Mundo!"@es`
-In RDF 1.1, a Literal with a language always have the
-type `http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`:
-
-```java
-System.out.println(inSpanish.getDatatype());
-```
-
-> `<http://www.w3.org/1999/02/22-rdf-syntax-ns#langString>`
+> `<http://www.w3.org/2001/XMLSchema#string>`
-A _typed literal_ has a datatype represented by an `IRI`:
+In RDF 1.1, a [simple
+literal](http://www.w3.org/TR/rdf11-concepts/#dfn-simple-literal) (as created
+above) always have the type
+`http://www.w3.org/2001/XMLSchema#string` (or
+[xsd:string](apidocs/org/apache/commons/rdf/simple/Types.html#XSD_STRING) for
+short).
+
+<div class="alert alert-warn" role="alert"><p><span class="glyphicon glyphicon-warn-sign" aria-hidden="true"></span>
+<!-- Markdown not supported inside HTML -->
+<strong>Note:</strong>
+RDF 1.0 had the datatype
+<code>http://www.w3.org/1999/02/22-rdf-syntax-ns#PlainLiteral</code> to
+indicate <em>plain literals</em> (untyped), which were distinct from
+<code>http://www.w3.org/2001/XMLSchema#string</code> (typed). Commons
+RDF assumes RDF 1.1, which merges the two concepts as the second type, however
+particular implementations might have explicit options for RDF 1.0 support, in
+which case you might find <code>Literal</code> instances with the deprecated
+<a href="apidocs/org/apache/commons/rdf/simple/Types.html#RDF_PLAINLITERAL">plain
+literal</a> data type.
+</p></div>
+
+
+To create a literal with any other
+[datatype](http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri), then
+first create the datatype `IRI` and pass it to the expanded
+[createLiteral](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createLiteral-java.lang.String-org.apache.commons.rdf.api.IRI-):
```java
IRI xsdDouble = factory.createIRI("http://www.w3.org/2001/XMLSchema#double");
Literal typedLiteral = factory.createLiteral("13.37", xsdDouble);
-System.out.println(typedLiteral);
+System.out.println(typedLiteral.ntriplesString());
```
> `"13.37"^^<http://www.w3.org/2001/XMLSchema#double>`
+
+
#### Types
The class [Types](apidocs/org/apache/commons/rdf/simple/Types.html), which is
-part of the _simple_ implementation, provides constants for the standard
-XML Schema datatypes, e.g. `xsd:dateTime` and `xsd:float`. Using `Types`,
+part of the _simple_ implementation, provides `IRI` constants for the standard
+XML Schema datatypes like `xsd:dateTime` and `xsd:float`. Using `Types`,
the above example can be simplified to:
```java
Literal typedLiteral = factory.createLiteral("13.37", Types.XSD_DOUBLE);
```
-Note that the string returned from `Literal.ntriplesString()` will always
-contain the full IRI for the datatype.
+As the constants in `Types` are all instances of `IRI`, they can
+also be used for comparisons:
+
+```java
+System.out.println(literal.getDatatype().equals(Types.XSD_STRING));
+```
+
+> `true`
+
+#### Language
+
+Literals may be created with an associated
+[language tag](http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string)
+using the expanded [createLiteral](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createLiteral-java.lang.String-java.lang.String-):
+
+```java
+Literal inSpanish = factory.createLiteral("¡Hola, Mundo!", "es");
+System.out.println(inSpanish.ntriplesString());
+System.out.println(inSpanish.getLexicalForm());
+```
+> `"¡Hola, Mundo!"@es`
+>
+> `¡Hola, Mundo!`
+
+A literal with a language tag always have the
+implied type `http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`:
+
+```java
+System.out.println(inSpanish.getDatatype().ntriplesString());
+```
+
+> `<http://www.w3.org/1999/02/22-rdf-syntax-ns#langString>`
+
+The language tag can be retrieved using
+[getLanguageTag()](apidocs/org/apache/commons/rdf/api/Literal.html#getLanguageTag--):
+
+```java
+Optional<String> tag = inSpanish.getLanguageTag();
+if (tag.isPresent()) {
+ System.out.println(tag.get());
+}
+```
+
+> `es`
+
+The language tag is behind an
+[Optional](http://docs.oracle.com/javase/8/docs/api/java/util/Optional.html) as
+it cannot be present for any other datatypes than
+`http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`:
+
+```java
+System.out.println(literal.getLanguageTag().isPresent());
+System.out.println(literalDouble.getLanguageTag().isPresent());
+```
+
+> `false`
+>
+> `false`
### Triple