commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r949459 - /websites/production/commonsrdf/content/userguide.html
Date Tue, 28 Apr 2015 09:14:05 GMT
Author: stain
Date: Tue Apr 28 09:14:04 2015
New Revision: 949459

Log:
Site checkin for project Commons RDF

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 Tue Apr 28 09:14:04 2015
@@ -249,7 +249,12 @@
 
 <ul>
   
-<li><a href="#Introduction">Introduction</a></li>
+<li><a href="#Introduction">Introduction</a>
+  
+<ul>
+    
+<li><a href="#RDF_concepts">RDF concepts</a></li>
+  </ul></li>
   
 <li><a href="#Using_Commons_RDF_from_Maven">Using Commons RDF from Maven</a></li>
   
@@ -259,6 +264,8 @@
   
 <ul>
     
+<li><a href="#N-Triples_string">N-Triples string</a></li>
+    
 <li><a href="#IRI">IRI</a></li>
     
 <li><a href="#Blank_node">Blank node</a>
@@ -622,7 +629,7 @@ System.out.println(datatype.ntriplesStri
 <blockquote>
 <p><tt>&lt;http://www.w3.org/2001/XMLSchema#string&gt;</tt></p>
 </blockquote>
-<p>In RDF 1.1, a <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-simple-literal">simple
literal</a> (as created above) always have the type <tt>http://www.w3.org/2001/XMLSchema#string</tt>
(or <a href="apidocs/org/apache/commons/rdf/simple/Types.html#XSD_STRING">xsd:string</a>
for short). </p>
+<p>In RDF 1.1, a <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-simple-literal">simple
literal</a> (as created above) always have the type <tt>http://www.w3.org/2001/XMLSchema#string</tt>
(or <a href="apidocs/org/apache/commons/rdf/simple/Types.html#XSD_STRING">xsd:string</a>
for short).</p>
 
 <div class="alert alert-warn" role="alert">
 <p><span class="glyphicon glyphicon-warn-sign" aria-hidden="true"></span>
@@ -743,7 +750,7 @@ Triple triple = factory.createTriple(sub
 
 <div class="source">
 <div class="source">
-<pre>BlankNodeOrIRI subj = triple.getSubject(); 
+<pre>BlankNodeOrIRI subj = triple.getSubject();
 System.out.println(subj.ntriplesString());
 </pre></div></div>
 
@@ -754,7 +761,7 @@ System.out.println(subj.ntriplesString()
 
 <div class="source">
 <div class="source">
-<pre>IRI pred = triple.getPredicate(); 
+<pre>IRI pred = triple.getPredicate();
 System.out.println(pred.getIRIString());
 </pre></div></div>
 
@@ -781,7 +788,7 @@ System.out.println(obj.ntriplesString())
     System.out.println(s);
 }
 // ..
-if (obj instanceof Literal) { 
+if (obj instanceof Literal) {
     IRI type = ((Literal) obj).getDatatype();
     System.out.println(type);
 }
@@ -941,13 +948,14 @@ System.out.println(graph.contains(null,
 
 <blockquote>
 <p>false</p>
-</blockquote>
-<h1>Mutability and thread safety</h1>
+</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>.equal()</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>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>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>
 
 <div class="source">
@@ -961,15 +969,16 @@ synchronized(graph) {
 synchronized(graph) {
     for (Triple t : graph) {
         // ...
-    } 
+    }
 }
-</pre></div></div>
-<h1>Implementations</h1>
+</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>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></div>
+<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">
-<h2><a name="Cross-compatibility"></a>Cross-compatibility</h2>
+<h3><a name="Cross-compatibility"></a>Cross-compatibility</h3>
 <p>While different frameworks will have their own classes implementing the Commons
RDF interfaces, Commons RDF objects are intended to be cross-compatible. Thus a client would
be able to mix and match objects from multiple implementations:</p>
 
 <div class="source">
@@ -989,7 +998,7 @@ Graph g2 = new BarGraph(&quot;localhost&
 IRI iri1 = fooFactory.createIRI(&quot;http://example.com/property1&quot;);
 
 // Both Triple and RDFTerm instances can be used
-// 
+//
 for (Triple t1: g1.getTriples(null, iri1, null)) {  
     if (g2.contains(t1.getSubject(), null, t1.getObject())) {
       g2.remove(t1);
@@ -997,11 +1006,12 @@ 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>The <tt>.equals()</tt> methods of <tt>RDFTerm</tt> interfaces
are explicitly defined, so their instances can be compared across implementations. </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>
-<h1>Complete example</h1>
-<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 source code repository.</p></div>
+<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>
+<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>
 					</td>
 				</tr>
 			</table>



Mime
View raw message