svn commit: r1425911 - in /jena/site/trunk/content/documentation/notes: reification.mdtext reification_previous.mdtext

[an...@apache.org]

Author: andy
Date: Wed Dec 26 14:10:11 2012
New Revision: 1425911

URL: http://svn.apache.org/viewvc?rev=1425911&view=rev
Log:
Updated reification documentation for fixed 'standard' style (v2.10.0)

Added:
    jena/site/trunk/content/documentation/notes/reification_previous.mdtext
Modified:
    jena/site/trunk/content/documentation/notes/reification.mdtext

Modified: jena/site/trunk/content/documentation/notes/reification.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/notes/reification.mdtext?rev=1425911&r1=1425910&r2=1425911&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/notes/reification.mdtext (original)
+++ jena/site/trunk/content/documentation/notes/reification.mdtext Wed Dec 26 14:10:11 2012
@@ -1,13 +1,9 @@
-Title: Reification howto
+Title: Reification HowTo
 
 ## Introduction
 
-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
+This document describes the Jena APi support for reification.
+it.  As always, consult the Javadoc for interface
 details.
 
 Reification in RDF and Jena is the ability to treat a `Statement`
@@ -31,9 +27,7 @@ default, simply manipulate reified state
 However, just as for `Bag`, `Seq`, `Alt` and `RDF lists` in
 ordinary models, or ontology classes and individuals in
 `OntModel`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.
+statements. 
 
 The interface `ReifiedStatement` is used to represent a reified
 statement as a Jena `Resource` that has direct access to the
@@ -67,15 +61,10 @@ associated reified statement" a resource
 `rdf:type rdf:Statement`. It can of course have *other*
 properties.)
 
-Once the `ReifiedStatement` has been constructed, it retains its
-`Statement` 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.
-
 ## Testing statements for reification
 
 You may wish to know if some `Statement` is reified. The methods
-`Statement::isReified()` and `Model::isreified(Statement)` return
+`Statement::isReified()` and `Model::isReified(Statement)` return
 true if (and only if) the statement has been reified in the model.
 Note that the `Statement` method tests to see if the statement is
 reified in its own model, and the model method tests to see if the
@@ -99,8 +88,8 @@ suitably-cast reified statement.
 
 ## Creating reified statements directly
 
-You do not have to create reified statements by asserting their
-quads into a `Model`; they can be created directly from their
+You do not have to create reified statements by asserting the
+quad into a `Model`; they can be created directly from their
 `Statement`s using one of the methods:
 -   `Statement::createReifiedStatement()`
 -   `Statement::createReifiedStatement(String)`
@@ -109,12 +98,13 @@ quads into a `Model`; they can be create
 
 Each of these returns a `ReifiedStatement` who's `getStatement()`
 method delivers the original statement (actually, a `.equals()`
-statement; it may not be the identical statement). If the creation
+statement; it may not be the identical statement object). If the creation
 method passed in a (non-null) `String`, the `ReifiedStatement` is a
 named resource and that string is its URI. Otherwise it is a
 newly-minted bnode. The methods on `Statement` create a reified
 statement in that statements model; those on `Model` 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 `AlreadyReifiedException`.
@@ -123,18 +113,6 @@ The additional method `Model::getAnyReif
 returns some reification of the supplied `Statement`; an existing
 one if possible, otherwise a fresh one (reified by a fresh bnode).
 
-## Reification and Model::add(Model)
-
-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)
-
-If `suppress` is `true`, 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.)
-
 ## Removing reified statements
 
 There are two methods which remove all the reifications of a
@@ -147,45 +125,10 @@ statement are removed, whatever their re
 a particular reified statement only, use
 -   `Model::removeReification(ReifiedStatement)`
 
-Similarly to `Model::add(Model)`, the method
-`model.remove(Model m)` will remove all the reified statements of
-`m` from `model`, and the two-argument form `model.remove(m,true)`
-will not.
-
 ## Reification styles
 
-By default and as you might expect, Jena models allow reification
-quads to be manifested as `ReifiedStatement`s. Similarly,
-explicitly created `ReifiedStatement`s are visible as statement
-quads.
-
-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 `listStatements()` will be
-quadlets; this is inefficient and confusing. One choice is to reify
-the statements in a *different* model. Another is to take advantage
-of *reification styles*.
-
-Each model has a reification style, described by constants in
-`ModelFactory`. The default style is called `Standard` because it
-behaves mostly closely to the RDF standard. There are two other
-reification styles to choose from:
-
--   `Convenient`: reification quadlets are not visible in the
-    results of `listStatements)()`. Otherwise everything is normal;
-    quadlets that are added to the model contribute to
-    `ReifiedStatement` construction.
--   `Minimal`: reification quadlets play no role at all in the
-    construction of `ReifiedStatement`s, which can only be created by
-    the methods discussed earlier. This style is most similar to that
-    of Jena 1.
-
-The method `ModelFactory.createDefaultModel()` takes an optional
-`Style` argument, which defaults to `Standard`. Similarly,
-`createFileModelMaker()` and `createMemModelMaker()` can take
-`Style` arguments which are applied to every model they create.
-To take a model with hidden reification quads and expose them as
-statements, the method `ModelFactory.withHiddenStatements(Model m)`
-produces a new model which does just that.
-
+Prior to version 2.10.0 of Jena, there were 3 styles of reificiation, 
+"standard", "minimal" and "convenient".  As of 2.10.0 and later, only 
+what was prviosuly the "standard" style is supported.
 
+The old documentation is [still available](reificiation_previous.html).

Added: jena/site/trunk/content/documentation/notes/reification_previous.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/notes/reification_previous.mdtext?rev=1425911&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/notes/reification_previous.mdtext (added)
+++ jena/site/trunk/content/documentation/notes/reification_previous.mdtext Wed Dec 26 14:10:11 2012
@@ -0,0 +1,41 @@
+Title: Reification styles (archive material)
+
+## Reification styles
+
+Prior to version 2.10.0 of Jena, there were 3 styles of reificiation, 
+"standard", "minimal" and "convenient".  As of 2.10.0 and later, only 
+what was prviosuly the "standard" style is supported.
+
+By default and as you might expect, Jena models allow reification
+quads to be manifested as `ReifiedStatement`s. Similarly,
+explicitly created `ReifiedStatement`s are visible as statement
+quads.
+
+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 `listStatements()` will be
+quadlets; this is inefficient and confusing. One choice is to reify
+the statements in a *different* model. Another is to take advantage
+of *reification styles*.
+
+Each model has a reification style, described by constants in
+`ModelFactory`. The default style is called `Standard` because it
+behaves mostly closely to the RDF standard. There are two other
+reification styles to choose from:
+
+-   `Convenient`: reification quadlets are not visible in the
+    results of `listStatements)()`. Otherwise everything is normal;
+    quadlets that are added to the model contribute to
+    `ReifiedStatement` construction.
+-   `Minimal`: reification quadlets play no role at all in the
+    construction of `ReifiedStatement`s, which can only be created by
+    the methods discussed earlier. This style is most similar to that
+    of Jena 1.
+
+The method `ModelFactory.createDefaultModel()` takes an optional
+`Style` argument, which defaults to `Standard`. Similarly,
+`createFileModelMaker()` and `createMemModelMaker()` can take
+`Style` arguments which are applied to every model they create.
+To take a model with hidden reification quads and expose them as
+statements, the method `ModelFactory.withHiddenStatements(Model m)`
+produces a new model which does just that.