Updated userguide for 0.2.0-incubating
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/935cb7f8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/935cb7f8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/935cb7f8 Branch: refs/heads/quad Commit: 935cb7f850c8776da974c4c611509161a12a657a Parents: 297000a Author: Stian Soiland-Reyes <st...@apache.org> Authored: Sun May 15 22:49:32 2016 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Sun May 15 22:49:32 2016 +0100 ---------------------------------------------------------------------- src/site/markdown/userguide.md | 60 +++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 19 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/935cb7f8/src/site/markdown/userguide.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/userguide.md b/src/site/markdown/userguide.md index 2a7a73d..df8a277 100644 --- a/src/site/markdown/userguide.md +++ b/src/site/markdown/userguide.md @@ -21,13 +21,15 @@ # User Guide This page shows some examples of a client using the Commons RDF API. -It was last updated for version `0.1.0-incubating` of the +It was last updated for version `0.2.0-incubating` of the Commons RDF [API](apidocs/). * [Introduction](#Introduction) * [RDF concepts](#RDF_concepts) * [Using Commons RDF from Maven](#Using_Commons_RDF_from_Maven) * [Creating Commons RDF instances](#Creating_Commons_RDF_instances) + * [Creating a RDFTermFactory](#Creating_a_RDFTermFactory) + * [Using a RDFTermFactory](#Using_a_RDFTermFactory) * [RDF terms](#RDF_terms) * [N-Triples string](#N-Triples_string) * [IRI](#IRI) @@ -84,7 +86,7 @@ add the following dependency to your `pom.xml`: <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-rdf-api</artifactId> - <version>0.1.0-incubating</version> + <version>0.2.0-incubating</version> </dependency> </dependencies> ``` @@ -128,7 +130,7 @@ _simple_ implementation, add to your `<dependencies>`: <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-rdf-simple</artifactId> - <version>0.1.0-incubating</version> + <version>0.2.0-incubating</version> </dependency> ``` @@ -143,7 +145,9 @@ To create instances of Commons RDF interfaces like [`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 +### Creating a RDFTermFactory + +How to get an instance of this factory is implementation-specific, for the _simple_ implementation, you can construct the [SimpleRDFTermFactory](apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html): @@ -170,6 +174,12 @@ Iterator<RDFTermFactory> iterator = loader.iterator(); RDFTermFactory factory = iterator.next(); ``` +Note that the `ServiceLoader` approach above might not work well within +split classloader systems like OSGi. + + +### Using a RDFTermFactory + 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), @@ -331,7 +341,7 @@ 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](apidocs/org/apache/commons/rdf/api/Triple.html). To create a new @@ -395,6 +405,7 @@ System.out.println(b1.equals(new SimpleRDFTermFactory().createBlankNode("b1"))); > > `false` + #### Blank node reference While blank nodes are distinct from IRIs, and don't have inherent @@ -688,7 +699,7 @@ 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-()): +[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"); @@ -803,6 +814,8 @@ graph.remove(triple); System.out.println(graph.contains(triple)); ``` +> `false` + 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 @@ -818,7 +831,7 @@ To remove all triples, use [clear](apidocs/org/apache/commons/rdf/api/Graph.html graph.clear(); System.out.println(graph.contains(null, null, null)); ``` -> false +> `false` ## Mutability and thread safety @@ -830,15 +843,22 @@ 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 +will have a return value which `.equals()` any earlier return values. Being immutable, the `Triple` and `RDFTerm` types should be -considered thread-safe. +considered thread-safe. Similarly their `hashCode()` should be +considered stable, so any `RDFTerm` or `Triple` can be used +in hashing collections like +[HashMap](https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html). 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. +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. A mutable `Graph` +might also be modified by operations outside Commons RDF, e.g. because it is +backed by a shared datastore with multiple clients. -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`. +Implementations of Commons RDF may specify the (im)mutability of `Graph` in further details +in their documentation. 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--) @@ -868,7 +888,7 @@ synchronized(graph) { ## Implementations The [Commons RDF API](apidocs/org/apache/commons/rdf/api/package-summary.html) -is a set of Java interfaces, with implementations provided by several Java RDF +is a set of Java interfaces, which can be implemented by several Java RDF frameworks. See the [implementations](implementations.html) page for an updated list of providers. @@ -913,8 +933,14 @@ for (Triple t1: g1.getTriples(null, iri1, null)) { ``` _Note: Special care might need to be taken for cross-interoperability of -`BlankNode` instances. This is currently under discussion. See -[COMMONSRDF-15](https://issues.apache.org/jira/browse/COMMONSRDF-15)_ +`BlankNode` instances. While multiple triples with the same +"foreign" `BlankNode` can be added without breaking their +connections, the `Graph` is not required to +return blank node instances that `.equals()` those +inserted - specifically it is **not** required to persist the +blank node [uniqueReference](apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--). + See +[COMMONSRDF-15](https://issues.apache.org/jira/browse/COMMONSRDF-15)._ The `.equals()` methods of `RDFTerm` interfaces are explicitly defined, so their instances can be compared across implementations. @@ -922,13 +948,9 @@ 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 -should be taken if returned values are needs to be casted to implementation +should be taken if returned values needs to be casted to implementation specific types._ -The `.hashCode()` is not currently explicitly defined, hence -special care should be taken for cross-interoperability within hashing data -structures like `HashMap`. See -[COMMONSRDF-14](https://issues.apache.org/jira/browse/COMMONSRDF-14) ## Complete example