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/09/13 01:39:52 UTC
svn commit: r795655 [2/4] - in /websites/staging/jena/trunk/content/jena: ./
about_jena/ documentation/ documentation/assembler/
documentation/inference/ documentation/larq/ documentation/notes/
documentation/ontology/ documentation/query/ documentatio...
Added: websites/staging/jena/trunk/content/jena/documentation/notes/rdf-frames.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/rdf-frames.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/rdf-frames.html Mon Sep 12 23:39:50 2011
@@ -0,0 +1,407 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ 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.
+-->
+
+ <link href="/jena/css/jena.css" rel="stylesheet" type="text/css">
+ <title>Apache Jena - Presenting RDF as frames</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="/jena/js/jquery-1.6.1.min.js" type="text/javascript"></script>
+ <script src="/jena/js/jena-navigation.js" type="text/javascript"></script>
+</head>
+
+<body>
+ <div id="header">
+ <div id="logoblock">
+ <img alt="Apache Jena" src="/jena/images/jena-logo/jena-logo-small.png"/>
+ </div>
+
+ <div id="titleblock">
+ <h1 class="title">Apache Jena</h1>
+ <div id="topmenu" class="tabbar round-10">
+ <ul>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/index.html" id="home_menu">Home</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/help_and_support/index.html">Support</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/getting_started/index.html">Getting started</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/tutorials/index.html">Tutorials</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/documentation/index.html">Documentation</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="navigation" class="clear">
+ <h1 id="quick_links">Quick links</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/download/index.html">Downloads</a></li>
+<li><a href="/jena/help_and_support/index.html">Help and support</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/getting_involved/index.html">Getting involved</a></li>
+</ul>
+<h1 id="about_jena">About Jena</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/about_jena/about.html">About Jena</a></li>
+<li><a href="/jena/about_jena/architecture.html">Architecture</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/about_jena/team.html">Project team</a></li>
+</ul>
+<h1 id="download">Download</h1>
+<ul>
+<li><a href="/jena/download/index.html">Downloading Jena</a></li>
+<li><a href="/jena/download/maven.html">Using Maven</a></li>
+<li><a href="/jena/download/osgi.html">Using OSGi</a></li>
+</ul>
+<h1 id="help_and_support">Help and support</h1>
+<ul>
+<li><a href="/jena/help_and_support/index.html">Getting help</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Bugs and suggestions</a></li>
+</ul>
+<h1 id="getting_started">Getting Started</h1>
+<ul>
+<li><a href="/jena/getting_started/index.html">A first Jena project</a></li>
+<li><a href="/jena/getting_started/rdf_api.html">RDF API overview</a></li>
+<li><a href="/jena/getting_started/sparql.html">Querying RDF with SPARQL</a></li>
+<li><a href="/jena/getting_started/fuseki.html">Serving RDF over HTTP</a></li>
+<li><a href="/jena/getting_started/tell_me_how.html">Tell me how to ...</a></li>
+</ul>
+<h1 id="tutorials">Tutorials</h1>
+<ul>
+<li><a href="/jena/tutorials/index.html">RDF tutorial</a></li>
+<li><a href="/jena/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/jena/tutorials/usingklzzwxh:0025jenaklzzwxh:0026withklzzwxh:0027eclipse.html">Using Jena with Eclipse</a></li>
+</ul>
+<h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="/jena/documentation/index.html">Overview</a></li>
+<li><a href="/jena/documentation/javadoc">Javadoc</a></li>
+<li><a href="/jena/documentation/rdf/index.html">RDF</a></li>
+<li><a href="/jena/documentation/query/index.html">Query</a></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a></li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">Serving Data</a></li>
+<li><a href="/jena/documentation/ontology/index.html">Ontology</a></li>
+<li><a href="/jena/documentation/inference/index.html">Inference</a></li>
+<li><a href="/jena/documentation/assembler/index.html">Assembler</a><ul>
+<li><a href="/jena/documentation/assembler/assembler-howto.html">Assembler how-to</a></li>
+<li><a href="/jena/documentation/assembler/inside-assemblers.html">Inside assemblers</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/jena/documentation/assembler/concurrency-howto.html">Concurrency how-to</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="getting_involved">Getting Involved</h1>
+<ul>
+<li><a href="/jena/getting_involved/index.html">Contributing to Jena</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Presenting RDF as frames</h1>
+ <p>The origins of RDF as a representation language include
+<em>frame languages</em>, in which an object, or frame, was the main unit
+of structuring data. Frames have <em>slots</em>, for example a <code>Person</code>
+frame might have an <code>age</code> slot, a <code>height</code>slot etc. RDF, however,
+has taken a step beyond frame languages by making <code>rdf:Property</code> a
+first class value, not an element of a frame or resource <em>per se</em>.
+In RDF, for example, an age property can be defined:
+<code><rdf:Property rdf:ID="age"></code>, and then applied to any resource,
+including, but not limited to a <code>Person</code> resource.</p>
+<p>While this introduces an extra element of modelling flexibility in
+RDF, it is often the case that users want to treat some components
+in their models in a more structured way, similar to the original
+idea of frames. It is often assumed that <code>rdfs:domain</code> restricts a
+property to be used only on resources that are in the domain class.
+For example, a frequently asked question on the Jena support list
+is why the following is not an error:</p>
+<div class="codehilite"><pre> <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"Person"</span> <span class="nt">/></span>
+ <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"Truck"</span> <span class="nt">/></span>
+ <span class="nt"><rdf:Property</span> <span class="na">rdf:ID=</span><span class="s">"age"</span><span class="nt">></span>
+ <span class="nt"><rdfs:domain</span> <span class="na">rdf:resource=</span><span class="s">"Person"</span> <span class="nt">/></span>
+ <span class="nt"></rdf:Property></span>
+
+ <span class="nt"><Truck</span> <span class="na">rdf:ID=</span><span class="s">"truck1"</span><span class="nt">></span>
+ <span class="nt"><age></span>2<span class="nt"></a></span>
+ <span class="nt"></Truck></span>
+</pre></div>
+
+
+<p>Whereas many object-oriented or frame-oriented representations
+would regard it as an error that the <code>age</code> property was not being
+applied to a <code>Person</code>, RDF-based applications are simply entitled
+to infer that <code>truck1</code> is a (that is, has <code>rdf:type</code>) <code>Truck</code> as
+well as a <code>Person</code>. This is unlikely to be the case in any
+real-world domain, but it is a valid RDF inference.</p>
+<p>A consequence of RDF's design is that it is not really possible to
+answer the commonly asked question "Which properties can be applied
+to resources of class <em>C</em>?". Strictly speaking, the RDF answer is
+"Any property". However, many developers have a legitimate
+requirement to present a composite view of classes and their
+associated properties, forming more a more succinct structuring of
+an ontology or schema. The purpose of this note is to explain the
+mechanisms built-in to Jena to support a frame-like view of
+resources, while remaining correct with respect to RDF (and OWL)
+semantics.</p>
+<h2 id="basic_principles_the_properties_of_a_class">Basic principles: the properties of a class</h2>
+<p>Since any RDF property can be applied to any RDF resource, we
+require a definition of the properties of a given class that
+respects RDF semantics. Consider the following RDF fragment:</p>
+<div class="codehilite"><pre> <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"Person"</span> <span class="nt">/></span>
+ <span class="nt"><rdf:Property</span> <span class="na">rdf:ID=</span><span class="s">"age"</span> <span class="nt">/></span>
+
+ <span class="nt"><Person</span> <span class="na">rdf:ID=</span><span class="s">"jane_doe"</span><span class="nt">></span>
+ <span class="nt"><age></span>23<span class="nt"></a></span>
+ <span class="nt"></Person></span>
+</pre></div>
+
+
+<p>Now consider that we add to this fragment that:</p>
+<div class="codehilite"><pre> <span class="nt"><rdf:Property</span> <span class="na">rdf:about=</span><span class="s">"age"</span><span class="nt">></span>
+ <span class="nt"><rdfs:domain</span> <span class="na">rdf:resource=</span><span class="s">"Person"</span> <span class="nt">/></span>
+ <span class="nt"></rdf:Property></span>
+</pre></div>
+
+
+<p>This additional information about the domain of the <code>age</code> property
+does not add any new entailments to the model. Why? Because we
+already know that <code>jane_doe</code> is a Person. So we can consider <code>age</code>
+to be one of the properties of <code>Person</code> type resources, because if
+we use the property as a predicate of that resource, it doesn't add
+any new <code>rdf:type</code> information about the resource. Conversely, if
+we know that some resource has an <code>age</code>, we don't learn any new
+information by declaring that it has <code>rdf:type Person</code>. In summary,
+for the purposes of this HOWTO we define the
+<em>properties of a class</em> as just those properties that don't entail
+any new type information when applied to resources that are already
+known to be of that class.</p>
+<h2 id="sub-classes_and_more_complex_class_expressions">Sub-classes, and more complex class expressions</h2>
+<p>Given these basic principles, now consider the following RDF
+fragment:</p>
+<div class="codehilite"><pre> <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"LivingThing"</span> <span class="nt">/></span>
+
+ <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"Animal"</span><span class="nt">></span>
+ <span class="nt"><rdfs:subClassOf</span> <span class="na">rdf:resource=</span><span class="s">"#LivingThing"</span><span class="nt">></span>
+ <span class="nt"></rdfs:Class></span>
+
+ <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"Mammal"</span><span class="nt">></span>
+ <span class="nt"><rdfs:subClassOf</span> <span class="na">rdf:resource=</span><span class="s">"#Animal"</span><span class="nt">></span>
+ <span class="nt"></rdfs:Class></span>
+
+ <span class="nt"><rdf:Property</span> <span class="na">rdf:ID=</span><span class="s">"hasSkeleton"</span><span class="nt">></span>
+ <span class="nt"><rdfs:domain</span> <span class="na">rdf:resource=</span><span class="s">"Animal"</span> <span class="nt">/></span>
+ <span class="nt"></rdf:Property></span>
+</pre></div>
+
+
+<p>Is <code>hasSkeleton</code> one of the properties of <code>Animal</code>? Yes, because
+any resource of <code>rdf:type Animal</code> can have a <code>hasSkeleton</code> property
+(with value either true or false) without adding type information.
+Similarly, any resource that is a <code>Mammal</code> also has
+<code>rdf:type Animal</code> (by the sub-class relation), so <code>hasSkeleton</code> is
+a property of <code>Mammal</code>. However, <code>hasSkeleton</code> is <em>not</em> a property
+of <code>LivingThing</code>, since we don't automatically know that a living
+thing is an animal - it may be a plant. Stating that a given
+<code>LivingThing</code> has a <code>hasSkeleton</code> property, even if the value is
+false, would entail the additional <code>rdf:type</code> statement that the
+<code>LivingThing</code> is also an <code>Animal</code>.</p>
+<p>For more complex class expressions in the domain, we look to see
+what simple domain constraints are entailed. For example, a domain
+constraint <code>AÂ â©Â B</code> (i.e. "A intersection B") for property <code>p</code>
+entails that both <code>p rdfs:domain A</code> and <code>p rdfs:domain B</code> are true.
+However, the properties of neither <code>A</code> nor <code>B</code> will include <code>p</code>. To
+see this, suppose we have a resource <code>x</code> that we already know is of
+type <code>A</code>, and a statement <code>x p y</code>. This entails <code>x rdf:type A</code>
+which we already know, but also <code>x rdf:type B</code>. So information is
+added, even if we know that <code>x</code> is an instance <code>A</code>, so <code>p</code> is not a
+property of <code>A</code>. The symmetrical argument holds for <code>p</code> not being a
+property of <code>B</code>.</p>
+<p>However, if the domain of <code>p</code> is <code>A âªÂ B</code> (i.e. "A union B"), then
+both <code>A</code> and <code>B</code> will have <code>p</code> as a property, since an occurrence
+of, say <code>x p y</code> does not allow us to conclude that either
+<code>x rdf:type A</code> or <code>x rdf:type B</code>.</p>
+<h2 id="property_hierarchies">Property hierarchies</h2>
+<p>Since sub-properties inherit the domain constraints of their parent
+property, the properties of a class will include the closure over
+the sub-property hierarchy. Extending the previous example, the
+properties of <code>Animal</code> and <code>Mammal</code> include both <code>hasSkeleton</code> and
+<code>hasEndoSkeleton</code>:</p>
+<div class="codehilite"><pre> <span class="nt"><rdf:Property</span> <span class="na">rdf:ID=</span><span class="s">"hasSkeleton"</span><span class="nt">></span>
+ <span class="nt"><rdfs:domain</span> <span class="na">rdf:resource=</span><span class="s">"Animal"</span> <span class="nt">/></span>
+ <span class="nt"></rdf:Property></span>
+
+ <span class="nt"><rdf:Property</span> <span class="na">rdf:ID=</span><span class="s">"hasEndoSkeleton"</span><span class="nt">></span>
+ <span class="nt"><rdfs:subPropertyOf</span> <span class="na">rdf:resource=</span><span class="s">"#hasSkeleton"</span> <span class="nt">/></span>
+ <span class="nt"></rdf:Property></span>
+</pre></div>
+
+
+<p>In general, there may be many different ways of deducing simple
+domain constraints from the axioms asserted in the ontology.
+Whether or not all of these possible deductions are present in any
+given RDF model depends on the power and completeness of the
+reasoner bound to that model.</p>
+<h2 id="global_properties">Global properties</h2>
+<p>Under the principled definition that we propose here, properties
+which do not express a domain value are <em>global</em>, in the sense that
+they can apply to any resource. They do not, by definition, entail
+any new type information about the individuals they are applied to.
+Put another way, the domain of a property, if unspecified, is
+either <code>rdfs:Resource</code> or <code>owl:Thing</code>, depending on the ontology
+language. These are simply the types that all resources have by
+default. Therefore, every class has all of the global properties as
+one of the properties of the class.</p>
+<p>A commonly used idiom in some OWL ontologies is to use
+<em>Restrictions</em> to create an association between a class and the
+properties of instances of that class. For example, the following
+fragment shows that all instances of <code>Person</code> should have a
+<code>familyName</code> property:</p>
+<div class="codehilite"><pre> <span class="nt"><owl:Class</span> <span class="na">rdf:ID=</span><span class="s">"Person"</span><span class="nt">></span>
+ <span class="nt"><rdfs:subClassOf></span>
+ <span class="nt"><owl:Restriction></span>
+ <span class="nt"><owl:onProperty</span> <span class="na">rdf:resource=</span><span class="s">"#familyName"</span> <span class="nt">/></span>
+ <span class="nt"><owl:minCardinality</span> <span class="na">rdf:datatype=</span><span class="s">"&xsd;int"</span><span class="nt">></span>1<span class="nt"></owl:minCardinality></span>
+ <span class="nt"></owl:Restriction></span>
+ <span class="nt"></rdfs:subClassOf></span>
+ <span class="nt"></owl:Class></span>
+</pre></div>
+
+
+<p>This approach shows the intent of the ontology designer that
+<code>Person</code> instances have <code>familyName</code> properties. We do regard
+<code>familyName</code> as one of the <em>properties of</em> <code>Person</code>, but only
+because of the global properties principle. Unless a domain
+constraint is also specified for <code>familyName</code>, it will appear as
+one of the properties of classes other than <code>Person</code>.
+<strong>Note that this is a behaviour change from versions of Jena prior to release 2.2</strong>.
+Prior to this release, Jena used a heuristic method to attempt to
+associate restriction properties with the classes sub-classing that
+restriction. Since there were problems with precisely defining the
+heuristic, and ensuring correct behaviour (especially with
+inference models), we have dropped the use of this heuristic from
+Jena 2.2 onwards.</p>
+<h2 id="the_java_api">The Java API</h2>
+<p>Support for frame-like views of classes and properties is provided
+through the <a href="../ontology/index.html">ontology API</a>. The following
+methods are used to access the properties of a class, and the
+converse for properties:</p>
+<div class="codehilite"><pre> <span class="n">OntClass</span><span class="o">.</span><span class="n">listDeclaredProperties</span><span class="p">();</span>
+ <span class="n">OntClass</span><span class="o">.</span><span class="n">listDeclaredProperties</span><span class="p">(</span> <span class="n">boolean</span> <span class="n">direct</span> <span class="p">);</span>
+ <span class="n">OntClass</span><span class="o">.</span><span class="n">hasDeclaredProperty</span><span class="p">(</span> <span class="n">Property</span> <span class="n">prop</span><span class="p">,</span> <span class="n">boolean</span> <span class="n">direct</span> <span class="p">);</span>
+ <span class="n">OntProperty</span><span class="o">.</span><span class="n">listDeclaringClasses</span><span class="p">();</span>
+ <span class="n">OntProperty</span><span class="o">.</span><span class="n">listDeclaringClasses</span><span class="p">(</span> <span class="n">boolean</span> <span class="n">direct</span> <span class="p">);</span>
+</pre></div>
+
+
+<p>All of the above API methods return a Jena
+<a href="../javadoc/com/hp/hpl/jena/util/iterator/ExtendedIterator.html"><code>ExtendedIterator</code></a>.</p>
+<p><strong>Note a change from the Jena 2.1 interface:</strong> the optional Boolean
+parameter on <code>listDeclaredProperties</code> has changed name from <code>all</code>
+(Jena 2.1 and earlier) to <code>direct</code> (Jena 2.2 and later). The
+meaning of the parameter has also changed: <code>all</code> was intended to
+simulate some reasoning steps in the absence of a reasoner, whereas
+<code>direct</code> is used to restrict the associations to only the local
+associations. See more on
+<a href="../ontology/index.html#direct_relationships">direct associations</a>.</p>
+<p>A further difference from Jena 2.1 is that the models that are
+constructed without reasoners perform only very limited simulation
+of the inference closure of the model. Users who wish the declared
+properties to include entailments will need to construct their
+models with one of the built-in or external reasoners. The
+difference is illustrated by the following code fragment:</p>
+<div class="codehilite"><pre> <span class="nt"><rdfs:Class</span> <span class="na">rdf:ID=</span><span class="s">"A"</span> <span class="nt">/></span>
+ <span class="nt"><rdfs:Property</span> <span class="na">rdf:ID=</span><span class="s">"p"</span><span class="nt">></span>
+ <span class="nt"><rdfs:domain</span> <span class="na">rdf:resource=</span><span class="s">"#A"</span> <span class="nt">/></span>
+ <span class="nt"></rdfs:Property></span>
+ <span class="nt"><rdfs:Property</span> <span class="na">rdf:ID=</span><span class="s">"q"</span><span class="nt">></span>
+ <span class="nt"><rdfs:subPropertyOf</span> <span class="na">rdf:resource=</span><span class="s">"#p"</span> <span class="nt">/></span>
+ <span class="nt"></rdfs:Property></span>
+
+ OntModel mNoInf = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM );
+ OntClass a0 = mNoInf.getOntClass( NS + "A" );
+ Iterator i0 = a0.listDeclaredProperties();
+
+ OntModel mInf = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM_RULE_INF );
+ OntClass a1 = mInf.getOntClass( NS + "A" );
+ Iterator i1 = a1.listDeclaredProperties();
+</pre></div>
+
+
+<p>Iterator <code>i1</code> will return <code>p</code> and <code>q</code>, while <code>i0</code> will return only
+<code>p</code>.</p>
+<h2 id="summary_of_changes_from_jena_22-beta-2_and_older">Summary of changes from Jena 2.2-beta-2 and older</h2>
+<p>For users updating code that uses <code>listDeclaredProperties</code> from
+versions of Jena prior to 2.2-final, the following changes should
+be noted:</p>
+<ul>
+<li>Global properties
+ <code>listDeclaredProperties</code> will treat properties with no specified
+ domain as global, and regard them as properties of all classes. The
+ use of the <code>direct</code> flag can hide global properties from non-root
+ classes.</li>
+<li>Restriction properties
+ <code>listDeclaredProperties</code> no longer heuristically returns properties
+ associated with a class via the <code>owl:onProperty</code> predicate of a
+ restriction.</li>
+<li>Limited simulated inference
+ The old version of <code>listDeclaredProperties</code> attempted to simulate
+ the entailed associations between classes and properties. Users are
+ now advised to attach a reasoner to their models to do this.</li>
+<li>Change in parameter semantics
+ The old version of <code>listDeclaredProperties(boolean all)</code> took one
+ parameter, a Boolean flag to indicate whether additional declared
+ (implied) properties should be listed. Since this is now covered by
+ the use, or otherwise, of a reasoner attached to the model, the new
+ method signature is <code>listDeclaredProperties(boolean direct)</code>, where
+ calling the method with <code>direct = true</code> will compress the returned
+ results to use only the
+ <a href="../ontology/index.html#direct_relationships">direct</a>
+ associations.</li>
+</ul>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/jena/trunk/content/jena/documentation/notes/reification.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/reification.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/reification.html Mon Sep 12 23:39:50 2011
@@ -0,0 +1,307 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ 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.
+-->
+
+ <link href="/jena/css/jena.css" rel="stylesheet" type="text/css">
+ <title>Apache Jena - Reification howto</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="/jena/js/jquery-1.6.1.min.js" type="text/javascript"></script>
+ <script src="/jena/js/jena-navigation.js" type="text/javascript"></script>
+</head>
+
+<body>
+ <div id="header">
+ <div id="logoblock">
+ <img alt="Apache Jena" src="/jena/images/jena-logo/jena-logo-small.png"/>
+ </div>
+
+ <div id="titleblock">
+ <h1 class="title">Apache Jena</h1>
+ <div id="topmenu" class="tabbar round-10">
+ <ul>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/index.html" id="home_menu">Home</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/help_and_support/index.html">Support</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/getting_started/index.html">Getting started</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/tutorials/index.html">Tutorials</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/documentation/index.html">Documentation</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="navigation" class="clear">
+ <h1 id="quick_links">Quick links</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/download/index.html">Downloads</a></li>
+<li><a href="/jena/help_and_support/index.html">Help and support</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/getting_involved/index.html">Getting involved</a></li>
+</ul>
+<h1 id="about_jena">About Jena</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/about_jena/about.html">About Jena</a></li>
+<li><a href="/jena/about_jena/architecture.html">Architecture</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/about_jena/team.html">Project team</a></li>
+</ul>
+<h1 id="download">Download</h1>
+<ul>
+<li><a href="/jena/download/index.html">Downloading Jena</a></li>
+<li><a href="/jena/download/maven.html">Using Maven</a></li>
+<li><a href="/jena/download/osgi.html">Using OSGi</a></li>
+</ul>
+<h1 id="help_and_support">Help and support</h1>
+<ul>
+<li><a href="/jena/help_and_support/index.html">Getting help</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Bugs and suggestions</a></li>
+</ul>
+<h1 id="getting_started">Getting Started</h1>
+<ul>
+<li><a href="/jena/getting_started/index.html">A first Jena project</a></li>
+<li><a href="/jena/getting_started/rdf_api.html">RDF API overview</a></li>
+<li><a href="/jena/getting_started/sparql.html">Querying RDF with SPARQL</a></li>
+<li><a href="/jena/getting_started/fuseki.html">Serving RDF over HTTP</a></li>
+<li><a href="/jena/getting_started/tell_me_how.html">Tell me how to ...</a></li>
+</ul>
+<h1 id="tutorials">Tutorials</h1>
+<ul>
+<li><a href="/jena/tutorials/index.html">RDF tutorial</a></li>
+<li><a href="/jena/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/jena/tutorials/usingklzzwxh:0025jenaklzzwxh:0026withklzzwxh:0027eclipse.html">Using Jena with Eclipse</a></li>
+</ul>
+<h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="/jena/documentation/index.html">Overview</a></li>
+<li><a href="/jena/documentation/javadoc">Javadoc</a></li>
+<li><a href="/jena/documentation/rdf/index.html">RDF</a></li>
+<li><a href="/jena/documentation/query/index.html">Query</a></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a></li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">Serving Data</a></li>
+<li><a href="/jena/documentation/ontology/index.html">Ontology</a></li>
+<li><a href="/jena/documentation/inference/index.html">Inference</a></li>
+<li><a href="/jena/documentation/assembler/index.html">Assembler</a><ul>
+<li><a href="/jena/documentation/assembler/assembler-howto.html">Assembler how-to</a></li>
+<li><a href="/jena/documentation/assembler/inside-assemblers.html">Inside assemblers</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/jena/documentation/assembler/concurrency-howto.html">Concurrency how-to</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="getting_involved">Getting Involved</h1>
+<ul>
+<li><a href="/jena/getting_involved/index.html">Contributing to Jena</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Reification howto</h1>
+ <h2 id="introduction">Introduction</h2>
+<p>This document describes the Jena 2 reification API and how to use
+it. New users of Jena should read this to understand Jena's special
+support for reification. Since there have been significant changes
+to this support since Jena 1, users of Jena 1's reification should
+also read this document to see how to translate their existing code
+to the new form. As always, consult the Javadoc for interface
+details.</p>
+<p>Reification in RDF and Jena is the ability to treat a <code>Statement</code>
+as a <code>Resource</code>, and hence to make assertions <em>about</em> that
+statement. A statement may be reified as many different resources,
+allowing different manifestations ("statings") of that statement to
+be treated differently if required.</p>
+<p>RDF represents a reified statement as four statements with
+particular RDF properties and objects: the statement <code>(S, P, O)</code>,
+reified by resource <code>R</code>, is represented by:</p>
+<ul>
+<li><code>R rdf:type rdf:Statement</code></li>
+<li><code>R rdf:subject S</code></li>
+<li><code>R rdf:predicate P</code></li>
+<li><code>R rdf:object O</code></li>
+</ul>
+<p>We shall call these four such statements a <em>reification quad</em> and
+the components <em>quadlets</em>. Users of reification in Jena may, by
+default, simply manipulate reified statements as these quads.
+However, just as for <code>Bag</code>, <code>Seq</code>, <code>Alt</code> and <code>RDF lists</code> in
+ordinary models, or ontology classes and individuals in
+<code>OntModel</code>s, Jena has additional support for manipulating reified
+statements. It also optimises the storage for complete reification
+quads, avoiding having to store the extra four statements merely to
+represent one reification.</p>
+<p>The interface <code>ReifiedStatement</code> is used to represent a reified
+statement as a Jena <code>Resource</code> that has direct access to the
+statement it reifies. The method</p>
+<ul>
+<li><code>ReifiedStatement::getStatement()</code></li>
+</ul>
+<p>returns the <code>Statement</code> that the resource is reifying. All the
+other <code>Resource</code> methods, of course, may be applied to a
+<code>ReifiedStatement</code>.</p>
+<h2 id="converting_resources_to_reified_statements">Converting resources to reified statements</h2>
+<p>If a resource <code>R</code> is associated with a reified statement, but might
+not itself be a <code>ReifiedStatement</code> object, the conversion method
+<code>RDFNode::as(Class)</code> can be used to find (or create) a
+<code>ReifiedStatement</code>:
+- <code>(ReifiedStatement) R.as(ReifiedStatement.class)</code></p>
+<p>For example, a model that has been read in from an RDF/XML file may
+have reified statements: knowing the name of the resource allows a
+ReifiedStatement object to be constructed without knowing the
+statement itself.</p>
+<p>If there is no such associated reified statement, a
+<code>CannotReifyException</code> is thrown. To find out in advance if the
+conversion is possible, use the predicate
+<code>RDFNode::canAs(ReifiedStatement.class)</code>. (Jena only counts as "an
+associated reified statement" a resource with exactly one
+<code>rdf:subject</code>, <code>rdf:predicate</code>, and <code>rdf:object</code> which has
+<code>rdf:type rdf:Statement</code>. It can of course have <em>other</em>
+properties.)</p>
+<p>Once the <code>ReifiedStatement</code> has been constructed, it retains its
+<code>Statement</code> even if some (or all) of the original quadlets are
+removed from the model. This is a feature of the current
+implementation that might go away; do not rely on it.</p>
+<h2 id="testing_statements_for_reification">Testing statements for reification</h2>
+<p>You may wish to know if some <code>Statement</code> is reified. The methods
+<code>Statement::isReified()</code> and <code>Model::isreified(Statement)</code> return
+true if (and only if) the statement has been reified in the model.
+Note that the <code>Statement</code> method tests to see if the statement is
+reified in its own model, and the model method tests to see if the
+<code>Statement</code> is reified in <em>that</em> model; there is no test to see if
+a <code>Statement</code> is reified in any other models.</p>
+<h2 id="listing_reified_statements">Listing reified statements</h2>
+<p>Just as <code>listStatements</code> is used to find the statements present in
+some model, there are methods for finding the reified statements of
+a model. Each of them returns a <code>RSIterator</code> object, which is an
+iterator each of who's elements are <code>ReifiedStatement</code>s and for
+which the convenience method <code>nextRS()</code> will deliver a
+suitably-cast reified statement.
+- <code>Statement::listReifiedStatements()</code> - all the reifications of
+ this statement in its model.
+- <code>Model::listReifiedStatements()</code> - all the reified statements
+ in this model.
+- <code>Model::listReifiedStatements(Statement s)</code> - all the reified
+ statements reifiying <code>s</code> in this model.</p>
+<h2 id="creating_reified_statements_directly">Creating reified statements directly</h2>
+<p>You do not have to create reified statements by asserting their
+quads into a <code>Model</code>; they can be created directly from their
+<code>Statement</code>s using one of the methods:
+- <code>Statement::createReifiedStatement()</code>
+- <code>Statement::createReifiedStatement(String)</code>
+- <code>Model::createReifiedStatement(Statement)</code>
+- <code>Model::createReifiedStatement(String,Statement)</code></p>
+<p>Each of these returns a <code>ReifiedStatement</code> who's <code>getStatement()</code>
+method delivers the original statement (actually, a <code>.equals()</code>
+statement; it may not be the identical statement). If the creation
+method passed in a (non-null) <code>String</code>, the <code>ReifiedStatement</code> is a
+named resource and that string is its URI. Otherwise it is a
+newly-minted bnode. The methods on <code>Statement</code> create a reified
+statement in that statements model; those on <code>Model</code> create a
+reified statement in that model.
+It is not permitted for two different (non-equals) statements to be
+reified onto the same resource. An attempt to do so will generate
+an <code>AlreadyReifiedException</code>.</p>
+<p>The additional method <code>Model::getAnyReifiedStatement(Statement)</code>
+returns some reification of the supplied <code>Statement</code>; an existing
+one if possible, otherwise a fresh one (reified by a fresh bnode).</p>
+<h2 id="reification_and_modeladdmodel">Reification and Model::add(Model)</h2>
+<p>When one model is added to another, as well as the ordinary
+statements of the model being added, the reified statements are
+copied across. If this is not desired, there is a two-argument
+form:
+- Model::add(Model m, boolean suppress)</p>
+<p>If <code>suppress</code> is <code>true</code>, then the reified statements are not
+copied. (This choice arose from comments on earlier versions of the
+Jena 2 API; users expected the reified statements to be copied.)</p>
+<h2 id="removing_reified_statements">Removing reified statements</h2>
+<p>There are two methods which remove all the reifications of a
+<code>Statement</code> in some <code>Model</code>:
+- <code>Statement::removeReification()</code>
+- <code>Model::removeAllReifications(Statement)</code></p>
+<p>All the reified statements in the model that reify the given
+statement are removed, whatever their reifying resource. To remove
+a particular reified statement only, use
+- <code>Model::removeReification(ReifiedStatement)</code></p>
+<p>Similarly to <code>Model::add(Model)</code>, the method
+<code>model.remove(Model m)</code> will remove all the reified statements of
+<code>m</code> from <code>model</code>, and the two-argument form <code>model.remove(m,true)</code>
+will not.</p>
+<h2 id="reification_styles">Reification styles</h2>
+<p>By default and as you might expect, Jena models allow reification
+quads to be manifested as <code>ReifiedStatement</code>s. Similarly,
+explicitly created <code>ReifiedStatement</code>s are visible as statement
+quads.</p>
+<p>Sometimes this is not desirable. For example, in an application
+that reifies large numbers of statements in the same model as those
+statements, most of the results from <code>listStatements()</code> will be
+quadlets; this is inefficient and confusing. One choice is to reify
+the statements in a <em>different</em> model. Another is to take advantage
+of <em>reification styles</em>.</p>
+<p>Each model has a reification style, described by constants in
+<code>ModelFactory</code>. The default style is called <code>Standard</code> because it
+behaves mostly closely to the RDF standard. There are two other
+reification styles to choose from:</p>
+<ul>
+<li><code>Convenient</code>: reification quadlets are not visible in the
+ results of <code>listStatements)()</code>. Otherwise everything is normal;
+ quadlets that are added to the model contribute to
+ <code>ReifiedStatement</code> construction.</li>
+<li><code>Minimal</code>: reification quadlets play no role at all in the
+ construction of <code>ReifiedStatement</code>s, which can only be created by
+ the methods discussed earlier. This style is most similar to that
+ of Jena 1.</li>
+</ul>
+<p>The method <code>ModelFactory.createDefaultModel()</code> takes an optional
+<code>Style</code> argument, which defaults to <code>Standard</code>. Similarly,
+<code>createFileModelMaker()</code> and <code>createMemModelMaker()</code> can take
+<code>Style</code> arguments which are applied to every model they create.
+To take a model with hidden reification quads and expose them as
+statements, the method <code>ModelFactory.withHiddenStatements(Model m)</code>
+produces a new model which does just that.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>