commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [1/2] incubator-commonsrdf git commit: Examples: All about graph methods
Date Fri, 24 Apr 2015 14:56:22 GMT
Repository: incubator-commonsrdf
Updated Branches:
  refs/heads/master 5cec446f0 -> b8edc41b7


Examples: All about graph methods


Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/bf3438f3
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/bf3438f3
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/bf3438f3

Branch: refs/heads/master
Commit: bf3438f3b32c4b7d0e2dd6f6113322804c69eef7
Parents: 5cec446
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Fri Apr 24 15:10:09 2015 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Fri Apr 24 15:31:58 2015 +0100

----------------------------------------------------------------------
 src/site/markdown/examples.md | 218 ++++++++++++++++++++++++++++++-------
 1 file changed, 179 insertions(+), 39 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/bf3438f3/src/site/markdown/examples.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/examples.md b/src/site/markdown/examples.md
index 268f27a..74d6075 100644
--- a/src/site/markdown/examples.md
+++ b/src/site/markdown/examples.md
@@ -1,11 +1,11 @@
-# Examples of using the Commons RDF API
+# User Guide
 
 This page shows some examples of a client using the Commons RDF API.
 
 ## Using Commons RDF from Maven
 
-To use Commons RDF API from an 
-[Apache Maven](http://maven.apache.org/) projects, 
+To use Commons RDF API from an
+[Apache Maven](http://maven.apache.org/) projects,
 add the following dependency to your `pom.xml`:
 
 ```xml
@@ -18,14 +18,36 @@ add the following dependency to your `pom.xml`:
 </dependencies>
 ```
 
-If you are using a `SNAPSHOT` version, then you will have to either build 
-Commons RDF from [source](https://github.com/apache/incubator-commonsrdf), or 
-add the [snapshot repository](https://github.com/apache/incubator-commonsrdf#snapshot-repository)
+If you are testing a `SNAPSHOT` version, then you will have to either build
+Commons RDF from [source](https://github.com/apache/incubator-commonsrdf), or
+add the [snapshot repository](https://github.com/apache/incubator-commonsrdf#snapshot-repository):
 
-In the examples below we will use the 
-[`simple` implementation](apidocs/org/apache/commons/rdf/simple/package-summary.html), but

+```xml
+<repositories>
+  <repository>
+    <id>apache.snapshots</id>
+    <name>Apache Snapshot Repository</name>
+    <url>http://repository.apache.org/snapshots</url>
+    <releases>
+      <enabled>false</enabled>
+    </releases>
+  </repository>
+</repositories>
+```
+
+As Commons RDF requires Java 8 or later, you will also need:
+
+```xml
+<properties>
+  <maven.compiler.source>1.8</maven.compiler.source>
+  <maven.compiler.target>1.8</maven.compiler.target>
+</properties>
+```
+
+In the examples below we will use the
+[_simple_ implementation](apidocs/org/apache/commons/rdf/simple/package-summary.html), but
 the examples should be equally applicable to other implementations. To add a dependency for
the
-`simple` implementation, add to your `pom.xml` section `<dependencies>`: 
+_simple_ implementation, add to your `<dependencies>`:
 
 ```xml
     <dependency>
@@ -36,15 +58,15 @@ the examples should be equally applicable to other implementations. To
add a dep
 ```
 
 
-## RDFTermFactory
+## Creating RDFTerm instances
 
-To create instances of Commons RDF interfaces like 
-[`Graph`](apidocs/org/apache/commons/rdf/api/Graph.html) and 
+To create instances of Commons RDF interfaces like
+[`Graph`](apidocs/org/apache/commons/rdf/api/Graph.html) and
 [`IRI`](apidocs/org/apache/commons/rdf/api/IRI.html) you will need a
 [RDFTermFactory](/apidocs/org/apache/commons/rdf/api/RDFTermFactory.html).
 
 How to get an instance of this factory is implementation specific, for the
-`simple` implementation, you can construct the 
+_simple_ implementation, you can construct the
 [SimpleRDFTermFactory](apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html):
 
 ```java
@@ -54,7 +76,7 @@ import org.apache.commons.rdf.simple.SimpleRDFTermFactory;
 RDFTermFactory rdfTermFactory = new SimpleRDFTermFactory();
 ```
 
-Using the factory you can create 
+Using the factory you can construct
 any [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html), e.g. to create a
 [BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html),
 [IRI](apidocs/org/apache/commons/rdf/api/IRI.html) and
@@ -72,18 +94,14 @@ You can also create a stand-alone [Triple](apidocs/org/apache/commons/rdf/api/Tr
 Triple triple = factory.createTriple(blankNode, iri, literal);
 ```
 
-To keep your triples, you might want a [Graph](apidocs/org/apache/commons/rdf/api/Graph.html):
 
-```java
-Graph graph = factory.createGraph();
-```
 
-The [RDFTermFactory](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html) also 
+The [RDFTermFactory](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html) also
 contains more specific variants of some of the methods above, e.g. to create a
 typed literal.  
 
 Note that for any given implementation, `RDFTerm` instances need not be created
-using a `RDFTermFactory`. More likely, implementation-specific methods might create these

+using a `RDFTermFactory`. More likely, implementation-specific methods might create these
 objects as part of data parsing, storage lookup and queries.
 
 
@@ -93,24 +111,30 @@ objects as part of data parsing, storage lookup and queries.
 A [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) is a collection of
 [Triple](apidocs/org/apache/commons/rdf/api/Triple.html)s.
 
-Given the [previous example](#RDFTermFactory), we can 
-[add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-)
-the `triple` to the `graph`:
+To create a graph from a `RDFTermFactory`, use [createGraph()](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--):
 
 ```java
-graph.add(triple);
+Graph graph = factory.createGraph();
 ```
 
-And check that the graph 
-[contains](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-)

-the triple:
+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
-System.out.println(graph.contains(triple));
+graph.add(triple);
 ```
-> true
-
-As an alternative you can also use the expanded form of these methods:
+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");
@@ -118,24 +142,140 @@ Literal bobName = factory.createLiteral("Bob");
 graph.add(bob, iri, bobName);
 ```
 
-and
+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
+> `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<Object> subjects = graph.getTriples().map(t -> t.getSubject());
+String s = subjects.map(Object::toString).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
+
+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
 
-Notice that the 
-expanded [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-)
-allow `null` as a wildcard parameters.
 
+## IRI, Literal, BlankNode
 
+**TODO:**
 
+* [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)
 
-**TODO:** Remaining Graph operations, incl. `getTriples()` streams
+## Types
 
 **TODO:** [Types](apidocs/org/apache/commons/rdf/simple/Types.html)
 
-**TODO:** Methods on `Literal`, `IRI`, `BlankNode` etc.
+## Full example
 
-**TODO:** Serialize as n-triples example
\ No newline at end of file
+**TODO:** Serialize as n-triples example


Mime
View raw message