commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r988321 - /websites/production/commonsrdf/content/userguide.html
Date Sun, 15 May 2016 22:01:09 GMT
Author: stain
Date: Sun May 15 22:01:09 2016
New Revision: 988321

Log:
Updated userguide

Modified:
    websites/production/commonsrdf/content/userguide.html

Modified: websites/production/commonsrdf/content/userguide.html
==============================================================================
--- websites/production/commonsrdf/content/userguide.html (original)
+++ websites/production/commonsrdf/content/userguide.html Sun May 15 22:01:09 2016
@@ -235,7 +235,7 @@
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License. --><h1>User Guide</h1>
-<p>This page shows some examples of a client using the Commons RDF API. It was last
updated for version <tt>0.1.0-incubating</tt> of the Commons RDF <a href="apidocs/">API</a>.</p>
+<p>This page shows some examples of a client using the Commons RDF API. It was last
updated for version <tt>0.2.0-incubating</tt> of the Commons RDF <a href="apidocs/">API</a>.</p>
 
 <ul>
   
@@ -250,6 +250,10 @@
   
 <li><a href="#Creating_Commons_RDF_instances">Creating Commons RDF instances</a></li>
   
+<li><a href="#Creating_a_RDFTermFactory">Creating a RDFTermFactory</a></li>
+  
+<li><a href="#Using_a_RDFTermFactory">Using a RDFTermFactory</a></li>
+  
 <li><a href="#RDF_terms">RDF terms</a>
   
 <ul>
@@ -327,7 +331,7 @@
     &lt;dependency&gt;
         &lt;groupId&gt;org.apache.commons&lt;/groupId&gt;
         &lt;artifactId&gt;commons-rdf-api&lt;/artifactId&gt;
-        &lt;version&gt;0.1.0-incubating&lt;/version&gt;
+        &lt;version&gt;0.2.0-incubating&lt;/version&gt;
     &lt;/dependency&gt;
 &lt;/dependencies&gt;
 </pre></div></div>
@@ -363,14 +367,16 @@
 <pre>    &lt;dependency&gt;
         &lt;groupId&gt;org.apache.commons&lt;/groupId&gt;
         &lt;artifactId&gt;commons-rdf-simple&lt;/artifactId&gt;
-        &lt;version&gt;0.1.0-incubating&lt;/version&gt;
+        &lt;version&gt;0.2.0-incubating&lt;/version&gt;
     &lt;/dependency&gt;
 </pre></div></div>
 <p><i>The <tt>&lt;version&gt;</tt> above might not be up
to date, see the <a href="download.html">download page</a> for the latest version.</i></p></div>
 <div class="section">
 <h2><a name="Creating_Commons_RDF_instances"></a>Creating Commons RDF instances</h2>
 <p>To create instances of Commons RDF interfaces like <a href="apidocs/org/apache/commons/rdf/api/Graph.html"><tt>Graph</tt></a>
and <a href="apidocs/org/apache/commons/rdf/api/IRI.html"><tt>IRI</tt></a>
you will need a <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html">RDFTermFactory</a>.</p>
-<p>How to get an instance of this factory is implementation specific, for the <i>simple</i>
implementation, you can construct the <a href="apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html">SimpleRDFTermFactory</a>:</p>
+<div class="section">
+<h3><a name="Creating_a_RDFTermFactory"></a>Creating a RDFTermFactory</h3>
+<p>How to get an instance of this factory is implementation-specific, for the <i>simple</i>
implementation, you can construct the <a href="apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html">SimpleRDFTermFactory</a>:</p>
 
 <div class="source">
 <div class="source">
@@ -392,6 +398,9 @@ ServiceLoader&lt;RDFTermFactory&gt; load
 Iterator&lt;RDFTermFactory&gt; iterator = loader.iterator();
 RDFTermFactory factory = iterator.next();
 </pre></div></div>
+<p>Note that the <tt>ServiceLoader</tt> approach above might not work well
within split classloader systems like OSGi.</p></div>
+<div class="section">
+<h3><a name="Using_a_RDFTermFactory"></a>Using a RDFTermFactory</h3>
 <p>Using the factory you can construct any <a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>,
e.g. to create a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a>,
<a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a> and <a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a>:</p>
 
 <div class="source">
@@ -407,7 +416,7 @@ Literal aliceLiteral = factory.createLit
 <pre>Triple triple = factory.createTriple(aliceBlankNode, nameIri, aliceLiteral);
 </pre></div></div>
 <p>The <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html">RDFTermFactory</a>
also contains more specific variants of some of the methods above, e.g. to create a typed
literal.</p>
-<p>Note that for any given implementation, <tt>RDFTerm</tt> instances need
not be created using a <tt>RDFTermFactory</tt>. More likely, implementation-specific
methods might create these objects as part of data parsing, storage lookup and queries.</p></div>
+<p>Note that for any given implementation, <tt>RDFTerm</tt> instances need
not be created using a <tt>RDFTermFactory</tt>. More likely, implementation-specific
methods might create these objects as part of data parsing, storage lookup and queries.</p></div></div>
 <div class="section">
 <h2><a name="RDF_terms"></a>RDF terms</h2>
 <p><a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>
is the super-interface for instances that can be used as subject, predicate and object of
a <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>.</p>
@@ -534,7 +543,7 @@ System.out.println(iri.equals(factory.cr
 </blockquote></div>
 <div class="section">
 <h3><a name="Blank_node"></a>Blank node</h3>
-<p>A <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes">blank
node</a> is a resource which, unlike an IRI, is not directly identified. Blank nodes
can be used as <i>subject</i> or <i>object</i> of a <tt>Triple</tt>
<a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>.</p>
+<p>A <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes">blank
node</a> is a resource which, unlike an IRI, is not directly identified. Blank nodes
can be used as <i>subject</i> or <i>object</i> of a <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>.</p>
 <p>To create a new <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a>
instance from a <tt>RDFTermFactory</tt>, use <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createBlankNode--">createBlankNode</a>:</p>
 
 <div class="source">
@@ -827,7 +836,7 @@ if (obj instanceof Literal) {
 <div class="source">
 <pre>graph.add(triple);
 </pre></div></div>
-<p>As an alternative to creating the <tt>Triple</tt> first, you can use
the expanded <i>subject/predicate/object</i> 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-()):</p>
+<p>As an alternative to creating the <tt>Triple</tt> first, you can use
the expanded <i>subject/predicate/object</i> form of <a href="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</a>:</p>
 
 <div class="source">
 <div class="source">
@@ -936,6 +945,10 @@ System.out.println(namedB.map(t -&gt; t.
 <pre>graph.remove(triple);
 System.out.println(graph.contains(triple));
 </pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+</blockquote>
 <p>The expanded <i>subject/predicate/object</i> form of <a href="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-">remove()</a>
can be used without needing to construct a <tt>Triple</tt> first. It also allow
<tt>null</tt> as a wildcard pattern:</p>
 
 <div class="source">
@@ -951,14 +964,14 @@ System.out.println(graph.contains(null,
 </pre></div></div>
 
 <blockquote>
-<p>false</p>
+<p><tt>false</tt></p>
 </blockquote></div></div>
 <div class="section">
 <h2><a name="Mutability_and_thread_safety"></a>Mutability and thread safety</h2>
 <p><i>Note: This section is subject to change - see discussion on <a class="externalLink"
href="https://issues.apache.org/jira/browse/COMMONSRDF-7">COMMONSRDF-7</a></i></p>
-<p>In Commons RDF, all instances of <tt>Triple</tt> and <tt>RDFTerm</tt>
(e.g. <tt>IRI</tt>, <tt>BlankNode</tt>, <tt>Literal</tt>)
are considered <i>immutable</i>. That is, their content does not change, and so
calling a method like <a href="apidocs/org/apache/commons/rdf/api/IRI.html#getIRIString--">IRI.getIRIString</a>
or <a href="apidocs/org/apache/commons/rdf/api/Literal.html#getDatatype--">Literal.getDatatype</a>
will always have return values that are <tt>.equals()</tt> to any earlier return
values. Being immutable, the <tt>Triple</tt> and <tt>RDFTerm</tt>
types should be considered thread-safe.</p>
-<p>A <tt>Graph</tt> may be <i>mutable</i>, particular if it
supports methods like <a href="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</a>
and <a href="apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-">Graph.remove</a>.
That means that responses to methods like <a href="apidocs/org/apache/commons/rdf/api/Graph.html#size--">size</a>
and <a href="apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-">contains</a>
might change during its lifetime.</p>
-<p>Implementations of Commons RDF may specify the (im)mutability of <tt>Graph</tt>
in further details. If a graph is immutable, the methods <tt>add</tt> and <tt>remove</tt>
may throw a <tt>UnsupportedOperationException</tt>.</p>
+<p>In Commons RDF, all instances of <tt>Triple</tt> and <tt>RDFTerm</tt>
(e.g. <tt>IRI</tt>, <tt>BlankNode</tt>, <tt>Literal</tt>)
are considered <i>immutable</i>. That is, their content does not change, and so
calling a method like <a href="apidocs/org/apache/commons/rdf/api/IRI.html#getIRIString--">IRI.getIRIString</a>
or <a href="apidocs/org/apache/commons/rdf/api/Literal.html#getDatatype--">Literal.getDatatype</a>
will have a return value which <tt>.equals()</tt> any earlier return values. Being
immutable, the <tt>Triple</tt> and <tt>RDFTerm</tt> types should be
considered thread-safe. Similarly their <tt>hashCode()</tt> should be considered
stable, so any <tt>RDFTerm</tt> or <tt>Triple</tt> can be used in
hashing collections like <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html">HashMap</a>.</p>
+<p>A <tt>Graph</tt> may be <i>mutable</i>, particular if it
supports methods like <a href="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</a>
and <a href="apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-">Graph.remove</a>.
That means that responses to methods like <a href="apidocs/org/apache/commons/rdf/api/Graph.html#size--">size</a>
and <a href="apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-">contains</a>
might change during its lifetime. A mutable <tt>Graph</tt> might also be modified
by operations outside Commons RDF, e.g. because it is backed by a shared datastore with multiple
clients.</p>
+<p>Implementations of Commons RDF may specify the (im)mutability of <tt>Graph</tt>
in further details in their documentation. If a graph is immutable, the methods <tt>add</tt>
and <tt>remove</tt> may throw a <tt>UnsupportedOperationException</tt>.</p>
 <p>Commons RDF does not specify if methods on a <tt>Graph</tt> are thread-safe.
Iterator methods like <a href="apidocs/org/apache/commons/rdf/api/Graph.html#iterate--">iterate</a>
and <a href="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-">getTriples</a>
might throw a <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/ConcurrentModificationException.html">ConcurrentModificationException</a>
if it detects a thread concurrency modification, although this behaviour is not guaranteed.
Implementations of Commons RDF may specify more specific thread-safety considerations.</p>
 <p>If an implementation does not specify any thread-safety support, then all potentially
concurrent access to a <tt>Graph</tt> must be <tt>synchronized</tt>,
e.g.:</p>
 
@@ -978,7 +991,7 @@ synchronized(graph) {
 </pre></div></div></div>
 <div class="section">
 <h2><a name="Implementations"></a>Implementations</h2>
-<p>The <a href="apidocs/org/apache/commons/rdf/api/package-summary.html">Commons
RDF API</a> is a set of Java interfaces, with implementations provided by several Java
RDF frameworks. See the <a href="implementations.html">implementations</a> page
for an updated list of providers.</p>
+<p>The <a href="apidocs/org/apache/commons/rdf/api/package-summary.html">Commons
RDF API</a> is a set of Java interfaces, which can be implemented by several Java RDF
frameworks. See the <a href="implementations.html">implementations</a> page for
an updated list of providers.</p>
 <p>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 <tt>UnsupportedOperationException</tt>.</p>
 <p>Different RDF frameworks might have different mechanisms to retrieve a Commons RDF
objects like <tt>Graph</tt> or <tt>Triple</tt> (e.g. returned from
a query). Commons RDF provides a <tt>RDFTermFactory</tt> 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).</p>
 <div class="section">
@@ -1009,10 +1022,9 @@ for (Triple t1: g1.getTriples(null, iri1
     }
 }
 </pre></div></div>
-<p><i>Note: Special care might need to be taken for cross-interoperability of
<tt>BlankNode</tt> instances. This is currently under discussion. See <a class="externalLink"
href="https://issues.apache.org/jira/browse/COMMONSRDF-15">COMMONSRDF-15</a></i></p>
+<p><i>Note: Special care might need to be taken for cross-interoperability of
<tt>BlankNode</tt> instances. While multiple triples with the same &#x201c;foreign&#x201d;
<tt>BlankNode</tt> can be added without breaking their connections, the <tt>Graph</tt>
is not required to return blank node instances that <tt>.equals()</tt> those inserted
- specifically it is <b>not</b> required to persist the blank node <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--">uniqueReference</a>.
 See <a class="externalLink" href="https://issues.apache.org/jira/browse/COMMONSRDF-15">COMMONSRDF-15</a>.</i></p>
 <p>The <tt>.equals()</tt> methods of <tt>RDFTerm</tt> interfaces
are explicitly defined, so their instances can be compared across implementations.</p>
-<p><i>Note: The <tt>Graph</tt> implementation is not required to
keep the JVM object reference, e.g. after <tt>g2.add(subj1, pred, obj)</tt> it
is not required to later return the same <tt>subj1</tt> implementation in <tt>g2.getTriples()</tt>.
Special care should be taken if returned values are needs to be casted to implementation specific
types.</i></p>
-<p>The <tt>.hashCode()</tt> is not currently explicitly defined, hence
special care should be taken for cross-interoperability within hashing data structures like
<tt>HashMap</tt>. See <a class="externalLink" href="https://issues.apache.org/jira/browse/COMMONSRDF-14">COMMONSRDF-14</a></p></div></div>
+<p><i>Note: The <tt>Graph</tt> implementation is not required to
keep the JVM object reference, e.g. after <tt>g2.add(subj1, pred, obj)</tt> it
is not required to later return the same <tt>subj1</tt> implementation in <tt>g2.getTriples()</tt>.
Special care should be taken if returned values needs to be casted to implementation specific
types.</i></p></div></div>
 <div class="section">
 <h2><a name="Complete_example"></a>Complete example</h2>
 <p>The complete source code for the examples used in this user guide can be browsed
in <a class="externalLink" href="https://github.com/apache/incubator-commonsrdf/blob/master/examples/src/example/UserGuideTest.java">UserGuideTest.java</a>
within the <a class="externalLink" href="https://github.com/apache/incubator-commonsrdf/tree/master/examples">examples</a>
folder of the Commons RDF <a href="source-repository.html">source code repository</a>.</p></div>



Mime
View raw message