You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2011/08/31 01:30:03 UTC
svn commit: r795037 -
/websites/staging/jena/trunk/content/jena/documentation/ontology/index.html
Author: buildbot
Date: Tue Aug 30 23:30:03 2011
New Revision: 795037
Log:
Staging update by buildbot
Modified:
websites/staging/jena/trunk/content/jena/documentation/ontology/index.html
Modified: websites/staging/jena/trunk/content/jena/documentation/ontology/index.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/ontology/index.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/ontology/index.html Tue Aug 30 23:30:03 2011
@@ -942,38 +942,30 @@ selective, and ignore only certain URI's
documents. To selectively skip certain named imports, call the
method <code>addIgnoreImport( String uri )</code> on the document manager
object, or set the <code>ignoreImport</code> property in the policy.</p>
-<blockquote>
-<blockquote>
-<blockquote>
-<blockquote>
-<p>TODO watermark >>>>>>>>>>></p>
-</blockquote>
-</blockquote>
-</blockquote>
-</blockquote>
<h3 id="managing_file_references">Managing file references</h3>
<p>An advantage of working with ontologies is that we can reuse work
done by other ontologists, by importing their published ontologies
-into our own. Sometimes, however, this means that there is an
-Internet firewall between the ontology-based application and the
-source of an imported ontology. Even if it's possible to traverse
-the firewall through an HTTP proxy, retrieving files from an HTTP
-connection may impose unacceptable delays when starting an
-application. In the worst case, we may find that ontology on which
-our application depends is temporarily or permanently unavailable
-from the original published URL. To alleviate these commonly
-experienced problems, you can use the ontology document manager to
-set up a a local indirection, so that an attempt to import a
+into our own. The <code>OntModel</code> can load such referenced ontologies
+automatically from their published URL's. This can mean that an
+application suffers a delay on startup. Worse, it may require extra
+work to cope with intervening firewalls or web proxies. Worse still,
+connectivity may be intermittent: we do not want our application to
+fail just because it temporarily does not have Internet access, or
+because a previously published ontology has been moved.
+To alleviate these commonly
+experienced problems, we can use Jena's
+<a href="/jena/documentation/javadoc/com/hp/hpl/jena/util/FileManager.html"><code>FileManager</code></a> to
+manage local indirections, so that an attempt to import a
document from a given published URL means that a local copy of the
-document is retrieved instead. This may be a file copy, or simply a
+document is loaded instead. This may be a file on the local disk, or simply a
pointer to a local mirror web site.</p>
-<p>To specify this local redirection in the policy file, use the
-following declarations:</p>
+<p>While the <code>FileManager</code> can be configure directly, we can also specify redirections
+declaratively in the document manager policy file:</p>
<div class="codehilite"><pre><span class="nt"><OntologySpec></span>
- <span class="nt"><publicURI</span> <span class="na">rdf:resource=</span><span class="s">"Â
the public URI to map fromÂ
"</span> <span class="nt">/></span>
- <span class="nt"><altURL</span> <span class="na">rdf:resource=</span><span class="s">"Â
the local URL to map to Â
"</span> <span class="nt">/></span>
+ <span class="nt"><publicURI</span> <span class="na">rdf:resource=</span><span class="s">"... the public URI to map from..."</span> <span class="nt">/></span>
+ <span class="nt"><altURL</span> <span class="na">rdf:resource=</span><span class="s">"... the local URL to map to ..."</span> <span class="nt">/></span>
<span class="c"><!-- optional ontology language term --></span>
- <span class="nt"><language</span> <span class="na">rdf:resource=</span><span class="s">"Â
encoding used Â
"</span> <span class="nt">/></span>
+ <span class="nt"><language</span> <span class="na">rdf:resource=</span><span class="s">"... encoding used ..."</span> <span class="nt">/></span>
<span class="c"><!-- optional prefix to associate with the public URL --></span>
<span class="nt"><prefix</span> <span class="na">rdf:datatype=</span><span class="s">"&xsd;string"</span><span class="nt">></span>a prefix<span class="nt"></prefix></span>
<span class="nt"></OntologySpec></span>
@@ -984,50 +976,46 @@ following declarations:</p>
<div class="codehilite"><pre><span class="nt"><OntologySpec></span>
<span class="c"><!-- local version of the RDFS vocabulary --></span>
<span class="nt"><publicURI</span> <span class="na">rdf:resource=</span><span class="s">"http://www.w3.org/2000/01/rdf-schema"</span> <span class="nt">/></span>
- <span class="nt"><altURL</span> <span class="na">rdf:resource=</span><span class="s">"file:vocabularies/rdf-schema.rdf"</span> <span class="nt">/></span>
+ <span class="nt"><altURL</span> <span class="na">rdf:resource=</span><span class="s">"file:src/main/resources/rdf-schema.rdf"</span> <span class="nt">/></span>
<span class="nt"></OntologySpec></span>
</pre></div>
<p>This specifies that an attempt to load the RDFS vocabulary from
<code>http://www.w3.org/2000/01/rdf-schema</code> will transparently cause
-<code>file:vocabularies/rdf-schema.rdf</code> to be fetched instead. You can
+<code>file:src/main/resources/rdf-schema.rdf</code> to be fetched instead. You can
specify any number of such re-directions in the policy file, or you
can add them to the document manager object directly by calling the
various setter methods (see the Javadoc for details). As a
side-effect, this mechanism also means that ontologies may be named
-with any legal URI (not necessarily resolvable) - so long as the
+with any legal URI (not necessarily resolvable) – so long as the
<code>altURL</code> is itself resolvable.</p>
-<p>Note that the <code>OntDocumentManager</code> is an application of Jena's
-<a href="../how-to/filemanager.html">File Manager</a>. See the notes on
-FileManager for details of additional options.</p>
-<p>In the following example, I programmatically declare that the ESWC
-ontology is replicated locally on disk, and then I load it using
-the public URL. Assume that the constant <code>JENA</code> has been
+<p>See the notes on
+<a href="/jena/tools/filemanager.html"><code>FileManager</code></a> for details of additional options.</p>
+<p>In the following example, we use the <code>DocumentManager</code> API to declare that the ESWC
+ontology is replicated locally on disk. We then load it using
+the normal URL. Assume that the constant <code>JENA</code> has been
initialised to the directory in which Jena was installed.</p>
<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createOntologyModel</span><span class="p">();</span>
- <span class="n">OntDocumentManager</span> <span class="n">dm</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getDocumentManager</span><span class="p">();</span>
- <span class="n">dm</span><span class="o">.</span><span class="n">addAltEntry</span><span class="p">(</span> <span class="s">"http://www.eswc2006.org/technologies/ontology"</span><span class="p">,</span>
- <span class="s">"file:"</span> <span class="o">+</span> <span class="n">JENA</span> <span class="o">+</span> <span class="s">"src-examples/data/eswc-2006-09-21.rdf"</span> <span class="p">);</span>
- <span class="n">m</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span> <span class="s">"http://www.eswc2006.org/technologies/ontology"</span> <span class="p">);</span>
+<span class="n">OntDocumentManager</span> <span class="n">dm</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getDocumentManager</span><span class="p">();</span>
+<span class="n">dm</span><span class="o">.</span><span class="n">addAltEntry</span><span class="p">(</span> <span class="s">"http://www.eswc2006.org/technologies/ontology"</span><span class="p">,</span>
+ <span class="s">"file:"</span> <span class="o">+</span> <span class="n">JENA</span> <span class="o">+</span> <span class="s">"src/examples/resources/eswc-2006-09-21.rdf"</span> <span class="p">);</span>
+<span class="n">m</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span> <span class="s">"http://www.eswc2006.org/technologies/ontology"</span> <span class="p">);</span>
</pre></div>
<h3 id="specifying_prefixes">Specifying prefixes</h3>
-<p>A model keeps a table of URI prefixes that can be used to render
-URI's in the shortened prefix:name form, which is useful in
+<p>A model keeps a table of URI prefixes which can be used to present
+URI's in the shortened <code>prefix:name</code> form. This is useful in
displaying URI's in a readable way in user interfaces, and is
essential in producing legal XML names that denote arbitrary URI's.
The ontology model's table of prefixes can be initialized from a
table kept by the document manager, which contains the standard
prefixes plus any that are declared by in the policy file (or added
-to subsequently by method calls). To prevent the model's prefix
-table from being initialized in this way, use the property
-<code>useDeclaredNsPrefixes</code> in the policy file (with value <code>false</code>), or
-call the method <code>setUseDeclaredPrefixes</code> on the ontology object.</p>
+to subsequently by method calls).</p>
<h3 id="caching_of_imported_models">Caching of imported models</h3>
<p>You can use the document manager to assist with loading ontology
-documents through its cache. Suppose two ontologies, A and B both
+documents through its cache. Suppose two ontologies, A and B, both
import ontology C. We would like not to have to read C twice when
loading A and then B. The document manager supports this use case
by optionally caching C's model, indexed by URI. When A tries to
@@ -1058,48 +1046,81 @@ will also accept an <code>OntResource</c
ontology value.</p>
<p>Some of the common attributes of ontology resources that are
expressed through methods on OntResource are shown below:</p>
-<p>Attribute
-Meaning
-versionInfo
-A string documenting the version or history of this resource
-comment
-A general comment associated with this value
-label
-A human-readable label
-seeAlso
-Another web location to consult for more information about this
-resource
-isDefinedBy
-A specialisation of seeAlso that is intended to supply a definition
-of this resource
-sameAs
-Denotes another resource that this resource is equivalent to
-differentFrom
-Denotes another resource that is distinct from this resource (by
-definition)
-For each of these properties, there is a standard pattern of
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>versionInfo</td>
+<td>A string documenting the version or history of this resource</td>
+</tr>
+<tr>
+<td>comment</td>
+<td>A general comment associated with this value</td>
+</tr>
+<tr>
+<td>label</td>
+<td>A human-readable label</td>
+</tr>
+<tr>
+<td>seeAlso</td>
+<td>Another web location to consult for more information about this resource</td>
+</tr>
+<tr>
+<td>isDefinedBy</td>
+<td>A specialisation of seeAlso that is intended to supply a definition of this resource</td>
+</tr>
+<tr>
+<td>sameAs</td>
+<td>Denotes another resource that this resource is equivalent to</td>
+</tr>
+<tr>
+<td>differentFrom</td>
+<td>Denotes another resource that is distinct from this resource (by definition)</td>
+</tr>
+</tbody>
+</table>
+<p>For each of these properties, there is a standard pattern of
available methods:</p>
-<p>Method
-Effect
-add<property>
-Add an additional value for the given property
-set<property>
-Remove any existing values for the property, then add the given
-value
-list<property>
-Return an iterator ranging over the values of the property
-get<property>
-Return the value for the given property, if the resource has one.
-If not, return null. If it has more than one value, an arbitrary
-selection is made.
-has<property>
-Return true if there is at least one value for the given property.
-Depending on the name of the property, this is sometimes
-is<property>
-remove<property>
-Removes a given value from the values of the property on this
-resource. Has no effect if the resource does not have that value.
-For example: <code>addSameAs( Resource r )</code>, or
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>add<property></td>
+<td>Add an additional value for the given property</td>
+</tr>
+<tr>
+<td>set<property></td>
+<td>Remove any existing values for the property, then add the given value</td>
+</tr>
+<tr>
+<td>list<property></td>
+<td>Return an iterator ranging over the values of the property</td>
+</tr>
+<tr>
+<td>get<property></td>
+<td>Return the value for the given property, if the resource has one. If not, return null. If it has more than one value, an arbitrary selection is made.</td>
+</tr>
+<tr>
+<td>has<property></td>
+<td>Return true if there is at least one value for the given property. Depending on the name of the property, this is sometimes is<property></td>
+</tr>
+<tr>
+<td>remove<property></td>
+<td>Removes a given value from the values of the property on this resource. Has no effect if the resource does not have that value.</td>
+</tr>
+</tbody>
+</table>
+<p>For example: <code>addSameAs( Resource r )</code>, or
<code>isSameAs( Resource r )</code>. For full details of the individual
methods, please consult the Javadoc.</p>
<p><code>OntResource</code> defines some other general utility methods. For
@@ -1108,26 +1129,26 @@ property, you can call <code>getCardinal
the resource from the ontology altogether, you can call <code>remove()</code>.
The effect of this is to remove every statement that mentions this
resource as a subject or object of a statement.</p>
-<p>To get or set the value of a given property, use
-<code>getPropertyValue( Property p )</code> or
+<p>To get the value of a given property, use
+<code>getPropertyValue( Property p )</code>. To set it,
<code>setPropertyValue( Property p, RDFNode value )</code>. Continuing the
naming pattern, the values of a named property can be listed (with
<code>listPropertyValues</code>), removed (with <code>removeProperty</code>) or added
(with <code>addProperty</code>).</p>
<p>Finally, <code>OntResource</code> provides methods for listing, getting and
setting the <code>rdf:type</code> of a resource, which denotes a class to
-which the resource belongs (remember that in RDF and OWL, a
+which the resource belongs (noting that, in RDF and OWL, a
resource can belong to many classes at once). The <code>rdf:type</code>
property is one for which many entailment rules are defined in the
semantic models of the various ontology languages. Therefore, the
values that <code>listRDFTypes()</code> returns is more than usually dependent
-on the actual reasoner bound to the ontology model. For example,
-suppose I have class A, class B which is a subclass of A, and
-resource x whose asserted <code>rdf:type</code> is B. With no reasoner,
-listing x's RDF types will return only B. If the reasoner is able
+on the reasoner bound to the ontology model. For example,
+suppose we have class <code>A</code>, class <code>B</code> which is a subclass of <code>A</code>, and
+resource <code>x</code> whose asserted <code>rdf:type</code> is <code>B</code>. With no reasoner,
+listing <code>x</code>'s RDF types will return only <code>B</code>. If the reasoner is able
to calculate the closure of the subclass hierarchy (and most can),
-X's RDF types would also include A. A complete OWL reasoner would
-also infer that x has <code>rdf:type</code> <code>owl:Thing</code> and <code>rdf:Resource</code>.</p>
+<code>x</code>'s RDF types would also include <code>A</code>. A complete OWL reasoner would
+also infer that <code>x</code> has <code>rdf:type</code> <code>owl:Thing</code> and <code>rdf:Resource</code>.</p>
<p>For some tasks, getting a complete list of the RDF types of a
resource is exactly what is needed. For other tasks, this is not
the case. If you are developing an ontology editor, for example,
@@ -1152,13 +1173,13 @@ example:</p>
<span class="n">Individual</span> <span class="n">p1</span> <span class="o">=</span> <span class="n">base</span><span class="o">.</span><span class="n">createIndividual</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"paper1"</span><span class="p">,</span> <span class="n">paper</span> <span class="p">);</span>
<span class="sr">//</span> <span class="n">list</span> <span class="n">the</span> <span class="n">asserted</span> <span class="n">types</span>
-<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">p1</span><span class="o">.</span><span class="n">listRDFTypes</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span><span class="sr"><Resource></span> <span class="n">i</span> <span class="o">=</span> <span class="n">p1</span><span class="o">.</span><span class="n">listRDFTypes</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
<span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span> <span class="n">p1</span><span class="o">.</span><span class="n">getURI</span><span class="p">()</span> <span class="o">+</span> <span class="s">" is asserted in class "</span> <span class="o">+</span> <span class="n">i</span><span class="o">.</span><span class="k">next</span><span class="p">()</span> <span class="p">);</span>
<span class="p">}</span>
<span class="sr">//</span> <span class="n">list</span> <span class="n">the</span> <span class="n">inferred</span> <span class="n">types</span>
<span class="n">p1</span> <span class="o">=</span> <span class="n">inf</span><span class="o">.</span><span class="n">getIndividual</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"paper1"</span> <span class="p">);</span>
-<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">p1</span><span class="o">.</span><span class="n">listRDFTypes</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span><span class="sr"><Resource></span> <span class="n">i</span> <span class="o">=</span> <span class="n">p1</span><span class="o">.</span><span class="n">listRDFTypes</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
<span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span> <span class="n">p1</span><span class="o">.</span><span class="n">getURI</span><span class="p">()</span> <span class="o">+</span> <span class="s">" is inferred to be in class "</span> <span class="o">+</span> <span class="n">i</span><span class="o">.</span><span class="k">next</span><span class="p">()</span> <span class="p">);</span>
<span class="p">}</span>
</pre></div>
@@ -1168,18 +1189,18 @@ example:</p>
something between the complete list of types and the base list of
only the asserted values. Consider the class hierarchy in figure 5
(i):</p>
-<p><img alt="Diagram showing direct relationships" src="../images/Direct-hierarchy.png" /></p>
-<p>Figure 5: asserted and inferred relationships</p>
+<p><img alt="Diagram showing direct relationships" src="./direct-hierarchy.png" title="asserted and direct relationships" />
+Figure 5: asserted and inferred relationships</p>
<p>Figure 5 (i) shows a base model, containing a class hierarchy and
-an instance x. Figure 5 (ii) shows the full set of relationships
+an instance <code>x</code>. Figure 5 (ii) shows the full set of relationships
that might be inferred from this base model. In Figure 5 (iii), we
see only the <em>direct</em> or maximally specific relationships. For
-example, in 5 (iii) x does not have <code>rdf:type A</code>, since this is an
-relationship that is covered by the facts that x has <code>rdf:type D</code>,
-and D is a subclass of A. Notice also that the <code>rdf:type B</code> link is
+example, in 5 (iii) <code>x</code> does not have <code>rdf:type A</code>, since this is an
+relationship that is covered by the fact that <code>x</code> has <code>rdf:type D</code>,
+and <code>D</code> is a subclass of <code>A</code>. Notice also that the <code>rdf:type B</code> link is
also removed from the direct graph, for a similar reason. Thus the
direct graph hides relationships from both the inferred and
-asserted graphs. When displaying instance x in a GUI, particularly
+asserted graphs. When displaying instance <code>x</code> in a user interface, particularly
in a tree view of some kind, the direct graph is often the most
useful as it contains the useful information in the most compact
form.</p>
@@ -1195,14 +1216,15 @@ returned.</p>
<p>Classes are the basic building blocks of an ontology. A simple
class is represented in Jena by an
<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/OntClass.html">OntClass</a>
-object. As I <a href="#rdfPolymorphism">mentioned above</a>, an ontology class
+object. As <a href="#rdfPolymorphism">mentioned above</a>, an ontology class
is a facet of an RDF resource. One way, therefore, to get an
-ontology class is to convert an RDF resource. Assume that <code>m</code> is a
-suitable defined <code>OntModel</code>, into which the ESWC ontology has
+ontology class is to convert a plain RDF resource into
+its class facet. Assume that <code>m</code> is a
+suitably defined <code>OntModel</code>, into which the ESWC ontology has
already been read, and that <code>NS</code> is a variable denoting the
ontology namespace:</p>
<div class="codehilite"><pre><span class="n">Resource</span> <span class="n">r</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getResource</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"Paper"</span> <span class="p">);</span>
-<span class="n">OntClass</span> <span class="n">paper</span> <span class="o">=</span> <span class="p">(</span><span class="n">OntClass</span><span class="p">)</span> <span class="n">r</span><span class="o">.</span><span class="n">as</span><span class="p">(</span> <span class="n">OntClass</span><span class="o">.</span><span class="n">class</span> <span class="p">);</span>
+<span class="n">OntClass</span> <span class="n">paper</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">as</span><span class="p">(</span> <span class="n">OntClass</span><span class="o">.</span><span class="n">class</span> <span class="p">);</span>
</pre></div>
@@ -1233,29 +1255,40 @@ They are less useful in RDFS.</p>
<p>Once you have the ontology class object, you can begin processing
it through the methods defined on <code>OntClass</code>. The attributes of a
class are handled in a similar way to the attributes of
-OntResource, above, with a collection of methods to set, add, get,
+<code>OntResource</code>, above, with a collection of methods to set, add, get,
test, list and remove values. Properties of classes that are
handled in this way are:</p>
-<p>Attribute
-Meaning
-subClass
-A subclass of this class, i.e. those classes that are declared
-<code>subClassOf</code> this class.
-superClass
-A super-class of this class, i.e. a class that this class is a
-<code>subClassOf</code>.
-equivalentClass
-A class that represents the same concept as this class. This is not
-just having the same class extension: the class 'British Prime
-Minister in 2003' contains the same individual as the class 'the
-husband of Cherie Blair', but they represent different concepts.
-disjointWith
-Denotes a class with which this class has no instances in common.
-Thus, in our example ontology, we can print a list the subclasses
-of an Artefact as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>subClass</td>
+<td>A subclass of this class, i.e. those classes that are declared <code>subClassOf</code> this class.</td>
+</tr>
+<tr>
+<td>superClass</td>
+<td>A super-class of this class, i.e. a class that this class is a <code>subClassOf</code>.</td>
+</tr>
+<tr>
+<td>equivalentClass</td>
+<td>A class that represents the same concept as this class. This is not just having the same class extension: the class 'British Prime Minister in 2003' contains the same individual as the class 'the husband of Cherie Blair', but they represent different concepts.</td>
+</tr>
+<tr>
+<td>disjointWith</td>
+<td>Denotes a class with which this class has no instances in common.</td>
+</tr>
+</tbody>
+</table>
+<p>Thus, in our example ontology, we can print a list the subclasses
+of an <code>Artefact</code> as follows:</p>
<div class="codehilite"><pre><span class="n">OntClass</span> <span class="n">artefact</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getOntClass</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"Artefact"</span> <span class="p">);</span>
-<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">artefact</span><span class="o">.</span><span class="n">listSubClasses</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
- <span class="n">OntClass</span> <span class="n">c</span> <span class="o">=</span> <span class="p">(</span><span class="n">OntClass</span><span class="p">)</span> <span class="n">i</span><span class="o">.</span><span class="k">next</span><span class="p">();</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">Iterator</span><span class="sr"><OntClass></span> <span class="n">i</span> <span class="o">=</span> <span class="n">artefact</span><span class="o">.</span><span class="n">listSubClasses</span><span class="p">();</span> <span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">();</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="n">OntClass</span> <span class="n">c</span> <span class="o">=</span> <span class="n">i</span><span class="o">.</span><span class="k">next</span><span class="p">();</span>
<span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span> <span class="n">c</span><span class="o">.</span><span class="n">getURI</span><span class="p">()</span> <span class="p">);</span>
<span class="p">}</span>
</pre></div>
@@ -1263,41 +1296,39 @@ of an Artefact as follows:</p>
<p>Note that, under RDFS and OWL semantics, each class is a sub-class
of itself (in other words, <code>rdfs:subClassOf</code> is reflexive). While
-this is true, under the semantics, Jena users have reported finding
-it unhelpful. Therefore, the <code>listSubClasses</code> and
-<code>listSuperClasses</code> methods remove the reflexive from the list of
+this is true in the semantics, Jena users have reported finding
+it inconvenient. Therefore, the <code>listSubClasses</code> and
+<code>listSuperClasses</code> convenience methods remove the reflexive from the list of
results returned by the iterator. However, if you use the plain
<code>Model</code> API to query for <code>rdfs:subClassOf</code> triples, assuming that a
-reasoner is in use, the reflexive triple will appear in the
-deductions model.</p>
+reasoner is in use, the reflexive triple will appear among the deduced
+triples.</p>
<p>Given an <code>OntClass</code> object, you can create or remove members of the
class extension – individuals that are instances of the class –
using the following methods:</p>
-<p>Method
-Meaning
-listInstances()
-listInstances( boolean direct )
-Returns an iterator over those instances that include this class
-among their <code>rdf:type</code> values. The <code>direct</code> flag can be used to
-select individuals that are direct members of the class, rather
-than indirectly through the class hierarchy. Thus if <code>p1</code> has
-<code>rdf:type :Paper</code>, it will appear in the iterator returned by
-<code>listInstances</code> on <code>:Artefact</code>, but not in the iterator returned by
-<code>listInstances(false)</code> on <code>:Artefact</code>.
-createIndividual()
-createIndividual( String uri )
-Adds a resource to the model, whose asserted <code>rdf:type</code> is this
-ontology class. If no URI is given, the individual is an anonymous
-resource.
-dropIndividual( Resource individual )
-Removes the association between the given individual and this
-ontology class. Effectively, this removes the <code>rdf:type</code> link
-between this class and the resource. Note that this is not the same
-as removing the individual altogether, unless the only thing that
-is known about the resource is that it is a member of the class. To
-delete an <code>OntResource</code>, including classes and individuals, use the
-<code>remove()</code> method.
-To test whether a class is a root of the class hierarchy in this
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>listInstances()<br />listInstances(boolean direct)</td>
+<td>Returns an iterator over those instances that include this class among their <code>rdf:type</code> values. The <code>direct</code> flag can be used to select individuals that are direct members of the class, rather than indirectly through the class hierarchy. Thus if <code>p1</code> has <code>rdf:type :Paper</code>, it will appear in the iterator returned by <code>listInstances</code> on <code>:Artefact</code>, but not in the iterator returned by <code>listInstances(false)</code> on <code>:Artefact</code>.</td>
+</tr>
+<tr>
+<td>createIndividual()<br />createIndividual(String uri)</td>
+<td>Adds a resource to the model, whose asserted <code>rdf:type</code> is this ontology class. If no URI is given, the individual is an anonymous resource.</td>
+</tr>
+<tr>
+<td>dropIndividual(Resource individual)</td>
+<td>Removes the association between the given individual and this ontology class. Effectively, this removes the <code>rdf:type</code> link between this class and the resource. Note that this is not the same as removing the individual altogether, unless the only thing that is known about the resource is that it is a member of the class. To delete an <code>OntResource</code>, including classes and individuals, use the <code>remove()</code> method.</td>
+</tr>
+</tbody>
+</table>
+<p>To test whether a class is a root of the class hierarchy in this
model (i.e. it has no known super-classes), call
<code>isHierarchyRoot()</code>.</p>
<p>The domain of a property is intended to allow entailments about the
@@ -1312,12 +1343,12 @@ this class among their domain classes. T
<code>listDeclaredProperties()</code> attempts to identify the properties that
are intended to apply to instances of this class. Using
<code>listDeclaredProperties</code> is explained in detail in the
-<a href="../how-to/rdf-frames.html">RDF frames how-to</a>.</p>
+<a href="../how-to/rdf-frames.html TODO">RDF frames how-to</a>.</p>
<h2 id="ontology_properties">Ontology properties</h2>
<p>In an ontology, a <em>property</em> denotes the name of a relationship
between resources, or between a resource and a data value. It
corresponds to a predicate in logic representations. One
-interesting aspect of languages like RDFS and OWL is that
+interesting aspect of RDFS and OWL is that
properties are not defined as aspects of some enclosing class, but
are first-class objects in their own right. This means that
ontologies and ontology-applications can store, retrieve and make
@@ -1334,33 +1365,16 @@ super-class for representing ontology pr
Again, using the pattern of add, set, get, list, has, and remove
methods, we can access the following attributes of an
<code>OntProperty</code>:</p>
-<p>Attribute
-Meaning
-subProperty
-A sub property of this property; i.e. a property which is declared
-to be a <code>subPropertyOf</code> this property. If p is a sub property of q,
-and we know that <code>A p B</code> is true, we can infer that <code>A q B</code> is also
-true.
-superProperty
-A super property of this property, i.e. a property that this
-property is a <code>subPropertyOf</code>
-domain
-Denotes the class or classes that form the domain of this property.
-Multiple domain values are interpreted as a conjunction. The domain
-denotes the class of value the property maps from.
-range
-Denotes the class or classes that form the range of this property.
-Multiple range values are interpreted as a conjunction. The range
-denotes the class of values the property maps to.
-equivalentProperty
-Denotes a property that is the same as this property.
-inverse
-Denotes a property that is the inverse of this property. Thus if q
-is the inverse of p, and we know that <code>A q B</code>, then we can infer
-that <code>B p A</code>.
-In the example ontology, the property <code>hasProgramme</code> has a domain
-of <code>OrganizedEvent</code>, a range of <code>Programme</code> and the human-readable
-label "has programme". I can reconstruct this definition in an
+<p>Attribute | Meaning
+subProperty | A sub property of this property; i.e. a property which is declared to be a <code>subPropertyOf</code> this property. If p is a sub property of q, and we know that <code>A p B</code> is true, we can infer that <code>A q B</code> is also true.
+superProperty | A super property of this property, i.e. a property that this property is a <code>subPropertyOf</code>
+domain | Denotes the class or classes that form the domain of this property. Multiple domain values are interpreted as a conjunction. The domain denotes the class of value the property maps from.
+range | Denotes the class or classes that form the range of this property. Multiple range values are interpreted as a conjunction. The range denotes the class of values the property maps to.
+equivalentProperty | Denotes a property that is the same as this property.
+inverse | Denotes a property that is the inverse of this property. Thus if q is the inverse of p, and we know that <code>A q B</code>, then we can infer that <code>B p A</code>.</p>
+<p>In the example ontology, the property <code>hasProgramme</code> has a domain
+of <code>OrganizedEvent</code>, a range of <code>Programme</code> and the human-readable label "has programme".
+We can reconstruct this definition in an
empty ontology model as follows:</p>
<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createOntologyModel</span><span class="p">(</span> <span class="n">OntModelSpec</span><span class="o">.</span><span class="n">OWL_MEM</span> <span class="p">);</span>
<span class="n">OntClass</span> <span class="n">programme</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">createClass</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"Programme"</span> <span class="p">);</span>
@@ -1374,10 +1388,10 @@ empty ontology model as follows:</p>
</pre></div>
-<p>As a further example, I can alternatively add information to an
-existing ontology. Let's add a super-property <code>hasDeadline</code> to
+<p>As a further example, we can alternatively add information to an
+existing ontology. To add a super-property <code>hasDeadline</code>, to
generalise the separate properties denoting the submission
-deadline, notification deadline and camera-ready deadline:</p>
+deadline, notification deadline and camera-ready deadline, do:</p>
<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createOntologyModel</span><span class="p">(</span> <span class="n">OntModelSpec</span><span class="o">.</span><span class="n">OWL_MEM</span> <span class="p">);</span>
<span class="n">m</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span> <span class="s">"http://www.eswc2006.org/technologies/ontology"</span> <span class="p">);</span>
@@ -1395,14 +1409,14 @@ deadline, notification deadline and came
</pre></div>
-<p>Note that, although I called the <code>addSubProperty</code> method on the
+<p>Note that, although we called the <code>addSubProperty</code> method on the
object representing the new super-property, the serialized form of
the ontology will contain <code>rdfs:subPropertyOf</code> axioms on each of
the sub-property resources, since this is what the language
defines. Jena will, in general, try to allow symmetric access to
sub-properties and sub-classes from either direction.</p>
<h3 id="object_and_datatype_properties">Object and Datatype properties</h3>
-<p>OWL and DAML+OIL refine the basic property type from RDF into two
+<p>OWL refines the basic property type from RDF into two
sub-types: <em>object properties</em> and <em>datatype properties</em> (for more
details see
[<a href="http://www.w3.org/TR/owl-ref/#Property">OWL Reference</a>]). The
@@ -1430,16 +1444,16 @@ property in a model, it will have the ef
<p>OWL permits object and datatype properties to be <em>functional</em> –
that is, for a given individual in the domain, the range value will
always be the same. In particular, if <code>father</code> is a functional
-property, and individual <code>:bryn</code> has <code>father :ijd</code> and
-<code>father :ian</code>, a reasoner is entitled to conclude that <code>:ijd</code> and
-<code>:ian</code> denote the same individual. A functional property is
+property, and individual <code>:jane</code> has <code>father :jim</code> and
+<code>father :james</code>, a reasoner is entitled to conclude that <code>:jim</code> and
+<code>:james</code> denote the same individual. A functional property is
equivalent to stating that the property has a maximum cardinality
of one.</p>
<p>Being a functional property is represented through the
<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/FunctionalProperty.html"><code>FunctionalProperty</code></a>
facet of an ontology property object. If a property is declared
functional (test using the <code>isFunctional()</code> method), then the
-method <code>asFunctionalProperty()</code> conveniently returns the functional
+method <code>asFunctionalProperty()</code> conveniently returns the functional property
facet. A non-functional property can be made functional through the
<code>convertToFunctionalProperty()</code> method. When you are creating a
property object, you also have the option of passing a Boolean
@@ -1447,16 +1461,14 @@ parameter to the <code>createObjectPrope
<h3 id="other_property_types">Other property types</h3>
<p>There are several additional sub-types of ObjectProperty that
represent additional capabilities of ontology properties. A
-[<code>TransitiveProperty</code>[(/jena/documentation/javadoc/com/hp/hpl/jena/ontology/TransitiveProperty.html)
+<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/TransitiveProperty.html"><code>TransitiveProperty</code></a>
means that if p is transitive, and we know <code>:a p :b</code> and also
<code>b p :c</code>, we can infer that <code>:a p :c</code>. A
<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/SymmetricProperty.html"><code>SymmetricProperty</code></a>
means that if p is symmetric, and we know <code>:a p :b</code>, we can infer
<code>:b p :a</code>. An
<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/InverseFunctionalProperty.html"><code>InverseFunctionalProperty</code></a>
-means that for any given range element, the domain value is unique.
-(Note that in DAML+OIL, the terminology for inverse functional
-property is <em>unambiguous property</em>).</p>
+means that for any given range element, the domain value is unique.</p>
<p>Given that all properties are <code>RDFNode</code> objects, and therefore
support the <code>as()</code> method, you can use <code>as()</code> to change from an
object property facet to a transitive property facet. To make this
@@ -1473,7 +1485,7 @@ view:</p>
<p>These methods all assume that the underlying model will support
this change in perspective. If not, the operation will fail with a
<code>ConversionException</code>. For example, if a given property <code>p</code> is not
-already a transitive property, then invoking
+asserted to be a transitive property in the underlying RDF model, then invoking
<code>p.asTransitiveProperty()</code> will throw a conversion exception. The
following methods will, if necessary, add additional information
(i.e. the additional <code>rdf:type</code> statement) to allow the conversion
@@ -1485,9 +1497,50 @@ to an alternative facet to succeed.</p>
</pre></div>
-<p>Finally, methods beginning <code>is</code> (e.g. <code>isTransitiveProperty</code>)
+<p>Sometimes it is convenient not to check whether the <code>.as()</code> conversion
+is warranted by the underlying data. This may be the case, for example,
+if the developer knows that the conversions are correct given the information from
+an external ontology which is not currently loaded. To allow <code>.as()</code> to always
+succeed, set the attribute <code>strictMode</code> to <code>false</code> on the <code>OntModel</code>
+object: <code>myOntModel.setStrictMode( false )</code>.</p>
+<p>Finally, methods beginning <code>is...</code> (e.g. <code>isTransitiveProperty</code>)
allow you to test whether a given property would support a given
sub-type facet.</p>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>TODO watermark</p>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
+</blockquote>
<h2 id="more_complex_class_expressions">More complex class expressions</h2>
<p>I introduced the handling of basic, named classes above. These are
the only kind of class descriptions available in RDFS. In OWL,
@@ -1576,15 +1629,15 @@ restrictions that mention that property:
<span class="n">Iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">listReferringRestrictions</span><span class="p">();</span>
<span class="k">while</span> <span class="p">(</span><span class="n">i</span><span class="o">.</span><span class="n">hasNext</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Restriction</span> <span class="n">r</span> <span class="o">=</span> <span class="p">(</span><span class="n">Restriction</span><span class="p">)</span> <span class="n">i</span><span class="o">.</span><span class="k">next</span><span class="p">();</span>
- <span class="sr">//</span> <span class="n">now</span> <span class="n">handle</span> <span class="n">the</span> <span class="n">restriction</span> <span class="err">Â
</span>
+ <span class="sr">//</span> <span class="n">now</span> <span class="n">handle</span> <span class="n">the</span> <span class="n">restriction</span> <span class="o">...</span>
<span class="p">}</span>
</pre></div>
<p>A general restriction can be converted to a specific type of
-restriction via <code>as</code> methods (if the information is already in the
+restriction via <code>as...</code> methods (if the information is already in the
model), or, if the information is not in the model, via
-<code>convertTo</code> methods. For example, to convert the example
+<code>convertTo...</code> methods. For example, to convert the example
restriction <code>r</code> from the example above to an all values from
restriction, you can do the following:</p>
<div class="codehilite"><pre><span class="n">OntClass</span> <span class="n">c</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">createClass</span><span class="p">(</span> <span class="n">NS</span> <span class="o">+</span> <span class="s">"SomeClass"</span> <span class="p">);</span>
@@ -1763,7 +1816,7 @@ list, and so forth. For example:</p>
union class expressions is straightforward. The <code>create</code> methods on
OntModel allow you to construct an intersection or union directly.
Alternatively, given an existing OntClass, you can use the
-<code>convertTo</code> methods to construct facet representing the more
+<code>convertTo...</code> methods to construct facet representing the more
specialised expressions. For example, we can define the class of UK
industry-related conferences as the intersection of conferences
with a UK location and conferences with an industrial track. Here's
@@ -1880,7 +1933,7 @@ following:</p>
<h3 id="listing_classes">Listing classes</h3>
<p>In many applications, you will need to inspect the set of classes
-in an ontology. The <code>list</code> methods on <code>OntModel</code> provide a variety
+in an ontology. The <code>list...</code> methods on <code>OntModel</code> provide a variety
of means of listing types of class. The methods available include:</p>
<div class="codehilite"><pre><span class="n">public</span> <span class="n">ExtendedIterator</span> <span class="n">listClasses</span><span class="p">();</span>
<span class="n">public</span> <span class="n">ExtendedIterator</span> <span class="n">listEnumeratedClasses</span><span class="p">();</span>
@@ -1910,7 +1963,7 @@ classes), use the
<a href="/jena/documentation/javadoc/com/hp/hpl/jena/ontology/OntTools.html">OntTools</a>
method <code>namedHierarchyRoots()</code>.</p>
<p>You should also note that it is important to close the iterators
-returned from the <code>list</code> methods, particularly when the underlying
+returned from the <code>list...</code> methods, particularly when the underlying
store is a database. This is necessary so that any state (e.g. the
database connection resources) can be released. Closing happens
automatically when the <code>hasNext()</code> method on the iterator returns
@@ -2011,8 +2064,8 @@ through the
interface. Suppose I wish to know the list of URI's that the
ontology imports. First I must obtain the resource representing the
ontology itself:</p>
-<div class="codehilite"><pre><span class="n">String</span> <span class="n">base</span> <span class="o">=</span> <span class="err">Â
</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">base</span> <span class="n">URI</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ontology</span>
-<span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="err">Â
</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">model</span> <span class="n">containing</span> <span class="n">the</span> <span class="n">ontology</span> <span class="n">statements</span>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">base</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">base</span> <span class="n">URI</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ontology</span>
+<span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">model</span> <span class="n">containing</span> <span class="n">the</span> <span class="n">ontology</span> <span class="n">statements</span>
<span class="n">Ontology</span> <span class="n">ont</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getOntology</span><span class="p">(</span> <span class="n">base</span> <span class="p">);</span>
<span class="sr">//</span> <span class="n">now</span> <span class="n">list</span> <span class="n">the</span> <span class="n">ontology</span> <span class="n">imports</span>
@@ -2031,7 +2084,7 @@ document has been read in to the model (
the imports of a document), there may well be more than one
<code>Ontology</code> resource in the model. In this case, you may find it
useful to list the ontology resources in just the base model:</p>
-<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="err">Â
</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">model</span><span class="p">,</span> <span class="n">including</span> <span class="n">imports</span>
+<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="o">...</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">model</span><span class="p">,</span> <span class="n">including</span> <span class="n">imports</span>
<span class="n">OntModel</span> <span class="n">mBase</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createOntologyModel</span><span class="p">(</span>
<span class="n">OntModelSpec</span><span class="o">.</span><span class="n">OWL_MEM</span><span class="p">,</span> <span class="n">m</span><span class="o">.</span><span class="n">getBaseModel</span><span class="p">()</span> <span class="p">);</span>
@@ -2054,8 +2107,8 @@ Smith, we can say:</p>
<p>It is also possible to programatically add imports and other
meta-data to a model, for example:</p>
-<div class="codehilite"><pre><span class="n">String</span> <span class="n">base</span> <span class="o">=</span> <span class="err">Â
</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">base</span> <span class="n">URI</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ontology</span>
-<span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="err">Â
</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">base</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span> <span class="sr">//</span> <span class="n">the</span> <span class="n">base</span> <span class="n">URI</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ontology</span>
+<span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span>
<span class="n">Ontology</span> <span class="n">ont</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">createOntology</span><span class="p">(</span> <span class="n">base</span> <span class="p">);</span>
<span class="n">ont</span><span class="o">.</span><span class="n">addImport</span><span class="p">(</span> <span class="n">m</span><span class="o">.</span><span class="n">createResource</span><span class="p">(</span> <span class="s">"http://example.com/import1"</span> <span class="p">)</span> <span class="p">);</span>
@@ -2152,7 +2205,7 @@ technique, which can sometimes be useful
use-cases, including debugging, is to snapshot the model by
constructing a temporary plain model and adding to it: the contents
of the ontology model:</p>
-<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span>
+<div class="codehilite"><pre><span class="n">OntModel</span> <span class="n">m</span> <span class="o">=</span> <span class="o">...</span>
<span class="sr">//</span> <span class="n">snapshot</span> <span class="n">the</span> <span class="n">contents</span> <span class="n">of</span> <span class="n">ont</span> <span class="n">model</span> <span class="n">om</span>
<span class="n">Model</span> <span class="n">snapshot</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createDefaultModel</span><span class="p">();</span>