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 2016/10/14 12:17:49 UTC
[3/8] incubator-commonsrdf git commit: Update examples for 0.3.0
Update examples for 0.3.0
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/e0f398d9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/e0f398d9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/e0f398d9
Branch: refs/heads/master
Commit: e0f398d9d9b59eee821bb35966e3be014f5a9cd3
Parents: 42b7c2c
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Oct 10 11:36:07 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Oct 10 11:36:07 2016 +0100
----------------------------------------------------------------------
examples/pom.xml | 4 +-
examples/src/example/UserGuideTest.java | 20 ++++---
src/site/markdown/userguide.md | 82 +++++++++++++++++-----------
3 files changed, 65 insertions(+), 41 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0f398d9/examples/pom.xml
----------------------------------------------------------------------
diff --git a/examples/pom.xml b/examples/pom.xml
index 4b61cf7..62eafa0 100644
--- a/examples/pom.xml
+++ b/examples/pom.xml
@@ -50,13 +50,13 @@
<groupId>org.apache.commons</groupId>
<artifactId>commons-rdf-api</artifactId>
<!-- update to latest version -->
- <version>0.2.0-incubating</version>
+ <version>0.3.0-incubating-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-rdf-simple</artifactId>
<!-- update to latest version -->
- <version>0.2.0-incubating</version>
+ <version>0.3.0-incubating-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>junit</groupId>
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0f398d9/examples/src/example/UserGuideTest.java
----------------------------------------------------------------------
diff --git a/examples/src/example/UserGuideTest.java b/examples/src/example/UserGuideTest.java
index 44cf587..ae70bb6 100644
--- a/examples/src/example/UserGuideTest.java
+++ b/examples/src/example/UserGuideTest.java
@@ -109,7 +109,7 @@ public class UserGuideTest {
Literal literalDouble2 = factory.createLiteral("13.37", Types.XSD_DOUBLE);
- System.out.println(literal.getDatatype().equals(Types.XSD_STRING));
+ System.out.println(Types.XSD_STRING.equals(literal.getDatatype()));
Literal inSpanish = factory.createLiteral("�Hola, Mundo!", "es");
System.out.println(inSpanish.ntriplesString());
@@ -187,13 +187,17 @@ public class UserGuideTest {
System.out.println(t.getPredicate());
}
- Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject());
- String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
- System.out.println(s);
+ try (Stream<? extends Triple> triples = graph.stream()) {
+ Stream<RDFTerm> subjects = triples.map(t -> t.getObject());
+ String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
+ System.out.println(s);
+ }
- 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());
+ try (Stream<? extends Triple> named = graph.stream(null, nameIri,null)) {
+ Stream<? extends Triple> namedB = named.filter(
+ t -> t.getObject().ntriplesString().contains("B"));
+ System.out.println(namedB.map(t -> t.getSubject()).findAny().get());
+ }
graph.remove(triple);
System.out.println(graph.contains(triple));
@@ -214,7 +218,7 @@ public class UserGuideTest {
}
public static void writeGraph(Graph graph, Path graphFile) throws Exception {
- Stream<CharSequence> stream = graph.getTriples().map(UserGuideTest::tripleAsString);
+ Stream<CharSequence> stream = graph.stream().map(UserGuideTest::tripleAsString);
Files.write(graphFile, stream::iterator, StandardCharsets.UTF_8);
}
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0f398d9/src/site/markdown/userguide.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md
index ae452fb..ab59292 100644
--- a/src/site/markdown/userguide.md
+++ b/src/site/markdown/userguide.md
@@ -262,7 +262,7 @@ public class NTriplesSerializer {
t.getObject().ntriplesString() + " .";
}
public static void writeGraph(Graph graph, Path graphFile) throws Exception {
- Stream<CharSequence> stream = graph.getTriples().map(NTriplesSerializer::tripleAsString);
+ Stream<CharSequence> stream = graph.stream().map(NTriplesSerializer::tripleAsString);
Files.write(graphFile, stream::iterator, StandardCharsets.UTF_8);
}
}
@@ -448,7 +448,8 @@ 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
-an _object_ 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--)
+or [Quad](apidocs/org/apache/commons/rdf/api/Quad.html#getObject--)
To create a [Literal](apidocs/org/apache/commons/rdf/api/Literal.html) instance
from an `RDFTermFactory`, use
@@ -461,7 +462,7 @@ System.out.println(literal.ntriplesString());
> `"Hello world!"`
-The lexical value (what is inside the quotes) can be retrieved
+The _lexical value_ (what is inside the quotes) can be retrieved
using [getLexicalForm()](apidocs/org/apache/commons/rdf/api/Literal.html#getLexicalForm--):
```java
@@ -509,8 +510,8 @@ literal</a> data type.
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
+[datatype](http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri) (e.g. `xsd:double`),
+then 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
@@ -535,11 +536,11 @@ the above example can be simplified to:
Literal literalDouble2 = factory.createLiteral("13.37", Types.XSD_DOUBLE);
```
-As the constants in `Types` are all instances of `IRI`, they can
+As the constants in `Types` are all instances of `IRI`, so they can
also be used for comparisons:
```java
-System.out.println(literal.getDatatype().equals(Types.XSD_STRING));
+System.out.println(Types.XSD_STRING.equals(literal.getDatatype()));
```
> `true`
@@ -582,7 +583,7 @@ if (tag.isPresent()) {
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
+it won't be present for any other datatypes than
`http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`:
```java
@@ -676,6 +677,14 @@ System.out.println(triple.equals(factory.createTriple(subj, pred, obj)));
> `true`
+This equality is true even across implementations, as Commons RDF has
+specified _equality semantics_ for
+[Triples](apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-),
+[Quads](apidocs/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-),
+[IRIs](apidocs/org/apache/commons/rdf/api/IRI.html#equals-java.lang.Object-),
+[Literals](apidocs/org/apache/commons/rdf/api/Literal.html#equals-java.lang.Object-)
+and even [BlankNodes](apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-).
+
## Graph
@@ -695,9 +704,6 @@ 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`_.
-
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-)
@@ -734,7 +740,7 @@ System.out.println(graph.contains(triple));
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:
+allow `null` as a wildcard parameter:
```java
System.out.println(graph.contains(null, nameIri, bobName));
@@ -781,14 +787,21 @@ for (Triple t : graph.iterate(null, null, bobName)) {
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
+[stream](apidocs/org/apache/commons/rdf/api/Graph.html#stream--) method
return a Java 8
[Stream](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html).
+Some of the implementations (e.g. [RDF4J](implementations.html#Closing_RDF4J_resources)) might
+require resources to be closed after the stream
+has been processed, so `.stream()` should be used within a
+[try-with-resources](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) block.
+
```java
-Stream<RDFTerm> subjects = graph.getTriples().map(t -> t.getObject());
-String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
-System.out.println(s);
+try (Stream<? extends Triple> triples = graph.stream()) {
+ Stream<RDFTerm> subjects = triples.map(t -> t.getObject());
+ String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(" "));
+ System.out.println(s);
+}
```
> ``"Alice" "Bob"``
@@ -800,21 +813,22 @@ Note that by default the stream will be parallel, use
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:
+are handled more efficiently by the implementation when using the expanded
+[stream](http://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/Graph.html#stream-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());
+try (Stream<? extends Triple> named = graph.stream(null, nameIri, null)) {
+ Stream<? extends Triple> namedB = named.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`_.
+
+### Removing triples
Triples can be [removed](apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-) from a graph:
@@ -871,7 +885,7 @@ 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-)
+and [stream](apidocs/org/apache/commons/rdf/api/Graph.html#stream-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.
@@ -894,6 +908,8 @@ synchronized(graph) {
}
```
+
+
## Implementations
The [Commons RDF API](apidocs/org/apache/commons/rdf/api/package-summary.html)
@@ -903,13 +919,17 @@ updated list of providers.
Implementations are free to choose their level of integration with Commons RDF.
Several methods defined in Commons RDF therefore explicitly note the
-possibility of throwing a `UnsupportedOperationException`.
+possibility of throwing a `UnsupportedOperationException` - however the
+implementations provided by Commons RDF
Different RDF frameworks might have different mechanisms to retrieve a Commons
RDF objects like `Graph` or `Triple` (e.g. returned from a query).
-Commons RDF provides a `RDFTermFactory` interface as a way to create new
-instances, but does not mandate how the factory itself should be instantiated
-(e.g. a factory might be returned for an open network connection).
+
+Commons RDF provides a `RDFTermFactory` interface as an interoperable
+way to create new instances, but does not mandate how the factory
+itself should be instantiated (e.g. a factory might be returned for an
+open network connection).
+
### Cross-compatibility
@@ -934,7 +954,7 @@ IRI iri1 = fooFactory.createIRI("http://example.com/property1");
// Both Triple and RDFTerm instances can be used
//
-for (Triple t1: g1.getTriples(null, iri1, null)) {
+for (Triple t1: g1.stream(null, iri1, null)) {
if (g2.contains(t1.getSubject(), null, t1.getObject())) {
g2.remove(t1);
}
@@ -956,7 +976,7 @@ their instances can be compared across implementations.
_Note: The `Graph` implementation is not required to keep the JVM object
reference, e.g. after `g2.add(subj1, pred, obj)` it is not required to later
-return the same `subj1` implementation in `g2.getTriples()`. Special care
+return the same `subj1` implementation in `g2.stream()`. Special care
should be taken if returned values needs to be casted to implementation
specific types._