commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r961353 - /websites/production/commonsrdf/content/userguide.html
Date Mon, 10 Aug 2015 11:18:35 GMT
Author: stain
Date: Mon Aug 10 11:18:35 2015
New Revision: 961353

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 Mon Aug 10 11:18:35 2015
@@ -306,9 +306,15 @@
   
 <li><a href="#Complete_example">Complete example</a></li>
 </ul>
+<div class="section">
+<h2><a name="Introduction"></a>Introduction</h2>
 <p><a href="index.html">Commons RDF</a> is an API that intends to directly
describe <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/">RDF 1.1
concepts</a> as a set of corresponding interfaces and methods.</p>
+<div class="section">
+<h3><a name="RDF_concepts"></a>RDF concepts</h3>
 <p>RDF is a <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#data-model">graph-based
data model</a>, where a <i>graph</i> contains a series of <i>triples</i>,
each containing the node-arc-node link <i>subject</i> -&gt; <i>predicate</i>
-&gt; <i>object</i>. Nodes in the graph are represented either as <i>IRIs</i>,
<i>literals</i> and <i>blank nodes</i>. : This user guide does not
intend to give a detailed description of RDF as a data model. To fully understand this user
guide, you should have a brief understanding of the core RDF concepts mentioned above.</p>
-<p>For more information on RDF, see the <a class="externalLink" href="http://www.w3.org/TR/rdf11-primer/">RDF
primer</a> and the <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#data-model">RDF
concepts</a> specification from W3C.</p>
+<p>For more information on RDF, see the <a class="externalLink" href="http://www.w3.org/TR/rdf11-primer/">RDF
primer</a> and the <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#data-model">RDF
concepts</a> specification from W3C.</p></div></div>
+<div class="section">
+<h2><a name="Using_Commons_RDF_from_Maven"></a>Using Commons RDF from Maven</h2>
 <p>To use Commons RDF API from an <a class="externalLink" href="http://maven.apache.org/">Apache
Maven</a> project, add the following dependency to your <tt>pom.xml</tt>:</p>
 
 <div class="source">
@@ -353,9 +359,12 @@
 <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.2.0-incubating-SNAPSHOT&lt;/version&gt;
+        &lt;version&gt;0.1.0-incubating&lt;/version&gt;
     &lt;/dependency&gt;
 </pre></div></div>
+<p>The <tt>&lt;version&gt;</tt> above might not be up to date,
see the [/download.html](download page) for the latest version.</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>
 
@@ -394,7 +403,9 @@ 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>
+<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 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>
 <p>The RDF term interfaces are arranged in this class hierarchy:</p>
 
@@ -416,6 +427,8 @@ Literal aliceLiteral = factory.createLit
 <li><a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a></li>
   </ul></li>
 </ul>
+<div class="section">
+<h3><a name="N-Triples_string"></a>N-Triples string</h3>
 <p>All of the <a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>
types support the <tt>ntriplesString()</tt> method:</p>
 
 <div class="source">
@@ -456,7 +469,9 @@ Example output:
 
 > `_:ef136d20-f1ee-3830-a54b-cd5e489d50fb <http://example.com/name> "Alice" .`
 >
-> `<http://example.com/bob> <http://example.com/name> "Bob" .` -->
+> `<http://example.com/bob> <http://example.com/name> "Bob" .` --></div>
+<div class="section">
+<h3><a name="IRI"></a>IRI</h3>
 <p>An <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a> is
a representation of an <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">Internationalized
Resource Identifier</a>, e.g. <tt>http://example.com/alice</tt> or <tt>http://ns.example.org/vocab#term</tt>.</p>
 
 <blockquote>
@@ -512,7 +527,9 @@ System.out.println(iri.equals(factory.cr
 <blockquote>
 <p><tt>false</tt></p>
 <p><tt>false</tt></p>
-</blockquote>
+</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>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>
 
@@ -560,6 +577,8 @@ System.out.println(b1.equals(new SimpleR
 <p><tt>true</tt></p>
 <p><tt>false</tt></p>
 </blockquote>
+<div class="section">
+<h4><a name="Blank_node_reference"></a>Blank node reference</h4>
 <p>While blank nodes are distinct from IRIs, and don&#x2019;t have inherent universal
identifiers, it can nevertheless be useful for debugging and testing to have a unique reference
string for a particular blank node. For that purpose, BlankNode exposes the <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--">uniqueReference</a>
method:</p>
 
 <div class="source">
@@ -571,7 +590,9 @@ System.out.println(b1.equals(new SimpleR
 <p><tt>735d5e63-96a4-488b-8613-7037b82c74a5</tt></p>
 </blockquote>
 <p>While this reference string might for the <i>simple</i> implementation
also be seen within the <tt>BlankNode.ntriplesString()</tt> result, there is no
such guarantee from the Commons RDF API. Clients who need a globally unique reference for
a blank node should therefore use the <tt>uniqueReference()</tt> method.</p>
-<p><i>Note: While it is recommended for this string to be (or contain) a <a
class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/UUID.html">UUID
string</a>, implementations are free to use any scheme to ensure their blank node references
are globally unique. Therefore no assumptions should be made about this string except that
it is unique per blank node.</i></p>
+<p><i>Note: While it is recommended for this string to be (or contain) a <a
class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/UUID.html">UUID
string</a>, implementations are free to use any scheme to ensure their blank node references
are globally unique. Therefore no assumptions should be made about this string except that
it is unique per blank node.</i></p></div></div>
+<div class="section">
+<h3><a name="Literal"></a>Literal</h3>
 <p>A <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal">literal</a>
in RDF is a value such as a string, number or a date. A <tt>Literal</tt> can only
be used as an <i>object</i> of a <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getObject--">Triple</a>.</p>
 <p>To create a <a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a>
instance from an <tt>RDFTermFactory</tt>, use <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createLiteral-java.lang.String-">createLiteral</a>:</p>
 
@@ -595,6 +616,8 @@ System.out.println(lexical);
 <blockquote>
 <p><tt>Hello world!</tt></p>
 </blockquote>
+<div class="section">
+<h4><a name="Datatype"></a>Datatype</h4>
 <p>All literals in RDF 1.1 have a <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri">datatype</a>
<tt>IRI</tt>, which can be retrieved using <a href="apidocs/org/apache/commons/rdf/api/Literal.html#getDatatype--">Literal.getDatatype()</a>:</p>
 
 <div class="source">
@@ -634,6 +657,8 @@ System.out.println(literalDouble.ntriple
 <blockquote>
 <p><tt>&quot;13.37&quot;^^&lt;http://www.w3.org/2001/XMLSchema#double&gt;</tt></p>
 </blockquote>
+<div class="section">
+<h5><a name="Types"></a>Types</h5>
 <p>The class <a href="apidocs/org/apache/commons/rdf/simple/Types.html">Types</a>,
which is part of the <i>simple</i> implementation, provides <tt>IRI</tt>
constants for the standard XML Schema datatypes like <tt>xsd:dateTime</tt> and
<tt>xsd:float</tt>. Using <tt>Types</tt>, the above example can be
simplified to:</p>
 
 <div class="source">
@@ -649,7 +674,9 @@ System.out.println(literalDouble.ntriple
 
 <blockquote>
 <p><tt>true</tt></p>
-</blockquote>
+</blockquote></div></div>
+<div class="section">
+<h4><a name="Language"></a>Language</h4>
 <p>Literals may be created with an associated <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string">language
tag</a> using the expanded <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createLiteral-java.lang.String-java.lang.String-">createLiteral</a>:</p>
 
 <div class="source">
@@ -697,7 +724,9 @@ System.out.println(literalDouble.getLang
 <blockquote>
 <p><tt>false</tt></p>
 <p><tt>false</tt></p>
-</blockquote>
+</blockquote></div></div></div>
+<div class="section">
+<h2><a name="Triple"></a>Triple</h2>
 <p>A <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-triples">triple</a>
in RDF 1.1 consists of:</p>
 
 <ul>
@@ -774,7 +803,9 @@ if (obj instanceof Literal) {
 
 <blockquote>
 <p><tt>true</tt></p>
-</blockquote>
+</blockquote></div>
+<div class="section">
+<h2><a name="Graph"></a>Graph</h2>
 <p>A <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">graph</a>
is a collection of triples.</p>
 <p>To create a <a href="apidocs/org/apache/commons/rdf/api/Graph.html">Graph</a>
instance from a <tt>RDFTermFactory</tt>, use <a href="apidocs/org/apache/commons/rdf/api/RDFTermFactory.html#createGraph--">createGraph()</a>:</p>
 
@@ -783,6 +814,8 @@ if (obj instanceof Literal) {
 <pre>Graph graph = factory.createGraph();
 </pre></div></div>
 <p>Implementations will typically also have other ways of retrieving a <tt>Graph</tt>,
e.g. by parsing a Turtle file or connecting to a storage backend.</p>
+<div class="section">
+<h3><a name="Adding_triples"></a>Adding triples</h3>
 <p><i>Note: Some <tt>Graph</tt> implementations are immutable, in
which case the below may throw an <tt>UnsupportedOperationException</tt></i>.</p>
 <p>Any <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>
can be added to the graph using the <a href="apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-">add</a>
method:</p>
 
@@ -799,7 +832,9 @@ IRI nameIri = factory.createIRI(&quot;ht
 Literal bobName = factory.createLiteral(&quot;Bob&quot;);
 graph.add(bob, nameIRI, bobName);
 </pre></div></div>
-<p>It is not necessary to check if a triple already exist in the graph, as the underlying
implementation will ignore duplicate triples.</p>
+<p>It is not necessary to check if a triple already exist in the graph, as the underlying
implementation will ignore duplicate triples.</p></div>
+<div class="section">
+<h3><a name="Finding_triples"></a>Finding triples</h3>
 <p>You can check if the graph <a href="apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-">contains</a>
a triple:</p>
 
 <div class="source">
@@ -819,7 +854,9 @@ graph.add(bob, nameIRI, bobName);
 
 <blockquote>
 <p><tt>true</tt></p>
-</blockquote>
+</blockquote></div>
+<div class="section">
+<h3><a name="Size"></a>Size</h3>
 <p>The <a href="apidocs/org/apache/commons/rdf/api/Graph.html#size--">size</a>
of a graph is the count of unique triples:</p>
 
 <div class="source">
@@ -829,7 +866,9 @@ graph.add(bob, nameIRI, bobName);
 
 <blockquote>
 <p><tt>2</tt></p>
-</blockquote>
+</blockquote></div>
+<div class="section">
+<h3><a name="Iterating_over_triples"></a>Iterating over triples</h3>
 <p>The <a href="apidocs/org/apache/commons/rdf/api/Graph.html#iterate--">iterate</a>
method can be used to sequentially iterate over all the triples of the graph:</p>
 
 <div class="source">
@@ -854,7 +893,9 @@ graph.add(bob, nameIRI, bobName);
 
 <blockquote>
 <p><tt>&lt;http://example.com/name&gt;</tt></p>
-</blockquote>
+</blockquote></div>
+<div class="section">
+<h3><a name="Stream_of_triples"></a>Stream of triples</h3>
 <p>For processing of larger graphs, and to access more detailed filtering and processing,
the <a href="apidocs/org/apache/commons/rdf/api/Graph.html#getTriples--">getTriples</a>
method return a Java 8 <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html">Stream</a>.</p>
 
 <div class="source">
@@ -880,7 +921,9 @@ System.out.println(namedB.map(t -&gt; t.
 
 <blockquote>
 <p><tt>&lt;http://example.com/bob&gt;</tt></p>
-</blockquote>
+</blockquote></div>
+<div class="section">
+<h3><a name="Removing_triples"></a>Removing triples</h3>
 <p><i>Note: Some <tt>Graph</tt> implementations are immutable, in
which case the below may throw an <tt>UnsupportedOperationException</tt></i>.</p>
 <p>Triples can be <a href="apidocs/org/apache/commons/rdf/api/Graph.html#remove-org.apache.commons.rdf.api.Triple-">removed</a>
from a graph:</p>
 
@@ -905,7 +948,9 @@ System.out.println(graph.contains(null,
 
 <blockquote>
 <p>false</p>
-</blockquote>
+</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>
@@ -926,10 +971,14 @@ synchronized(graph) {
         // ...
     }
 }
-</pre></div></div>
+</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 class="section">
+<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">
@@ -959,8 +1008,10 @@ for (Triple t1: g1.getTriples(null, iri1
 <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><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>
-<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>
+<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