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/11/20 19:31:39 UTC
svn commit: r799006 - in
/websites/staging/jena/trunk/content/jena/documentation/notes: index.html
jena-internals.html
Author: buildbot
Date: Sun Nov 20 18:31:39 2011
New Revision: 799006
Log:
Staging update by buildbot
Added:
websites/staging/jena/trunk/content/jena/documentation/notes/jena-internals.html
Modified:
websites/staging/jena/trunk/content/jena/documentation/notes/index.html
Modified: websites/staging/jena/trunk/content/jena/documentation/notes/index.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/index.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/index.html Sun Nov 20 18:31:39 2011
@@ -155,6 +155,12 @@
<ul>
<li><a href="concurrency-howto.mdtext">Concurrency how-to</a> Handling concurrent access to Jena models</li>
<li><a href="event-handler-howto.mdtext">Event handler how-to</a> Responding to events</li>
+<li><a href="file-manager.html">File manager how-to</a> Convenient access to RDF files</li>
+<li><a href="jena-internals.html">Jena internals</a> Notes on internal architecture (now rather old)</li>
+<li><a href="model-factory.html">Model factory</a> Creating Jena models of various kinds</li>
+<li><a href="rdf-frames.html">RDF frames</a> Viewing RDF statements as frame-like objects</li>
+<li><a href="reification.html">Reification</a> API support for RDF reification</li>
+<li><a href="typed-literals.html">Typed literals</a> Creating and extracting RDF typed literals</li>
</ul>
</div>
Added: websites/staging/jena/trunk/content/jena/documentation/notes/jena-internals.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/jena-internals.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/jena-internals.html Sun Nov 20 18:31:39 2011
@@ -0,0 +1,615 @@
+<!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 - Notes on Jena internals</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="/jena/js/jquery-1.6.4.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>
+<li><a href="/jena/documentation/">Documentation</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">Tutorials index</a></li>
+<li><a href="/jena/tutorials/rdf_api.html">RDF tutorial</a></li>
+<li><a href="/jena/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/jena/tutorials/using_jena_with_eclipse.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">SPARQL (ARQ)</a></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</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/io/index.html">I/O</a><ul>
+<li><a href="/jena/documentation/io/iohowto.html">I/O how-to</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/jena/documentation/notes/concurrency-howto.html">Concurrency how-to</a></li>
+<li><a href="/jena/documentation/notes/event-handler-howto.html">Event handler how-to</a></li>
+<li><a href="/jena/documentation/notes/file-manager.html">File manager how-to</a></li>
+<li><a href="/jena/documentation/notes/model-factory.html">Model factory how-to</a></li>
+<li><a href="/jena/documentation/notes/rdf-frames.html">RDF frames</a></li>
+<li><a href="/jena/documentation/notes/reification.html">Reification how-to</a></li>
+<li><a href="/jena/documentation/notes/typed-literals.html">Typed literals 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>
+<li><a href="/jena/documentation/tools/eyeball-getting-started.html">eyeball</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">Notes on Jena internals</h1>
+ <p><strong>Note:</strong> These notes are quite old now, but may still be of some interest in the design
+and architecture of Jena.</p>
+<h2 id="enhanced_nodes">Enhanced Nodes</h2>
+<p>This note is a development of the original note on the enhanced
+node and graph design of Jena 2.</p>
+<h3 id="key_objectives_for_the_enhanced_node_design">Key objectives for the enhanced node design</h3>
+<p>One problem with the Jena 1 design was that both the DAML layer and
+the RDB layer independently extended Resource with domain-specific
+information. That made it impossible to have a DAML-over-RDB
+implementation. While this could have been fixed by using the
+"enhanced resource" mechanism of Jena 1, that would have left a
+second problem.</p>
+<p>In Jena 1.0, once a resource has been determined to be a DAML Class
+(for instance), that remains true for the lifetime of the model. If
+a resource starts out not qualifying as a DAML Class (no
+<code>rdf:type daml:Class</code>) then adding the type assertion later doesn't
+make it a Class. Similarly, of a resource is a DAML Class, but then
+the type assertion is retracted, the resource is still apparently a
+class.</p>
+<p>Hence being a DAMLClass is a <em>view</em> of the resource that may change
+over time. Moreover, a given resource may validly have a number of
+different views simultaneously. Using the current <code>DAMLClass</code>
+implementation method means that a given resource is limited to a
+single such view.</p>
+<p>A key objective of the new design is to allow different views, or
+<em>facets</em>, to be used dynamically when accessing a node. The new
+design allows nodes to be polymorphic, in the sense that the same
+underlying node from the graph can present different encapsulations
+- thus different affordances to the programmer - on request.</p>
+<p>In summary, the enhanced node design in Jena 2.0 allows programmers
+to:</p>
+<ul>
+<li>provide alternative perspectives onto a node from a graph,
+ supporting additional functionality particular to that perspective;</li>
+<li>dynamically convert a between perspectives on nodes;</li>
+<li>register implementations of implementation classes that present
+ the node as an alternative perspective.</li>
+</ul>
+<h3 id="terminology">Terminology</h3>
+<p>To assist the following discussion, the key terms are introduced
+first.</p>
+<p>node
+ ~ A subject or object from a triple in the underlying graph
+graph
+ ~ The underlying container of RDF triples that simplifies the
+ previous abstraction Model
+enhanced node
+ ~ An encapsulation of a node that adds additional state or
+ functionality to the interface defined for node. For example, a bag
+ is a resource that contains a number of other resources; an
+ enhanced node encapsulating a bag might provide simplified
+ programmatic access to the members of the bag.
+enhanced graph
+ ~ Just as an enhanced node encapsulates a node and adds extra
+ functionality, an enhanced graph encapsulates an underlying graph
+ and provides additional features. For example, both Model and
+ DAMLModel can be thought of as enhancements to the (deliberately
+ simple) interface to graphs.
+polymorphic
+ ~ An abstract super-class of enhanced graph and enhanced node
+ that exists purely to provide shared implementation.
+personality
+ ~ An abstraction that circumscribes the set of alternative views
+ that are available in a given context. In particular, defines a
+ mapping from types (q.v.) to implementations (q.v.). This seems to
+ be taken to be closed for graphs.
+implementation
+ ~ A factory object that is able to generate polymorphic objects
+ that present a given enhanced node according to a given type. For
+ example, an alt implementation can produce a sub-class of enhanced
+ node that provides accessors for the members of the alt.</p>
+<h4 id="key_points">Key points</h4>
+<p>Some key features of the design are:</p>
+<ul>
+<li>every enhanced graph has a single graph personality, which
+ represents the types of all the enhanced nodes that can be created
+ in this graph;</li>
+<li>every enhanced node refers to that personality</li>
+<li>different kinds of enhanced graph can have different
+ personalities, for example, may implement interfaces in different
+ ways, or not implement some at all.</li>
+<li>enhanced nodes wrap information in the graph, but keep no
+ independant state; they may be discarded and regenerated at whim.</li>
+</ul>
+<h3 id="how_an_enhanced_node_is_created">How an enhanced node is created</h3>
+<h4 id="creation_from_another_enhanced_node">Creation from another enhanced node</h4>
+<p>If <code>en</code> is an enhanced node representing some resource we wish to
+be able to view as being of some (Java) class/interface <code>T</code>, the
+expression <code>en.as(T.class)</code> will either deliver an EnhNode of type
+<code>C</code>, if it is possible to do so, or throw an exception if not.</p>
+<p>To check if the conversion is allowed, without having to catch
+exceptions, the expression <code>en.canAs(T.class)</code> delivers <code>true</code> iff
+the conversion is possible.</p>
+<h4 id="creation_from_a_base_node">Creation from a base node</h4>
+<p>Somehow, some seed enhanced node must be created, otherwise <code>as()</code>
+would have nothing to work on. Subclasses of enhanced node provide
+constructors (perhaps hidden behind factories) which wrap plain
+nodes up in enhanced graphs. Eventually these invoke the
+constructor
+ <code>EnhNode(Node,EnhGraph)</code></p>
+<p>It's up to the constructors for the enhanced node subclasses to
+ensure that they are called with appropriate arguments.</p>
+<h4 id="internal_operation_of_the_conversion">internal operation of the conversion</h4>
+<p><code>as(Class T)</code> is defined on EnhNode to invoke <code>asInternal(T)</code> in
+<code>Polymorphic</code>. If the original enhanced node <code>en</code>is already a valid
+instance of <code>T</code>, it is returned as the result. Validity is checked
+by the method <code>isValue()</code>.</p>
+<p>If <code>en</code> is not already of type <code>T</code>, then a cache of alternative
+views of <code>en</code> is consulted to see if a suitable alternative exists.
+The cache is implemented as a <em>sibling ring</em> of enhanced nodes -
+each enhanced node has a link to its next sibling, and the "last"
+node links back to the "first". This makes it cheap to find
+alternative views if there are not too many of them, and avoids
+caches filling up with dead nodes and having to be flushed.</p>
+<p>If there is no existing suitable enhanced node, the node's
+personality is consulted. The personality maps the desired class
+type to an <code>Implementation</code> object, which is a factory with a
+<code>wrap</code> method which takes a (plain) node and an enhanced graph and
+delivers the new enhanced node after checking that its conditions
+apply. The new enhanced node is then linked into the sibling ring.</p>
+<h3 id="how_to_build_an_enhanced_node__graph">How to build an enhanced node & graph</h3>
+<p>What you have to do to define an enhanced node/graph
+implementation:</p>
+<ol>
+<li>define an interface <code>I</code> for the new enhanced node. (You could
+ use just the implementation class, but we've stuck with the
+ interface, because there might be different implementations)</li>
+<li>define the implementation class <code>C</code>. This is just a front for
+ the enhanced node. All the state of <code>C</code> is reflected in the graph
+ (except for caching; but beware that the graph can change without
+ notice).</li>
+<li>define an <code>Implementation</code> class for the factory. This class
+ defines methods <code>canWrap</code> and <code>wrap</code>, which test a node to see if
+ it is allowed to represent <code>I</code> and construct an implementation of
+ <code>C</code>respectively.</li>
+<li>Arrange that the personality of the graph maps the class of <code>I</code>
+ to the factory. At the moment we do this by using (a copy of) the
+ built-in graph personality as the personality for the enhanced
+ graph.</li>
+</ol>
+<p>For an example, see the code for <code>ReifiedStatementImpl</code>.</p>
+<h2 id="reification_api">Reification API</h2>
+<h3 id="introduction">Introduction</h3>
+<p>This document describes the reification API in Jena2, following
+discussions based on the 0.5a document. The essential decision made
+during that discussion is that reification triples are captured and
+dealt with by the Model transparently and appropriately.</p>
+<h3 id="context">Context</h3>
+<p>The first Jena implementation made some attempt to optimise the
+representation of reification. In particular it tried to avoid so
+called 'triple bloat', <em>ie</em> requiring four triples to represent the
+reification of a statement. The approach taken was to make a
+<em>Statement</em> a subclass of <em>Resource</em> so that properties could be
+directly attached to statement objects.</p>
+<p>There are a number of defects in the Jena 1 approach.</p>
+<ul>
+<li>Not everyone in the team was bought in to the approach</li>
+<li>The <em>.equals()</em> method for <em>Statement</em>s was arguably wrong and
+ also violated the Java requirements on a <em>.equals()</em></li>
+<li>The implied triples of a reification were not present so could
+ not be searched for</li>
+<li>There was confusion between the optimised representation and
+ explicit representation of reification using triples</li>
+<li>The optimisation did not round trip through RDF/XML using the
+ the writers and ARP.</li>
+</ul>
+<p>However, there are some supporters of the approach. They liked:
+- the avoidance of triple bloat
+- that the extra reifications statements are not there to be
+ found on queries or ListStatements and do not affect the <em>size()</em>
+ method.</p>
+<p>Since Jena was first written the RDFCore WG have clarified the
+meaning of a reified statement. Whilst Jena 1 took a reified
+statement to denote a statement, RDFCore have decided that a
+reified statement denotes an occurrence of a statement, otherwise
+called a stating. The Jena 1 <em>.equals()</em> methods for <em>Statement</em>s
+is thus inappropriate for comparing reified statements.
+The goal of reification support in the Jena 2 implementation are:</p>
+<ul>
+<li>to conform to the revised RDF specifications</li>
+<li>to maintain the expections of Jena 1; <em>ie</em> they should still be
+ able to reify everything without worrying about triple bloat if
+ they want to</li>
+<li>as far as is consistent with 2, to not break existing code, or
+ at least make it easy to transition old code to Jena 2.</li>
+<li>to enable round tripping through RDF/XML and other RDF
+ representation langauges</li>
+<li>enable a complete standard compliant implementation, but not
+ necessarily as default</li>
+</ul>
+<h3 id="presentation_api">Presentation API</h3>
+<p><em>Statement</em> will no longer be a subclass of <em>Resource</em>. Thus a
+statement may not be used where a resource is expected. Instead, a
+new interface <em>ReifiedStatement</em> will be defined:</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">ReifiedStatement</span> <span class="n">extends</span> <span class="n">Resource</span>
+ <span class="p">{</span>
+ <span class="n">public</span> <span class="n">Statement</span> <span class="n">getStatement</span><span class="p">();</span>
+ <span class="sr">//</span> <span class="n">could</span> <span class="n">call</span> <span class="n">it</span> <span class="n">a</span> <span class="n">day</span> <span class="n">at</span> <span class="n">that</span> <span class="ow">or</span> <span class="n">could</span> <span class="n">duplicate</span> <span class="n">convenience</span>
+ <span class="sr">//</span> <span class="n">methods</span> <span class="n">from</span> <span class="n">Statement</span><span class="p">,</span> <span class="n">eg</span> <span class="n">getSubject</span><span class="p">(),</span> <span class="n">getInt</span><span class="p">()</span><span class="o">.</span>
+ <span class="o">...</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>The <em>Statement</em> interface will be extended with the following
+methods:
+ public interface Statement
+ ...
+ public ReifiedStatement createReifiedStatement();
+ public ReifiedStatement createReifiedStatement(String URI);
+ /<em> </em>/
+ public boolean isReified();
+ public ReifiedStatement getAnyReifiedStatement();
+ /<em> </em>/
+ public RSIterator listReifiedStatements();
+ /<em> </em>/
+ public void removeAllReifications();
+ ...</p>
+<p><em>RSIterator</em> is a new iterator which returns <em>ReifiedStatement</em>s.
+It is an extension of <em>ResourceIterator</em>.
+The <em>Model</em> interface will be extended with the following methods:</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">Model</span>
+ <span class="o">...</span>
+ <span class="n">public</span> <span class="n">ReifiedStatement</span> <span class="n">createReifiedStatement</span><span class="p">(</span><span class="n">Statement</span> <span class="n">stmt</span><span class="p">);</span>
+ <span class="n">public</span> <span class="n">ReifiedStatement</span> <span class="n">createReifiedStatement</span><span class="p">(</span><span class="n">String</span> <span class="n">URI</span><span class="p">,</span> <span class="n">Statement</span> <span class="n">stmt</span><span class="p">);</span>
+<span class="sr">/* */</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">isReified</span><span class="p">(</span><span class="n">Statement</span> <span class="n">st</span><span class="p">);</span>
+ <span class="n">public</span> <span class="n">ReifiedStatement</span> <span class="n">getAnyReifiedStatement</span><span class="p">(</span><span class="n">Statement</span> <span class="n">stmt</span><span class="p">);</span>
+<span class="sr">/* */</span>
+ <span class="n">public</span> <span class="n">RSIterator</span> <span class="n">listReifiedStatements</span><span class="p">();</span>
+ <span class="n">public</span> <span class="n">RSIterator</span> <span class="n">listReifiedStatements</span><span class="p">(</span><span class="n">Statement</span> <span class="n">stmt</span><span class="p">);</span>
+<span class="sr">/* */</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">removeReifiedStatement</span><span class="p">(</span><span class="n">reifiedStatement</span> <span class="n">rs</span><span class="p">);</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">removeAllReifications</span><span class="p">(</span><span class="n">Statement</span> <span class="n">st</span><span class="p">);</span>
+ <span class="o">...</span>
+</pre></div>
+
+
+<p>The methods in <em>Statement</em> are defined to be the obvious calls of
+methods in <em>Model</em>. The interaction of those models is expressed
+below. Reification operates over statements in the model which use
+predicates <strong>rdf:subject</strong>, <strong>rdf:predicate</strong>, <strong>rdf:object</strong>, and
+<strong>rdf:type</strong> with object <strong>rdf:Statement</strong>.
+<em>statements with those predicates are, by default, invisible</em>. They
+do not appear in calls of <em>listStatements</em>, <em>contains</em>, or uses of
+the <em>Query</em> mechanism. Adding them to the model will not affect
+<em>size()</em>. Models that do not hide reification quads will also be
+available.</p>
+<h3 id="retrieval">Retrieval</h3>
+<p>The <em>Model::as()</em> mechanism will allow the retrieval of reified
+statements.</p>
+<div class="codehilite"><pre><span class="n">someResource</span><span class="o">.</span><span class="n">as</span><span class="p">(</span> <span class="n">ReifiedStatement</span><span class="o">.</span><span class="n">class</span> <span class="p">)</span>
+</pre></div>
+
+
+<p>If <em>someResource</em> has an associated reification quad, then this
+will deliver an instance <em>rs</em> of <em>ReifiedStatement</em> such that
+<em>rs.getStatement()</em> will be the statement <em>rs</em> reifies. Otherwise a
+<em>DoesNotReifyException</em> will be thrown. (Use the predicate
+<em>canAs()</em> to test if the conversion is possible.)
+It does not matter how the quad components have arrived in the
+model; explicitly asserted or by the <em>create</em> mechanisms described
+below. If quad components are removed from the model, existing
+<em>ReifiedStatement</em> objects will continue to function, but
+conversions using <em>as()</em> will fail.</p>
+<h3 id="creation">Creation</h3>
+<p><em>createReifiedStatement(Statement stmt)</em> creates a new
+<em>ReifiedStatement</em> object that reifies <em>stmt</em>; the appropriate
+quads are inserted into the model. The resulting resource is a
+blank node.</p>
+<p><em>createReifiedStatement(String URI, Statement stmt)</em> creates a new
+<em>ReifiedStatement</em> object that reifies <em>stmt</em>; the appropriate
+quads are inserted into the model. The resulting resource is a
+<em>Resource</em> with the URI given.</p>
+<h3 id="equality">Equality</h3>
+<p>Two reified statements are <em>.equals()</em> iff they reify the same
+statement and have <em>.equals()</em> resources. Thus it is possible for
+equal <em>Statement</em>s to have unequal reifications.</p>
+<h3 id="isreified">IsReified</h3>
+<p><em>isReified(Statement st)</em> is true iff in the <em>Model</em> of this
+<em>Statement</em> there is a reification quad for this <em>Statement</em>. It
+does not matter if the quad was inserted piece-by-piece or all at
+once using a <em>create</em> method.</p>
+<h3 id="fetching">Fetching</h3>
+<p><em>getAnyReifiedStatement(Statement st)</em> delivers an existing
+<em>ReifiedStatement</em> object that reifies <em>st</em>, if there is one;
+otherwise it creates a new one. If there are multiple reifications
+for <em>st</em>, it is not specified which one will be returned.</p>
+<h3 id="listing">Listing</h3>
+<p><em>listReifiedStatements()</em> will return an <em>RSIterator</em> which will
+deliver all the reified statements in the model.</p>
+<p><em>listReifiedStatements( Statement st )</em> will return an <em>RSIterator</em>
+which will deliver all the reified statements in the model that
+reifiy <em>st</em>.</p>
+<h3 id="removal">Removal</h3>
+<p><em>removeReifiedStatement(ReifiedStatement rs)</em> will remove the
+reification <em>rs</em> from the model by removing the reification quad.
+Other reified statements with different resources will remain.</p>
+<p><em>removeAllReifications(Statement st)</em> will remove all the
+reifications in this model which reify <em>st</em>.</p>
+<h3 id="input_and_output">Input and output</h3>
+<p>The writers will have access to the complete set of <em>Statement</em>s
+and will be able to write out the quad components.</p>
+<p>The readers need have no special machinery, but it would be
+efficient for them to be able to call <em>createReifiedStatement</em> when
+detecting an reification.</p>
+<h3 id="performance">Performance</h3>
+<p>Jena1's "statements as resources" approach avoided triples bloat by
+not storing the reification quads. How, then, do we avoid triple
+bloat in Jena2?</p>
+<p>The underlying machinery is intended to capture the reification
+quad components and store them in a form optimised for reification.
+In particular, in the case where a statement is completely reified,
+it is expected to store only the implementation representation of
+the <em>Statement</em>.</p>
+<p><em>createReifiedStatement</em> is expected to bypass the construction and
+detection of the quad components, so that in the "usual case" they
+will never come into existance.</p>
+<h2 id="the_reification_spi">The Reification SPI</h2>
+<h3 id="introduction_1">Introduction</h3>
+<p>This document describes the reification SPI, the mechanisms by
+which the Graph family supports the Model API reification
+interface.</p>
+<p>Graphs handle reification at two levels. First, their reifier
+supports requests to reify triples and to search for reifications.
+The reifier is responsible for managing the reification information
+it adds and removes - the graph is not involved.</p>
+<p>Second, a graph may optionally allow all triples added and removed
+through its normal operations (including the bulk update
+interfaces) to be monitored by its reifier. If so, all appropriate
+triples become the property of the reifier - they are no longer
+visible through the graph.</p>
+<p>A graph may also have a reifier that doesn't do any reification.
+This is useful for internal graphs that are not exposed as models.
+So there are three kinds of <code>Graph</code>:</p>
+<p>Graphs that do no reification;
+Graphs that only do explicit reficiation;
+Graphs that do implicit reification.</p>
+<h3 id="graph_operations_for_reification">Graph operations for reification</h3>
+<p>The primary reification operation on graphs is to extract their
+<code>Reifier</code> instance. Handing reification off to a different class
+allows reification to be handled independantly of other Graph
+issues, eg query handling, bulk update.</p>
+<h4 id="graphgetreifier_-_reifier">Graph.getReifier() -> Reifier</h4>
+<p>Returns the <code>Reifier</code> for this <code>Graph</code>. Each graph has a single
+reifier during its lifetime. The reifier object need not be
+allocated until the first call of <code>getReifier()</code>.</p>
+<h3 id="addtriple_deletetriple">add(Triple), delete(Triple)</h3>
+<p>These two operations may defer their triples to the graph's reifier
+using <code>handledAdd(Triple)</code> and <code>handledDelete(Triple)</code>; see below
+for details.</p>
+<h3 id="interface_reifier">Interface Reifier</h3>
+<p>Instances of <code>Reifier</code> handle reification requests from their
+<code>Graph</code> and from the API level code (issues by the API class
+<code>ModelReifier</code>.</p>
+<h4 id="reifiergethiddentriples_-_graph">reifier.getHiddenTriples() -> Graph</h4>
+<p>The reifier may keep reification triples to itself, coded in some
+special way, rather than having them stored in the parent <code>Graph</code>.
+This method exposes those triples as another <code>Graph</code>. This is a
+dynamic graph - it changes as the underlying reifications change.
+However, it is read-only; triples cannot be added to or removed
+from it.
+ The <code>SimpleReifier</code> implementation currently does not implement a
+ dynamic graph. This is a bug that will need fixing.</p>
+<h4 id="reifiergetparentgraph_-_graph">reifier.getParentGraph() -> Graph</h4>
+<p>Get the <code>Graph</code> that this reifier serves; the result is never
+<code>null</code>. (Thus the observable relationship between graphs and
+reifiers is 1-1.)</p>
+<h4 id="class_alreadyreifiedexception">class AlreadyReifiedException</h4>
+<p>This class extends <code>RDFException</code>; it is the exception that may be
+thrown by <code>reifyAs</code>.</p>
+<h3 id="reifierreifyas_triple_t_node_n__-_node">reifier.reifyAs( Triple t, Node n ) -> Node</h3>
+<p>Record the <code>t</code> as reified in the parent <code>Graph</code> by the given <code>n</code>
+and returns <code>n</code>. If <code>n</code> already reifies a different <code>Triple</code>, throw
+a <code>AlreadyReifiedException</code>.
+Calling <code>reifyAs(t,n)</code> is like adding the triples:</p>
+<p><code>n rdf:type ref:Statement</code>
+<code>n rdf:subject t.getSubject()</code>
+<code>n rdf:predicate t.getPredicate()</code>
+<code>n rdf:object t.getObject()</code>
+to the associated Graph; however, it is intended that it is
+efficient in both time and space.</p>
+<h4 id="reifierhastriple_triple_t__-_boolean">reifier.hasTriple( Triple t ) -> boolean</h4>
+<p>Returns true iff some <code>Node n</code> reifies <code>t</code> in this <code>Reifier</code>,
+typically by an unretracted call of <code>reifyAs(t,n)</code>.
+The intended (and actual) use for <code>hasTriple(Triple)</code> is in the
+implementation of <code>isReified(Statement)</code> in <code>Model</code>.</p>
+<h4 id="reifiergettriple_node_n__-_triple">reifier.getTriple( Node n ) -> Triple</h4>
+<p>Get the single <code>Triple</code> associated with <code>n</code>, if there is one. If
+there isn't, return <code>null</code>.
+A node reifies at most one triple. If <code>reifyAs</code>, with its explicit
+check, is bypassed, and extra reification triples are asserted into
+the parent graph, then <code>getTriple()</code> will simply return <code>null</code>.</p>
+<h3 id="reifierallnodes_-_extendediterator">reifier.allNodes() -> ExtendedIterator</h3>
+<p>Returns an (extended) iterator over all the nodes that (still)
+reifiy something in this reifier.
+This is intended for the implementation of <code>listReifiedStatements</code>
+in <code>Model</code>.</p>
+<h4 id="reifierallnodes_triple_t__-_closableiterator">reifier.allNodes( Triple t ) -> ClosableIterator</h4>
+<p>Returns an iterator over all the nodes that (still) reify the
+triple _t_.</p>
+<h3 id="reifierremove_node_n_triple_t_">reifier.remove( Node n, Triple t )</h3>
+<p>Remove the association between <code>n</code> and the triple<code>t</code>. Subsequently,
+<code>hasNode(n)</code> will return false and <code>getTriple(n)</code> will return
+<code>null</code>.
+This method is used to implement <code>removeReification(Statement)</code> in
+<code>Model</code>.</p>
+<h4 id="reifierremove_triple_t_">reifier.remove( Triple t )</h4>
+<p>Remove all the associations between any node <code>n</code> and <code>t</code>; ie, for
+all <code>n</code> do <code>remove(n,t)</code>.
+This method is used to implement <code>removeAllReifications</code> in
+<code>Model</code>.</p>
+<h4 id="handledadd_triple_t__-_boolean">handledAdd( Triple t ) -> boolean</h4>
+<p>A graph doing reification may choose to monitor the triples being
+added to it and have the reifier handle reification triples. In
+this case, the graph's <code>add(t)</code> should call <code>handledAdd(t)</code> and
+only proceed with its add if the result is <code>false</code>.
+A graph that does not use <code>handledAdd()</code> [and <code>handledDelete()</code>]
+can only use the explict reification supplied by its reifier.</p>
+<h4 id="handledremove_triple_t_">handledRemove( Triple t )</h4>
+<p>As for <code>handledAdd(t)</code>, but applied to <code>delete</code>.</p>
+<h3 id="simplereifier">SimpleReifier</h3>
+<p><code>SimpleReifier</code> is an implementation of <code>Reifier</code> suitable for
+in-memory <code>Graph</code>s built over <code>GraphBase</code>. It operates in either of
+two modes: with and without triple interception. With interception
+enabled, reification triples fed to (or removed from) its parent
+graph are captured using <code>handledAdd()</code> and <code>handledRemove</code>;
+otherwise they are ignored and the graph must store them itself.
+<code>SimpleReifier</code> keeps a map from nodes to the reification
+information about that node. Nodes which have no reification
+information (most of them, in the usual case) do not appear in the
+map at all.</p>
+<p>Nodes with partial or excessive reification information are
+associated with <code>Fragments</code>. A <code>Fragments</code> for a node <code>n</code> records
+separately</p>
+<p>the <code>S</code>s of all <code>n ref:subject S</code> triples
+the <code>P</code>s of all <code>n ref:predicate P</code> triples
+the <code>O</code>s of all <code>n ref:subject O</code> triples
+the <code>T</code>s of all <code>n ref:type T[Statement]</code> triples
+If the <code>Fragments</code> becomes <em>singular</em>, ie each of these sets
+contains exactly one element, then <code>n</code> represents a reification of
+the triple <code>(S, P, O)</code>, and the <code>Fragments</code> object is replaced by
+that triple.
+(If another reification triple for <code>n</code> arrives, then the triple is
+re-exploded into <code>Fragments</code>.)</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 Jena, Jena, the Apache Jena project logo,
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>