commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r1001920 [8/8] - in /websites/staging/commonsrdf/content: ./ apidocs/ apidocs/org/apache/commons/rdf/api/ apidocs/org/apache/commons/rdf/api/class-use/ apidocs/org/apache/commons/rdf/experimental/ apidocs/org/apache/commons/rdf/experimental...
Date Wed, 30 Nov 2016 23:42:48 GMT
Added: websites/staging/commonsrdf/content/userguide.html
==============================================================================
--- websites/staging/commonsrdf/content/userguide.html (added)
+++ websites/staging/commonsrdf/content/userguide.html Wed Nov 30 23:42:47 2016
@@ -0,0 +1,1315 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 30 November 2016
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="Date-Revision-yyyymmdd" content="20161130" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>Apache Commons RDF &#x2013; User Guide</title>
+
+  <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" />
+  <link rel="stylesheet" href="./css/site.css" type="text/css" />
+    <link rel="stylesheet" href="./css/print.css" media="print" />
+
+  <script type="text/javascript" src="./js/jquery.min.js"></script>
+  <script type="text/javascript" src="./js/bootstrap.min.js"></script>
+  <script type="text/javascript" src="./js/prettify.min.js"></script>
+  <script type="text/javascript" src="./js/site.js"></script>
+
+              
+      </head>
+
+  <body class="composite">
+                                        <a href="./" id="bannerLeft" title="Apache Commons RDF logo">
+                                                                                                <img class="logo-left" src="images/commonsrdf-logo.png"  alt="Apache Commons RDF logo"/>
+                </a>
+                    <div class="clear"></div>
+
+    <div class="navbar">
+      <div class="navbar-inner">
+        <div class="container-fluid">
+          <a class="brand" href="https://commons.apache.org/proper/commons-rdf/">Commons RDF &trade;</a>
+          <ul class="nav">      
+                    
+            <li id="publishDate">Last Published: 30 November 2016</li>
+      <li class="divider">|</li> <li id="projectVersion">Version: 0.4.0-SNAPSHOT</li>
+  </ul>
+                    <div class="pull-right">  <ul class="nav">
+            <li>
+                  <a href="http://www.apachecon.com/" class="externalLink" title="ApacheCon">
+    ApacheCon</a>
+      </li>
+          <li>
+                  <a href="http://www.apache.org" class="externalLink" title="Apache">
+    Apache</a>
+      </li>
+          <li>
+                  <a href="http://commons.apache.org/" class="externalLink" title="Commons">
+    Commons</a>
+      </li>
+    </ul>
+</div>
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+      <table class="layout-table">
+        <tr>
+          <td class="sidebar">
+            <div class="well sidebar-nav">
+                    <ul class="nav nav-list">
+                                  <li class="nav-header">Project</li>
+                                        <li class="none">
+                  <a href="index.html" title="Home">
+    Home</a>
+          </li>
+                             <li class="none">
+                  <a href="introduction.html" title="Introduction">
+    Introduction</a>
+          </li>
+                             <li class="none">
+                  <a href="apidocs/index.html?org/apache/commons/rdf/api/package-summary.html" title="API">
+    API</a>
+          </li>
+                             <li class="none">
+                  <a href="implementations.html" title="Implementations">
+    Implementations</a>
+          </li>
+                               <li class="none active">
+                  <a href="userguide.html" title="User Guide">
+    User Guide</a>
+          </li>
+                             <li class="none">
+                  <a href="download.html" title="Download">
+    Download</a>
+          </li>
+                             <li class="none">
+                  <a href="contributing.html" title="Contributing">
+    Contributing</a>
+          </li>
+                             <li class="none">
+                  <a href="team-list.html" title="Team">
+    Team</a>
+          </li>
+                 </ul>
+      <ul class="nav nav-list">
+                                  <li class="nav-header">Tools</li>
+                                        <li class="none">
+                  <a href="mail-lists.html" title="Mailing Lists">
+    Mailing Lists</a>
+          </li>
+                             <li class="none">
+                  <a href="https://git-wip-us.apache.org/repos/asf/commons-rdf.git" class="externalLink" title="Source (Git)">
+    Source (Git)</a>
+          </li>
+                             <li class="none">
+                  <a href="https://github.com/apache/commons-rdf/" class="externalLink" title="Source (GitHub mirror)">
+    Source (GitHub mirror)</a>
+          </li>
+                             <li class="none">
+                  <a href="https://issues.apache.org/jira/browse/COMMONSRDF" class="externalLink" title="Issues (Jira)">
+    Issues (Jira)</a>
+          </li>
+                 </ul>
+      <ul class="nav nav-list">
+                                        <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li>
+                                                                                                                                                                                                                                                                                                <li class="collapsed">
+                  <a href="project-info.html" title="Project Information">
+    Project Information</a>
+                    </li>
+                                                                                                                                                                                                             <li class="collapsed">
+                  <a href="project-reports.html" title="Project Reports">
+    Project Reports</a>
+                    </li>
+                 </ul>
+      <ul class="nav nav-list">
+                                  <li class="nav-header">Commons</li>
+                                        <li class="none">
+                  <a href="http://commons.apache.org/" class="externalLink" title="Home">
+    Home</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/licenses/" class="externalLink" title="License">
+    License</a>
+          </li>
+                                                                               <li class="collapsed">
+                  <a href="http://commons.apache.org/components.html" class="externalLink" title="Components">
+    Components</a>
+                    </li>
+                                                                               <li class="collapsed">
+                  <a href="http://commons.apache.org/sandbox/index.html" class="externalLink" title="Sandbox">
+    Sandbox</a>
+                    </li>
+                                                                               <li class="collapsed">
+                  <a href="http://commons.apache.org/dormant/index.html" class="externalLink" title="Dormant">
+    Dormant</a>
+                    </li>
+                 </ul>
+      <ul class="nav nav-list">
+                                  <li class="nav-header">General Information</li>
+                                        <li class="none">
+                  <a href="http://commons.apache.org/security.html" class="externalLink" title="Security">
+    Security</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/volunteering.html" class="externalLink" title="Volunteering">
+    Volunteering</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/patches.html" class="externalLink" title="Contributing Patches">
+    Contributing Patches</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/building.html" class="externalLink" title="Building Components">
+    Building Components</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/commons-parent-pom.html" class="externalLink" title="Commons Parent Pom">
+    Commons Parent Pom</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/build-plugin/index.html" class="externalLink" title="Commons Build Plugin">
+    Commons Build Plugin</a>
+          </li>
+                             <li class="none">
+                  <a href="http://commons.apache.org/releases/index.html" class="externalLink" title="Releasing Components">
+    Releasing Components</a>
+          </li>
+                             <li class="none">
+                  <a href="http://wiki.apache.org/commons/FrontPage" class="externalLink" title="Wiki">
+    Wiki</a>
+          </li>
+                 </ul>
+      <ul class="nav nav-list">
+                                  <li class="nav-header">ASF</li>
+                                        <li class="none">
+                  <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">
+    How the ASF works</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">
+    Get Involved</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/dev/" class="externalLink" title="Developer Resources">
+    Developer Resources</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/foundation/policies/conduct.html" class="externalLink" title="Code of Conduct">
+    Code of Conduct</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">
+    Sponsorship</a>
+          </li>
+                             <li class="none">
+                  <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
+    Thanks</a>
+          </li>
+                 </ul>
+              </div>
+            <div id="poweredBy">
+                                                                                                                    <a href="http://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy">
+        <img class="builtBy"  alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png"    />
+      </a>
+                                                                                                    <a href="http://maven.apache.org/" title="Maven" class="builtBy">
+        <img class="builtBy"  alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png"    />
+      </a>
+                      </div>
+          </td>
+          <td class="content">
+            <!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements. See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership. The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    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.3.0-incubating</tt> of the Commons RDF <a href="apidocs/">API</a>.</p>
+
+<ul>
+  
+<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>
+  
+<li><a href="#Creating_Commons_RDF_instances">Creating Commons RDF instances</a></li>
+  
+<li><a href="#Finding_an_RDF_implementation">Finding an RDF implementation</a></li>
+  
+<li><a href="#Using_an_RDF_implementation">Using an RDF implementation</a></li>
+  
+<li><a href="#RDF_terms">RDF terms</a>
+  
+<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>
+    
+<ul>
+      
+<li><a href="#Blank_node_reference">Blank node reference</a></li>
+    </ul></li>
+    
+<li><a href="#Literal">Literal</a>
+    
+<ul>
+      
+<li><a href="#Datatype">Datatype</a>
+      
+<ul>
+        
+<li><a href="#Types">Types</a></li>
+      </ul></li>
+      
+<li><a href="#Language">Language</a></li>
+    </ul></li>
+  </ul></li>
+  
+<li><a href="#Triple">Triple</a></li>
+  
+<li><a href="#Quad">Quad</a></li>
+  
+<li><a href="#Graph">Graph</a>
+  
+<ul>
+    
+<li><a href="#Adding_triples">Adding triples</a></li>
+    
+<li><a href="#Finding_triples">Finding triples</a></li>
+    
+<li><a href="#Size">Size</a></li>
+    
+<li><a href="#Iterating_over_triples">Iterating over triples</a></li>
+    
+<li><a href="#Stream_of_triples">Stream of triples</a></li>
+    
+<li><a href="#Removing_triples">Removing triples</a></li>
+  </ul></li>
+  
+<li><a href="#Dataset">Dataset</a>
+  
+<ul>
+    
+<li><a href="#Dataset_operations">Dataset operations</a></li>
+  </ul></li>
+  
+<li><a href="#Mutability_and_thread_safety">Mutability and thread safety</a></li>
+  
+<li><a href="#Implementations">Implementations</a>
+  
+<ul>
+    
+<li><a href="#Cross-compatibility">Cross-compatibility</a></li>
+  </ul></li>
+  
+<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></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">
+<div class="source">
+<pre>&lt;dependencies&gt;
+    &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.3.0-incubating&lt;/version&gt;
+    &lt;/dependency&gt;
+&lt;/dependencies&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>
+<p>If you are testing a <tt>SNAPSHOT</tt> version, then you will have to either build Commons RDF from <a class="externalLink" href="https://github.com/apache/commons-rdf">source</a>, or add this <a class="externalLink" href="https://github.com/apache/commons-rdf#snapshot-repository">snapshot repository</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>&lt;repositories&gt;
+  &lt;repository&gt;
+    &lt;id&gt;apache.snapshots&lt;/id&gt;
+    &lt;name&gt;Apache Snapshot Repository&lt;/name&gt;
+    &lt;url&gt;http://repository.apache.org/snapshots&lt;/url&gt;
+    &lt;releases&gt;
+      &lt;enabled&gt;false&lt;/enabled&gt;
+    &lt;/releases&gt;
+  &lt;/repository&gt;
+&lt;/repositories&gt;
+</pre></div></div>
+<p>As Commons RDF requires Java 8 or later, you will also need:</p>
+
+<div class="source">
+<div class="source">
+<pre>&lt;properties&gt;
+  &lt;maven.compiler.source&gt;1.8&lt;/maven.compiler.source&gt;
+  &lt;maven.compiler.target&gt;1.8&lt;/maven.compiler.target&gt;
+&lt;/properties&gt;
+</pre></div></div>
+<p>In the examples below we will use the <a href="apidocs/org/apache/commons/rdf/simple/package-summary.html"><i>simple</i> implementation</a>, but the examples should be equally applicable to other <a href="implementations.html">implementations</a>. To add a dependency for the <i>simple</i> implementation, add to your <tt>&lt;dependencies&gt;</tt>:</p>
+
+<div class="source">
+<div class="source">
+<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.3.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/RDF.html">RDF</a> implementation.</p>
+<div class="section">
+<h3><a name="Finding_an_RDF_implementation"></a>Finding an RDF implementation</h3>
+<p>The <a href="implementations.html">implementations</a> of <tt>RDF</tt> can usually be created using a normal Java constructor, for instance the <i>simple</i> implementation from <a href="apidocs/org/apache/commons/rdf/simple/SimpleRDF.html">SimpleRDF</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>import org.apache.commons.rdf.api.*;
+import org.apache.commons.rdf.simple.SimpleRDF;
+// ...
+RDF rdf = new SimpleRDF();
+</pre></div></div>
+<p>If you don&#x2019;t want to depend on instantiating a concrete <tt>RDF</tt> implementation, you can alternatively use the <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html">ServiceLoader</a> to lookup any <tt>RDF</tt> implementations found on the classpath:</p>
+
+<div class="source">
+<div class="source">
+<pre>import java.util.Iterator;
+import java.util.ServiceLoader;
+
+import org.apache.commons.rdf.api.*;
+// ...
+ServiceLoader&lt;RDF&gt; loader = ServiceLoader.load(RDF.class);
+Iterator&lt;RDF&gt; iterator = loader.iterator();
+RDF rdf = 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>
+<p>When using the factory method <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode-java.lang.String-">createBlankNode(String)</a> from different sources, care should be taken to create correspondingly different <tt>RDF</tt> instances.</p></div>
+<div class="section">
+<h3><a name="Using_an_RDF_implementation"></a>Using an RDF implementation</h3>
+<p>Using the <tt>RDF</tt> implementation 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">
+<div class="source">
+<pre>BlankNode aliceBlankNode = rdf.createBlankNode();
+IRI nameIri = rdf.createIRI(&quot;http://example.com/name&quot;);
+Literal aliceLiteral = rdf.createLiteral(&quot;Alice&quot;);
+</pre></div></div>
+<p>You can also create a stand-alone <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Triple triple = rdf.createTriple(aliceBlankNode, nameIri, aliceLiteral);
+</pre></div></div>
+<p>The <a href="apidocs/org/apache/commons/rdf/api/RDF.html">RDF</a> interface also contains more specific variants of some of the methods above, e.g. to create a typed literal.</p>
+<p>In addition, the <a href="implementations.html">implementations</a> of <tt>RDF</tt> may add specific converter methods and implementation-specific subtypes for interoperability with their underlying RDF framework&#x2019;s API.</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>
+<p>The RDF term interfaces are arranged in this type hierarchy:</p>
+
+<ul>
+  
+<li><a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>
+  
+<ul>
+    
+<li><a href="apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html">BlankNodeOrIRI</a>
+    
+<ul>
+      
+<li><a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a></li>
+      
+<li><a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a></li>
+    </ul></li>
+    
+<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">
+<div class="source">
+<pre>System.out.println(aliceBlankNode.ntriplesString());
+System.out.println(nameIri.ntriplesString());
+System.out.println(aliceLiteral.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>_:ef136d20-f1ee-3830-a54b-cd5e489d50fb</tt></p>
+<p><tt>&lt;http://example.com/name&gt;</tt></p>
+<p><tt>&quot;Alice&quot;</tt></p>
+</blockquote>
+<p>This returns the <a class="externalLink" href="http://www.w3.org/TR/n-triples">N-Triples</a> canonical form of the term, which can be useful for debugging or simple serialization.</p>
+<p><i>Note: The <tt>.toString()</tt> of the <tt>simple</tt> implementation used in some of these examples use <tt>ntriplesString()</tt> internally, but Commons RDF places no such formal requirement on the <tt>.toString()</tt> method. Clients that rely on a canonical N-Triples-compatible string should instead use <tt>ntriplesString()</tt>.</i></p>
+<!-- Not relevant here
+
+As an example of using `ntriplesString()`, here is how one could write a basic
+N-Triples-compatible serialization of a
+[Graph](apidocs/org/apache/commons/rdf/api/Graph.html):
+
+```java
+public class NTriplesSerializer {
+    public static String tripleAsString(Triple t) {
+        return t.getSubject().ntriplesString() + " " +
+               t.getPredicate().ntriplesString() + " " +
+               t.getObject().ntriplesString() + " .";
+    }
+    public static void writeGraph(Graph graph, Path graphFile) throws Exception {
+        Stream<CharSequence> stream = graph.stream().map(NTriplesSerializer::tripleAsString);
+        Files.write(graphFile, stream::iterator, StandardCharsets.UTF_8);
+    }
+}
+```
+
+Example output:
+
+> `_:ef136d20-f1ee-3830-a54b-cd5e489d50fb <http://example.com/name> "Alice" .`
+>
+> `<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>
+<p>IRIs in the RDF abstract syntax MUST be absolute, and MAY contain a fragment identifier.</p>
+</blockquote>
+<p>An IRI identifies a resource that can be used as a <i>subject</i>, <i>predicate</i> or <i>object</i> of a <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a> or <a href="apidocs/org/apache/commons/rdf/api/Quad.html">Quad</a>, where it can also be used a <i>graph name</i>.</p>
+<p>To create an <tt>IRI</tt> instance from an <tt>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createIRI-java.lang.String-">createIRI</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>IRI iri = rdf.createIRI(&quot;http://example.com/alice&quot;);
+</pre></div></div>
+<p>You can retrieve the IRI string using <a href="apidocs/org/apache/commons/rdf/api/IRI.html#getIRIString--">getIRIString</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(iri.getIRIString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>http://example.com/alice</tt></p>
+</blockquote>
+<p><i>Note: The <b>IRI</b> string might contain non-ASCII characters which must be %-encoded for applications that expect an <b>URI</b>. It is currently out of scope for Commons RDF to perform such a conversion, however implementations might provide separate methods for that purpose.</i></p>
+<p>Two IRI instances can be compared using the <a href="apidocs/org/apache/commons/rdf/api/IRI.html#equals-java.lang.Object-">equals</a> method, which uses <a class="externalLink" href="http://tools.ietf.org/html/rfc3987#section-5.3.1">simple string comparison</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>IRI iri2 = rdf.createIRI(&quot;http://example.com/alice&quot;);
+System.out.println(iri.equals(iri2));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+
+<div class="source">
+<div class="source">
+<pre>IRI iri3 = rdf.createIRI(&quot;http://example.com/alice/./&quot;);
+System.out.println(iri.equals(iri3));
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+</blockquote>
+<p>Note that IRIs are never equal to objects which are not themselves instances of <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(iri.equals(&quot;http://example.com/alice&quot;));
+System.out.println(iri.equals(rdf.createLiteral(&quot;http://example.com/alice&quot;)));
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+<p><tt>false</tt></p>
+</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 <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a> or <a href="apidocs/org/apache/commons/rdf/api/Quad.html">Quad</a>, where it can also be used a <i>graph name</i>.</p>
+<p>To create a new <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a> instance from a <tt>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode--">createBlankNode</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNode bnode = rdf.createBlankNode();
+</pre></div></div>
+<p>Every call to <tt>createBlankNode()</tt> returns a brand new blank node which can be used in multiple triples in multiple graphs. Thus every such blank node can only be <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-">equal</a> to itself:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(bnode.equals(bnode));
+System.out.println(bnode.equals(rdf.createBlankNode()));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+<p><tt>false</tt></p>
+</blockquote>
+<p>Sometimes it can be beneficial to create a blank node based on a localized <i>name</i>, without needing to keep object references to earlier <tt>BlankNode</tt> instances. For that purpose, the <tt>RDF</tt> interface provides the <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createBlankNode-java.lang.String-">expanded createBlankNode</a> method:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNode b1 = rdf.createBlankNode(&quot;b1&quot;);
+</pre></div></div>
+<p>Note that there is no requirement for the <a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html#ntriplesString--">ntriplesString()</a> of the BlankNode to reflect the provided <tt>name</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(b1.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>_:6c0f628f-02cb-3634-99db-0e1e99d2e66d</tt></p>
+</blockquote>
+<p>Any later <tt>createBlankNode(&quot;b1&quot;)</tt> <b>on the same <tt>RDF</tt> instance</b> returns a <tt>BlankNode</tt> which are <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-">equal</a> to the previous b1:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(b1.equals(rdf.createBlankNode(&quot;b1&quot;)));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+<p>That means that care should be taken to create a new <tt>RDF</tt> instance if making &#x201c;different&#x201d; blank nodes (e.g. parsed from a different RDF file) which accidfentally might have the same name:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(b1.equals(new SimpleRDF().createBlankNode(&quot;b1&quot;)));
+</pre></div></div>
+
+<blockquote>
+<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">
+<div class="source">
+<pre>System.out.println(bnode.uniqueReference());
+</pre></div></div>
+
+<blockquote>
+<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></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> or <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getObject--">Quad</a></p>
+<p>To create a <a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a> instance from an <tt>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createLiteral-java.lang.String-">createLiteral</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Literal literal = rdf.createLiteral(&quot;Hello world!&quot;);
+System.out.println(literal.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>&quot;Hello world!&quot;</tt></p>
+</blockquote>
+<p>The <i>lexical value</i> (what is inside the quotes) can be retrieved using <a href="apidocs/org/apache/commons/rdf/api/Literal.html#getLexicalForm--">getLexicalForm()</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>String lexical = literal.getLexicalForm();
+System.out.println(lexical);
+</pre></div></div>
+
+<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">
+<div class="source">
+<pre>IRI datatype = literal.getDatatype();
+System.out.println(datatype.ntriplesString());
+</pre></div></div>
+
+<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>
+
+<div class="alert alert-warn" role="alert">
+<p><span class="glyphicon glyphicon-warn-sign" aria-hidden="true"></span>
+<!-- Markdown not supported inside HTML -->
+<b>Note:</b>
+RDF 1.0 had the datatype
+<tt>http://www.w3.org/1999/02/22-rdf-syntax-ns#PlainLiteral</tt> to
+indicate <i>plain literals</i> (untyped), which were distinct from
+<tt>http://www.w3.org/2001/XMLSchema#string</tt> (typed). Commons
+RDF assumes RDF 1.1, which merges the two concepts as the second type, however
+particular implementations might have explicit options for RDF 1.0 support, in
+which case you might find <tt>Literal</tt> instances with the deprecated
+<a href="apidocs/org/apache/commons/rdf/simple/Types.html#RDF_PLAINLITERAL">plain
+literal</a> data type.
+</p></div>
+<p>To create a literal with any other <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri">datatype</a> (e.g. <tt>xsd:double</tt>), then create the datatype <tt>IRI</tt> and pass it to the expanded <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createLiteral-java.lang.String-org.apache.commons.rdf.api.IRI-">createLiteral</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>IRI xsdDouble = rdf.createIRI(&quot;http://www.w3.org/2001/XMLSchema#double&quot;);
+Literal literalDouble = rdf.createLiteral(&quot;13.37&quot;, xsdDouble);
+System.out.println(literalDouble.ntriplesString());
+</pre></div></div>
+
+<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">
+<div class="source">
+<pre>Literal literalDouble2 = rdf.createLiteral(&quot;13.37&quot;, Types.XSD_DOUBLE);
+</pre></div></div>
+<p>As the constants in <tt>Types</tt> are all instances of <tt>IRI</tt>, so they can also be used for comparisons:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(Types.XSD_STRING.equals(literal.getDatatype()));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</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/RDF.html#createLiteral-java.lang.String-java.lang.String-">createLiteral</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Literal inSpanish = rdf.createLiteral(&quot;&#xa1;Hola, Mundo!&quot;, &quot;es&quot;);
+System.out.println(inSpanish.ntriplesString());
+System.out.println(inSpanish.getLexicalForm());
+</pre></div></div>
+
+<blockquote>
+<p><tt>&quot;&#xa1;Hola, Mundo!&quot;@es</tt></p>
+<p><tt>&#xa1;Hola, Mundo!</tt></p>
+</blockquote>
+<p>A literal with a language tag always have the implied type <tt>http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(inSpanish.getDatatype().ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>&lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#langString&gt;</tt></p>
+</blockquote>
+<p>The language tag can be retrieved using <a href="apidocs/org/apache/commons/rdf/api/Literal.html#getLanguageTag--">getLanguageTag()</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Optional&lt;String&gt; tag = inSpanish.getLanguageTag();
+if (tag.isPresent()) {
+    System.out.println(tag.get());
+}
+</pre></div></div>
+
+<blockquote>
+<p><tt>es</tt></p>
+</blockquote>
+<p>The language tag is behind an <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/Optional.html">Optional</a> as it won&#x2019;t be present for any other datatypes than <tt>http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(literal.getLanguageTag().isPresent());
+System.out.println(literalDouble.getLanguageTag().isPresent());
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+<p><tt>false</tt></p>
+</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>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getSubject--">subject</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a> or a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a></li>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getPredicate--">predicate</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a></li>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getObject--">object</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a>, a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a> or a <a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a></li>
+</ul>
+<p>To construct a <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a> from an <tt>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createTriple-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">createTriple</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNodeOrIRI subject = rdf.createBlankNode();
+IRI predicate = rdf.createIRI(&quot;http://example.com/says&quot;);
+RDFTerm object = rdf.createLiteral(&quot;Hello&quot;);
+Triple triple = rdf.createTriple(subject, predicate, object);
+</pre></div></div>
+<p>The subject of the triple can be retrieved using <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getSubject--">getSubject</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNodeOrIRI subj = triple.getSubject();
+System.out.println(subj.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>_:7b914fbe-aa2a-4551-b71c-8ac0e2b52b26</tt></p>
+</blockquote>
+<p>Likewise the predicate using <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getPredicate--">getPredicate</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>IRI pred = triple.getPredicate();
+System.out.println(pred.getIRIString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>http://example.com/says</tt></p>
+</blockquote>
+<p>Finally, the object of the triple is returned with <a href="apidocs/org/apache/commons/rdf/api/Triple.html#getObject--">getObject</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>RDFTerm obj = triple.getObject();
+System.out.println(obj.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>&quot;Hello&quot;</tt></p>
+</blockquote>
+<p>For the subject and object you might find it useful to do Java type checking and casting from the types <a href="apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html">BlankNodeOrIRI</a> and <a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>if (subj instanceof IRI) {
+    String s = ((IRI) subj).getIRIString();
+    System.out.println(s);
+}
+// ..
+if (obj instanceof Literal) {
+    IRI type = ((Literal) obj).getDatatype();
+    System.out.println(type);
+}
+</pre></div></div>
+<p>In Commons RDF, <tt>BlankNodeOrIRI</tt> instances are always one of <tt>BlankNode</tt> or <tt>IRI</tt>, and <tt>RDFTerm</tt> instances one of <tt>BlankNode</tt>, <tt>IRI</tt> or <tt>Literal</tt>.</p>
+<p>A <tt>Triple</tt> is considered <a href="apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-">equal</a> to another <tt>Triple</tt> if each of their subject, predicate and object are equal:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(triple.equals(rdf.createTriple(subj, pred, obj)));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+<p>This equality is true even across implementations, as Commons RDF has specified <i>equality semantics</i> for <a href="apidocs/org/apache/commons/rdf/api/Triple.html#equals-java.lang.Object-">Triples</a>, <a href="apidocs/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-">Quads</a>, <a href="apidocs/org/apache/commons/rdf/api/IRI.html#equals-java.lang.Object-">IRIs</a>, <a href="apidocs/org/apache/commons/rdf/api/Literal.html#equals-java.lang.Object-">Literals</a> and even <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-">BlankNodes</a>.</p></div>
+<div class="section">
+<h2><a name="Quad"></a>Quad</h2>
+<p>A <i>quad</i> is a triple with an associated <i>graph name</i>, and can be a statement in a <a class="externalLink" href="http://www.w3.org/TR/rdf11-concepts/#section-dataset">dataset</a>.</p>
+<p>Commons RDF represents such statements using the class <a href="apidocs/org/apache/commons/rdf/api/Quad.html">Quad</a>, which consists of:</p>
+
+<ul>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getSubject--">subject</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a> or a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a></li>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getPredicate--">predicate</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a></li>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getObject--">object</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a>, a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a> or a <a href="apidocs/org/apache/commons/rdf/api/Literal.html">Literal</a></li>
+  
+<li>The <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getGraphName--">graph name</a>, which is an <a href="apidocs/org/apache/commons/rdf/api/IRI.html">IRI</a> or a <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html">BlankNode</a>; wrapped as an <tt>java.util.Optional</tt></li>
+</ul>
+<p>To create a <tt>Quad</tt>, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">createQuad</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNodeOrIRI graph = rdf.createIRI(&quot;http://example.com/graph&quot;);
+BlankNodeOrIRI subject = rdf.createBlankNode();
+IRI predicate = rdf.createIRI(&quot;http://example.com/says&quot;);
+RDFTerm object = rdf.createLiteral(&quot;Hello&quot;);
+Quad quad = rdf.createQuad(graph, subject, predicate, object);
+</pre></div></div>
+<p>The subject, predicate and object are accessible just like in a <tt>Triple</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>IRI pred = quad.getPredicate();
+System.out.println(pred.ntriplesString());
+</pre></div></div>
+
+<blockquote>
+<p><tt>&lt;http://example.com/says&gt;</tt></p>
+</blockquote>
+<div class="section">
+<h3><a name="Graph_name"></a>Graph name</h3>
+<p>The quad&#x2019;s <i>graph name</i> is accessible using <a href="apidocs/org/apache/commons/rdf/api/Quad.html#getGraphName--">getGraphName()</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Optional&lt;BlankNodeOrIRI&gt; g = quad.getGraphName();
+</pre></div></div>
+<p>The graph name is represented as an <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html">Optional</a>, where <tt>Optional.empty()</tt> indicates that the quad is in the <a class="externalLink" href="https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph">default graph</a>, while if the <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#isPresent--">Optional.isPresent()</a> then the graph name <tt>BlankNodeOrIRI</tt> is accessible with <tt>g.get()</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>if (g.isPresent()) {
+  BlankNodeOrIRI graphName = g.get();
+  System.out.println(graphName.ntriplesString());
+}
+</pre></div></div>
+
+<blockquote>
+<p><tt>&lt;http://example.com/graph&gt;</tt></p>
+</blockquote>
+<p>To create a quad in the <i>default graph</i>, supply <tt>null</tt> as the graph name to the factory method:</p>
+
+<div class="source">
+<div class="source">
+<pre>Quad otherQuad = rdf.createQuad(null, subject, predicate, object);
+System.out.println(otherQuad.getGraphName().isPresent());
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+</blockquote>
+<p>Note that a <tt>Quad</tt> will never return <tt>null</tt> on any of its getters, which is why the graph name is wrapped as an <tt>Optional</tt>. This also allows the use of Java 8 functional programming patterns like:</p>
+
+<div class="source">
+<div class="source">
+<pre>String str = quad.map(BlankNodeOrIRI::ntriplesString).orElse(&quot;&quot;);
+</pre></div></div>
+<p>As the <tt>createQuad</tt> method does not expect an <tt>Optional</tt>, you might use this <tt>orElse</tt> pattern to represent the default graph as <tt>null</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>BlankNodeOrIRI g = quad.getGraphName().orElse(null);
+if (g == null) {
+  System.out.println(&quot;In default graph&quot;);
+}
+rdf.createQuad(g,s,p,o);
+</pre></div></div>
+<p>Care should be taken with regards when accessing graph named with <tt>BlankNode</tt>s, as the graph name will be compared using <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#equals-java.lang.Object-">BlankNode&#x2019;s equality semantics</a>.</p></div>
+<div class="section">
+<h3><a name="Quad_equality"></a>Quad equality</h3>
+<p>A <tt>Quad</tt> is considered <a href="apidocs/org/apache/commons/rdf/api/Quad.html#equals-java.lang.Object-">equal</a> to another <tt>Quad</tt> if each of the graph name, subject, predicate and object are equal:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(quad.equals(otherQuad));
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+</blockquote></div>
+<div class="section">
+<h3><a name="Converting_quads_to_triples"></a>Converting quads to triples</h3>
+<p>All quads can be viewed as triples - in a way &#x201c;stripping&#x201d; the graph name:</p>
+
+<div class="source">
+<div class="source">
+<pre>Triple quadAsTriple = quad.asTriple();
+</pre></div></div>
+<p>This can be utilized to compare quads at triple-level (considering just s/p/o):</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(quadAsTriple.equals(otherQuad.asTriple());
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+<p>To create a triple from a quad, you will need to use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createQuad-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">RDF.createQuad</a> providing the desired graph name:</p>
+
+<div class="source">
+<div class="source">
+<pre>Triple t; // ..
+BlankNodeOrIRI g; // ..
+Quad q = rdf.createQuad(g, t.getSubject(), t.getPredicate(), t.getObject());
+</pre></div></div></div>
+<div class="section">
+<h3><a name="TripleLike"></a>TripleLike</h3>
+<p>Note that the class <a href="apidocs/org/apache/commons/rdf/api/Quad.html">Quad</a> does <b>not</b> extend the class <a href="apidocs/org/apache/commons/rdf/api/Triple.html">Triple</a>, as they have different equality semantics.</p>
+<p>Both <tt>Triple</tt> and <tt>Quad</tt> do however share a common &#x201c;duck-typing&#x201d; interface <a href="apidocs/org/apache/commons/rdf/api/TripleLike.html">TripleLike</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>TripleLike a = quad;
+TripleLike b = quad.asTriple();
+</pre></div></div>
+<p>Unlike <tt>Triple</tt> and <tt>Quad</tt>, <tt>TripleLike</tt> does not mandate any specific <tt>.equals()</tt>, it just provides common access to <a href="apidocs/org/apache/commons/rdf/api/TripleLike.html#getSubject--">getSubject()</a> <a href="apidocs/org/apache/commons/rdf/api/TripleLike.html#getPredicate--">getPredicate()</a> and <a href="apidocs/org/apache/commons/rdf/api/TripleLike.html#getObject--">getObject()</a>.</p>
+
+<div class="source">
+<div class="source">
+<pre>RDFTerm s = a.getSubject();
+RDFTerm p = a.getPredicate();
+RDFTerm o = a.getObject();
+</pre></div></div>
+<p>TripleLike can also be used for <a class="externalLink" href="https://www.w3.org/TR/rdf11-concepts/#section-generalized-rdf">generalized RDF</a> therefore all of its parts are returned as <a href="apidocs/org/apache/commons/rdf/api/RDFTerm.html">RDFTerm</a>.</p>
+<p>For generalized quads the <a href="apidocs/org/apache/commons/rdf/api/QuadLike.html">QuadLike</a> interface extends <tt>TripleLike</tt> to add <a href="apidocs/org/apache/commons/rdf/api/QuadLike.html#getGraphName--">getGraphName()</a> as an <tt>Optional&lt;T extends RDFTerm&gt;</tt>.</p></div></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>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createGraph--">createGraph()</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Graph graph = rdf.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>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>
+
+<div class="source">
+<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 <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">
+<pre>IRI bob = rdf.createIRI(&quot;http://example.com/bob&quot;);
+IRI nameIri = rdf.createIRI(&quot;http://example.com/name&quot;);
+Literal bobName = rdf.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></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">
+<div class="source">
+<pre>System.out.println(graph.contains(triple));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+<p>The expanded <i>subject/predicate/object</i> call for <a href="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-">Graph.contains()</a> can be used without needing to create a <tt>Triple</tt> first, and also allow <tt>null</tt> as a wildcard parameter:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(graph.contains(null, nameIri, bobName));
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</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">
+<div class="source">
+<pre>System.out.println(graph.size());
+</pre></div></div>
+
+<blockquote>
+<p><tt>2</tt></p>
+</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">
+<div class="source">
+<pre>for (Triple t : graph.iterate()) {
+  System.out.println(t.getObject());
+}
+</pre></div></div>
+
+<blockquote>
+<p><tt>&quot;Alice&quot;</tt></p>
+<p><tt>&quot;Bob&quot;</tt></p>
+</blockquote>
+<p>The expanded <a href="apidocs/org/apache/commons/rdf/api/Graph.html#iterate-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">iterate</a> method takes a <i>subject/predicate/object</i> filter which permits the <tt>null</tt> wildcard:</p>
+
+<div class="source">
+<div class="source">
+<pre>for (Triple t : graph.iterate(null, null, bobName)) {
+  System.out.println(t.getPredicate());
+}
+</pre></div></div>
+
+<blockquote>
+<p><tt>&lt;http://example.com/name&gt;</tt></p>
+</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#stream--">stream</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>
+<p>Some of the implementations (e.g. <a href="implementations.html#Closing_RDF4J_resources">RDF4J</a>) might require resources to be closed after the stream has been processed, so <tt>.stream()</tt> should be used within a <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">try-with-resources</a> block.</p>
+
+<div class="source">
+<div class="source">
+<pre>try (Stream&lt;? extends Triple&gt; triples = graph.stream()) {
+  Stream&lt;RDFTerm&gt; subjects = triples.map(t -&gt; t.getObject());
+  String s = subjects.map(RDFTerm::ntriplesString).collect(Collectors.joining(&quot; &quot;));
+  System.out.println(s);
+}
+</pre></div></div>
+
+<blockquote>
+<p><tt>&quot;Alice&quot; &quot;Bob&quot;</tt></p>
+</blockquote>
+<p>For details about what can be done with a stream, see the <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html">java.util.stream documentation</a>.</p>
+<p>Note that by default the stream will be parallel, use <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/stream/BaseStream.html#sequential--">.sequential()</a> if your stream operations need to interact with objects that are not thread-safe.</p>
+<p>Streams allow advanced <a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#filter-java.util.function.Predicate-">filter predicates</a>, but you may find that simple <i>subject/predicate/object</i> patterns are handled more efficiently by the implementation when using the expanded <a class="externalLink" href="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-">stream</a> method. These can of course be combined:</p>
+
+<div class="source">
+<div class="source">
+<pre>try (Stream&lt;? extends Triple&gt; named = graph.stream(null, nameIri, null)) {
+   Stream&lt;? extends Triple&gt; namedB = named.filter(
+       t -&gt; t.getObject().ntriplesString().contains(&quot;B&quot;));
+   System.out.println(namedB.map(t -&gt; t.getSubject()).findAny().get());
+ }
+</pre></div></div>
+
+<blockquote>
+<p><tt>&lt;http://example.com/bob&gt;</tt></p>
+</blockquote></div>
+<div class="section">
+<h3><a name="Removing_triples"></a>Removing triples</h3>
+<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>
+
+<div class="source">
+<div class="source">
+<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">
+<div class="source">
+<pre>graph.remove(null, nameIri, null);
+</pre></div></div>
+<p>To remove all triples, use <a href="apidocs/org/apache/commons/rdf/api/Graph.html#clear--">clear</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>graph.clear();
+System.out.println(graph.contains(null, null, null));
+</pre></div></div>
+
+<blockquote>
+<p><tt>false</tt></p>
+</blockquote></div></div>
+<div class="section">
+<h2><a name="Dataset"></a>Dataset</h2>
+<p>A <a class="externalLink" href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">dataset</a> is a collection of quads, or if you like, a collection of <tt>Graph</tt>s.</p>
+<p>To create a <a href="apidocs/org/apache/commons/rdf/api/Dataset.html">Dataset</a> instance from a <tt>RDF</tt> implementation, use <a href="apidocs/org/apache/commons/rdf/api/RDF.html#createDataset--">createDataset()</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Dataset dataset = rdf.createDataset();
+</pre></div></div>
+<p>Implementations will typically also have other ways of retrieving a <tt>Dataset</tt>, e.g. by parsing a JSON-LD file or connecting to a storage backend.</p>
+<div class="section">
+<h3><a name="Dataset_operations"></a>Dataset operations</h3>
+<p><tt>Dataset</tt> operations match their equivalent operations on <tt>Graph</tt>, except that methods like <a href="apidocs/org/apache/commons/rdf/api/Dataset.html#add-org.apache.commons.rdf.api.Quad-">add(q)</a> and <a href="apidocs/org/apache/commons/rdf/api/Dataset.html#remove-org.apache.commons.rdf.api.Quad-">remove(q)</a> use <a href="apidocs/org/apache/commons/rdf/api/Quad.html">Quad</a> instead of <tt>Triple</tt>.</p>
+
+<div class="source">
+<div class="source">
+<pre>dataset.add(quad);
+System.out.println(dataset.contains(quad));
+dataset.remove(quad);
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt></p>
+</blockquote>
+<p>The convenience method <a href="apidocs/org/apache/commons/rdf/api/Dataset.html#add-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">add(g,s,p,o)</a> take an additional <tt>BlankNodeOrIRI</tt> parameter for the graph name - matching <tt>RDF.createQuad(g,s,p,o)</tt>.</p>
+<p>Note that the expanded pattern methods like <a href="apidocs/org/apache/commons/rdf/api/Dataset.html#contains-java.util.Optional-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">contains(g,s,p,o)</a> and <a href="apidocs/org/apache/commons/rdf/api/Dataset.html#stream-java.util.Optional-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">stream(g,s,p,o)</a> uses <tt>null</tt> as a wildcard pattern, and therefore an explicit <i>graph name</i> parameter must be supplied as <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#empty--">Optional.empty()</a> (default graph) or wrapped using <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html#of-T-">Optional.of(g)</a>:</p>
+
+<div class="source">
+<div class="source">
+<pre>Literal foo = rdf.createLiteral(&quot;Foo&quot;);
+// Match Foo in any graph, any subject, any predicate
+if (dataset.contains(null, null, null, foo)) {
+  System.out.println(&quot;Foo literal found&quot;);
+}
+
+// Match Foo in default graph, any subject, any predicate
+if (dataset.contains(Optional.empty(), null, null, foo)) {
+  System.out.println(&quot;Foo literal found in default graph&quot;);
+}
+
+
+BlankNodeOrIRI g1 = rdf.createIRI(&quot;http://example.com/graph1&quot;);
+// Match Foo in named graph, any subject, any predicate
+if (dataset.contains(Optional.of(g1), null, null, foo)) {
+  System.out.println(&quot;Foo literal found in default graph&quot;);
+}
+</pre></div></div></div>
+<div class="section">
+<h3><a name="Graphs_in_the_dataset"></a>Graphs in the dataset</h3>
+<p>An <a class="externalLink" href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF Dataset</a> is defined as:</p>
+
+<blockquote>
+<p>An RDF dataset is a collection of RDF graphs, and comprises:</p>
+  
+<ul>
+    
+<li>Exactly one default graph, being an RDF graph. The default graph does not have a name and may be empty.</li>
+    
+<li>Zero or more named graphs. Each named graph is a pair consisting of an IRI or a blank node (the graph name), and an RDF graph. Graph names are unique within an RDF dataset.</li>
+  </ul>
+</blockquote>
+<p>It is possible to retrieve these graphs from a <tt>Dataset</tt> using:</p>
+
+<ul>
+  
+<li><a href="apidocs/org/apache/commons/rdf/api/Dataset.html#getGraph--">getGraph()</a> for the <i>default graph</i></li>
+  
+<li><a href="apidocs/org/apache/commons/rdf/api/Dataset.html#getGraph-org.apache.commons.rdf.api.BlankNodeOrIRI-">getGraph(blankNodeOrIRI)</a> for a named graph</li>
+</ul>
+
+<div class="source">
+<div class="source">
+<pre>Graph defaultGraph = dataset.getGraph();
+BlankNodeOrIRI graphName = rdf.createIRI(&quot;http://example.com/graph&quot;);
+Optional&lt;Graph&gt; otherGraph = dataset.getGraph(graphName);
+</pre></div></div>
+<p>These provide a <tt>Graph</tt> <b>view</b> of the corresponding <tt>Triple</tt>s in the <tt>Dataset</tt>:</p>
+
+<div class="source">
+<div class="source">
+<pre>System.out.println(defaultGraph.contains(otherQuad.asTriple()));
+System.out.println(defaultGraph.size());
+</pre></div></div>
+
+<blockquote>
+<p><tt>true</tt> <tt>1</tt></p>
+</blockquote>
+<p>It is unspecified if modifications to the returned Graph are reflected in the Dataset.</p>
+<p>Note that it is unspecified if requesting an unknown graph name will return <tt>Optional.empty()</tt> or create a new (empty) <tt>Graph</tt>.</p>
+<p>Some implementations may also support a <i>union graph</i>, a <tt>Graph</tt> that contains all triples regardless of their graph names. <i>simple</i> provides <a href="apidocs/org/apache/commons/rdf/simple/DatasetGraphView.html">DatasetGraphView</a> which can be used with any <tt>Dataset</tt> for this purpose.</p></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 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#stream-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-">stream</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">
+<div class="source">
+<pre>Graph graph;
+// ...
+synchronized(graph) {
+    graph.add(triple);
+}
+// ...
+synchronized(graph) {
+    for (Triple t : 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, 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>Commons RDF defines a <tt>RDF</tt> interface as a factory for using a particular implementations&#x2019; <tt>RDFTerm</tt>, <tt>Triple</tt>, <tt>Quad</tt>, <tt>Graph</tt> and <tt>Dataset</tt>. The <tt>RDF</tt> implementations also add adapter/converter methods to facilitate interoperability with their underlying framework&#x2019;s API.</p>
+<p>Note that some RDF frameworks have several possibilities for creating a backend for a <tt>Graph</tt> or <tt>Dataset</tt>, which configuration is implementation-specific.</p>
+<div class="section">
+<h3><a name="Cross-compatibility"></a>Cross-compatibility</h3>
+<p>While different frameworks have their own classes implementing the Commons RDF interfaces, Commons RDF objects are cross-compatible. Thus a client is able to mix and match objects from multiple implementations:</p>
+
+<div class="source">
+<div class="source">
+<pre>import org.apache.commons.rdf.rdf4j.RDF4J;
+import org.apache.commons.rdf.jena.JenaRDF;
+
+RDF rdf4j = new RDF4J();
+JenaRDF jena = new JenaRDF();
+
+JenaGraph jenaGraph = jena.createGraph();
+// Jena-specific load method
+jenaGraph.asJenaModel().read(&quot;dataset.ttl&quot;);
+
+
+// Another Graph, from a different implementation
+Graph rdf4jGraph = rdf4j.createGraph();  
+
+// Any RDF implementation can make RDFTerms
+IRI rdfIRI = rdf4j.createIRI(&quot;http://example.com/property1&quot;);
+// and used added to a different implementation's
+jenaGraph.add(rdfIRI,rdfIRI,rdfIRI);
+
+// Both Triple and RDFTerm instances can be used
+// with interoperability
+for (Triple t1: g1.stream(null, iri1, null)) {
+    if (g2.contains(t1.getSubject(), null, t1.getObject())) {
+      g2.remove(t1);
+    }
+}
+</pre></div></div>
+<p>It is however generally recommended to use the matching <tt>RDF</tt> implementation for operations on a <tt>Graph</tt> or <tt>Dataset</tt> as it avoids unnecessary conversion round-trips.</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.stream()</tt>. Special care should be taken if returned values needs to be casted to implementation specific types, e.g. using the appropriate adapter method from the desired <tt>RDF</tt> implementation.</i></p>
+<p>The <tt>.equals()</tt> methods of <tt>RDFTerm</tt>, <tt>Triple</tt> and <tt>Quad</tt> are explicitly defined, so their instances can be compared across implementations, and thus can safely be used for instance as keys in a <tt>java.util.Map</tt> or <tt>java.util.Set</tt>.</p>
+<p><i>Note: Special care might need to be taken for cross-interoperability of <tt>BlankNode</tt> instances. While multiple triples/quads with the same &#x201c;foreign&#x201d; <tt>BlankNode</tt> can be added without breaking their connections, the <tt>Graph</tt>/<tt>Quad</tt> is not required to <b>return</b> blank node instances that <tt>.equals()</tt> those previously inserted - specifically implementations are <b>not</b> expected to persist the blank node <a href="apidocs/org/apache/commons/rdf/api/BlankNode.html#uniqueReference--">uniqueReference</a>.</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/commons-rdf/blob/master/examples/src/example/UserGuideTest.java">UserGuideTest.java</a> within the <a class="externalLink" href="https://github.com/apache/commons-rdf/tree/master/examples">examples</a> folder of the Commons RDF <a href="source-repository.html">source code repository</a>.</p></div>
+          </td>
+        </tr>
+      </table>
+    </div>
+
+    <div class="footer">
+      <p>Copyright &copy;                    2015-2016
+                        <a href="https://www.apache.org/">The Apache Software Foundation</a>.
+            All Rights Reserved.</p>
+                                                                  <?xml version="1.0" encoding="UTF-8"?>
+<div class="center">Apache Commons, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
+      All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div>
+                              </div>
+  </body>
+
+</html>
\ No newline at end of file

Modified: websites/staging/commonsrdf/content/xref-test/index.html
==============================================================================
--- websites/staging/commonsrdf/content/xref-test/index.html (original)
+++ websites/staging/commonsrdf/content/xref-test/index.html Wed Nov 30 23:42:47 2016
@@ -4,7 +4,7 @@
 <!-- this is a JXR report set -->
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 	</head>
     <frameset cols="20%,80%">
 		<frameset rows="30%,70%">

Modified: websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-frame.html
==============================================================================
--- websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-frame.html (original)
+++ websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-frame.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-summary.html
==============================================================================
--- websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-summary.html (original)
+++ websites/staging/commonsrdf/content/xref-test/org/apache/commons/rdf/api/package-summary.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref-test/overview-frame.html
==============================================================================
--- websites/staging/commonsrdf/content/xref-test/overview-frame.html (original)
+++ websites/staging/commonsrdf/content/xref-test/overview-frame.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 		<link rel="stylesheet" type="text/css" href="stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref-test/overview-summary.html
==============================================================================
--- websites/staging/commonsrdf/content/xref-test/overview-summary.html (original)
+++ websites/staging/commonsrdf/content/xref-test/overview-summary.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 		<link rel="stylesheet" type="text/css" href="stylesheet.css" title="style" />
 	</head>
 	<body>
@@ -24,7 +24,7 @@
 	        </ul>
       	</div>
 		
-		      	<h2>Commons RDF API 0.4.0-SNAPSHOT Reference</h2>
+		      	<h2>Commons RDF 0.4.0-SNAPSHOT Reference</h2>
 
 		<table class="summary">
         	<thead>

Modified: websites/staging/commonsrdf/content/xref/index.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/index.html (original)
+++ websites/staging/commonsrdf/content/xref/index.html Wed Nov 30 23:42:47 2016
@@ -4,7 +4,7 @@
 <!-- this is a JXR report set -->
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 	</head>
     <frameset cols="20%,80%">
 		<frameset rows="30%,70%">

Modified: websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-frame.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-frame.html (original)
+++ websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-frame.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-summary.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-summary.html (original)
+++ websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/api/package-summary.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.api</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-frame.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-frame.html (original)
+++ websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-frame.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.experimental</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.experimental</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-summary.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-summary.html (original)
+++ websites/staging/commonsrdf/content/xref/org/apache/commons/rdf/experimental/package-summary.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.experimental</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference Package org.apache.commons.rdf.experimental</title>
 		<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref/overview-frame.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/overview-frame.html (original)
+++ websites/staging/commonsrdf/content/xref/overview-frame.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 		<link rel="stylesheet" type="text/css" href="stylesheet.css" title="style" />
 	</head>
 	<body>

Modified: websites/staging/commonsrdf/content/xref/overview-summary.html
==============================================================================
--- websites/staging/commonsrdf/content/xref/overview-summary.html (original)
+++ websites/staging/commonsrdf/content/xref/overview-summary.html Wed Nov 30 23:42:47 2016
@@ -3,7 +3,7 @@
 <html xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
-		<title>Commons RDF API 0.4.0-SNAPSHOT Reference</title>
+		<title>Commons RDF 0.4.0-SNAPSHOT Reference</title>
 		<link rel="stylesheet" type="text/css" href="stylesheet.css" title="style" />
 	</head>
 	<body>
@@ -24,7 +24,7 @@
 	        </ul>
       	</div>
 		
-		      	<h2>Commons RDF API 0.4.0-SNAPSHOT Reference</h2>
+		      	<h2>Commons RDF 0.4.0-SNAPSHOT Reference</h2>
 
 		<table class="summary">
         	<thead>



Mime
View raw message