commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [3/4] incubator-commonsrdf git commit: User guide: Graph section moved to the end
Date Tue, 28 Apr 2015 00:10:29 GMT
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 <stain@apache.org>
Authored: Tue Apr 28 00:05:49 2015 +0100
Committer: Stian Soiland-Reyes <stain@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


Mime
View raw message