You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by ij...@apache.org on 2011/09/13 01:39:35 UTC
svn commit: r1169979 [1/2] - in /incubator/jena/site/trunk:
content/jena/documentation/notes/ templates/
Author: ijd
Date: Mon Sep 12 23:39:35 2011
New Revision: 1169979
URL: http://svn.apache.org/viewvc?rev=1169979&view=rev
Log:
Import of how-to's from old Jena documentation. Some editing applied, still needs a clean-up pass
Added:
incubator/jena/site/trunk/content/jena/documentation/notes/
incubator/jena/site/trunk/content/jena/documentation/notes/concurrency-howto.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/event-handler-howto.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/file-manager.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/index.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/model-factory.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/rdf-frames.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/reification.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/schemagen.mdtext
incubator/jena/site/trunk/content/jena/documentation/notes/typed-literals.mdtext
Modified:
incubator/jena/site/trunk/templates/sidenav.mdtext
Added: incubator/jena/site/trunk/content/jena/documentation/notes/concurrency-howto.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/concurrency-howto.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/concurrency-howto.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/concurrency-howto.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,115 @@
+Title: Concurrent access to Models
+
+Applications need to be aware of the concurrency issues in access
+Jena models. API operations are not thread safe by default. Thread
+safety would simple ensure that the model data-structures remained
+intact but would not give an application consistent access to the
+RDF graph. It would also limit the throughput of multi-threaded
+applications on multiprocessor machines where true concurrency can
+lead to a reduction in response time.
+
+For example, supposed an application wishes to read the name and
+age of a person from model. This takes two API calls. It is more
+convenient to be able to read that information in a consistent
+fashion, knowing that the access to the second piece of information
+is not being done after some model change has occurred.
+
+Special care is needed with iterators. In general, Jena's
+iterators do *not* take a copy to enable safe use in the presence
+of concurrent update. A multi-threaded application needs to be
+aware of these issues and correctly use the mechanisms that Jena
+provides (or manage its own concurrency itself). While not zero,
+the application burden is not high.
+
+There are two main cases:
+
+- Multiple threads in the same JVM.
+- Multiple applications accessing the same persistent model
+ (typically, a database).
+
+Transactions are provided by database-backed models: see the
+[database documentation TODO](../DB/index.html) and the
+[Model interface to transactions TODO](../javadoc/com/hp/hpl/jena/rdf/model/Model.html#supportsTransactions()).
+
+This note describes the support for same-JVM, multi-threaded
+applications.
+
+## Locks
+
+Locks provide critical section support for managing the
+interactions of multiple threads in the same JVM. Jena provides
+multiple-reader/single-writer concurrency support (MRSW).
+
+The pattern general is:
+
+ Model model = . . . ;
+ model.enterCriticalSection(Lock.READ) ; // or Lock.WRITE
+ try {
+ ... perform actions on the model ...
+ ... obey contract - no update operations if a read lock
+ } finally {
+ model.leaveCriticalSection() ;
+ }
+
+Applications are expected to obey the lock contract, that is, they
+must not do update operations if they have a read lock as there can
+be other application threads reading the model concurrently.
+
+## Iterators
+
+Care must be taken with iterators: unless otherwise stated, all
+iterators must be assumed to be iterating over the data-structures
+in the model or graph implementation itself. It is not possible to
+safely pass these out of critical sections.
+
+## SPARQL Query
+
+SPARQL query results are iterators and no different from other
+iterators in Jena for concurrency purposes. The default query
+engine does not give thread safety and the normal requirements on
+an application to ensure MRSW access in the presence of iterators
+applies. Note that Jena's query mechanism is itself multi-threaded.
+If the application is single threaded, no extra work is necessary.Â
+If the application is multi-threaded, queries should be executed
+with a read lock.
+
+Outline:
+
+ Model model = ... ;
+ String queryString = " .... " ;
+ Query query = QueryFactory.create(queryString) ;
+ model.enterCriticalSection(Lock.READ) ;
+ try {
+ QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
+ ResultSet results = qexec.execSelect() ;
+ try {
+ for ( ; results.hasNext() ; )
+ {
+ QuerySolution soln = results.nextSolution() ;
+ RDFNode x = soln.get("..var name..") ;
+ }
+ } finally { qexec.close() ; }
+ } finally { model.leaveCriticalSection() ; }
+
+Updates to the model should not be performed inside the read-only
+section. For database-backed models, the application can use a
+transaction. For in-memory models, the application should collect
+the changes together during the query processing then making all
+the changes holding a write lock.
+
+Jena Locks do not provide lock promotion - an application can not
+start a "write" critical section while holding a "read" lock
+because this can lead to deadlock.
+
+## Compatibility
+
+The actually interface is called `Lock` and has implementations
+including `LockMRSW`.
+
+For compatibility with previous versions of Jena, there is a class
+`ModelLock`.
+
+Â
+
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/notes/event-handler-howto.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/event-handler-howto.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/event-handler-howto.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/event-handler-howto.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,135 @@
+Title: Event handling in Jena
+
+## ModelChangedListener
+
+In Jena it is possible to monitor a `Model` for changes, so that
+code can be run after changes are applied without the coding for
+that Model having to do anything special. We call these changes
+"events". This first
+design and implementation is open for user comment and we may
+refine or reduce the implementation as more experience is gained with
+it.
+
+To monitor a Model, you must *register* a *ModelChangedListener*
+with that Model:
+ Model m = ModelFactory.createDefaultModel();
+ ModelChangedListener L = new MyListener();
+ m.register( L );
+
+*MyListener* must be an implementation of *ModelChangedListener*,
+for example:
+ class MyListener implements ModelChangedListener
+ {
+ public void addedStatement( Statement s )
+ { System.out.println( ">> added statement " + s ); }
+ public void addedStatements( Statement [] statements ) {}
+ public void addedStatements( List statements ) {}
+ public void addedStatements( StmtIterator statements ) {}
+ public void addedStatements( Model m ) {}
+ public void removedStatement( Statement s ) {}
+ public void removedStatements( Statement [] statements ) {}
+ public void removedStatements( List statements ) {}
+ public void removedStatements( StmtIterator statements ) {}
+ public void removedStatements( Model m ) {}
+ }
+
+This listener ignores everything except the addition of single
+statements to *m*; those it prints out. The listener has a method
+for each of the ways that statements can be added to a Model:
+- as a single statement, Model::add(Statement)
+- as an element of an array of statements,
+ Model::add(Statement[])
+- as an element of a list of statements, Model::add(List)
+- as an iterator over statements, Model::add(StmtIterator)
+- as part of another Model, Model::add(Model)
+
+(Similarly for *delete*.)
+
+The listener method is called when the statement(s) have been added
+to the Model, if no exceptions have been thrown. It does not matter
+if the statement was *already* in the Model or not; it is the act
+of adding it that fires the listener.
+
+There is no guarantee that the statement, array, list, or model
+that is added or removed is the same one that is passed to the
+appropriate listener method, and the *StmtIterator* will never be
+the same one. However, in the current design:
+
+- a single Statement will be .equals to the original Statement
+- a List will be .equals to the original List
+- a Statement[] will be the same length and have .equal elements
+ in the same order
+- a StmtIterator will deliver .equal elements in the same order
+- a Model will contain the same statements
+
+We advise not relying on these ordering properties; instead assume
+that for any bulk update operation on the model, the listener will
+be told the method of update and the statements added or removed,
+but that the order may be different and duplicate statements may
+have been removed.
+Note in particular that a Model with any Listeners will have to
+record the complete contents of any *StmtIterator* that is added or
+removed to the model, so that the Model and the Listener can both
+see all the statements.
+
+Finally, there is no guarantee that *only* Statements etc added
+through the Model API will be presented to the listener; any
+Triples added to its underlying Graph will also be presented to the
+listener as statements.
+
+## Utility classes
+
+The full Listener API is rather chunky and it can be inconvenient
+to use, especially for the creation of inline classes. There are
+four utility classes in *com.hp.hpl.jena.rdf.listeners:*
+- *NullListener*. This class's methods do nothing. This is useful
+ when you want to subclass and intercept only specific ways of
+ updating a Model.
+- *ChangedListener*. This class only records whether some change
+ has been made, but not what it is. The method *hasChanged()*
+ returns *true* if some change has been made since the last call of
+ *hasChanged()* [or since the listener was created].
+- *StatementListener*. This class translates all bulk update
+ calls (ie the ones other than *addedStatement()* and
+ *removedStatement()*) into calls to
+ *addedStatement()/removedStatement()* for each Statement in the
+ collection. This allows statements to be tracked whether they are
+ added one at a time or in bulk.
+- *ObjectListener*. This class translates all the listener calls
+ into *added(Object)* or *removed(Object)* as appropriate; it is
+ left to the user code to distinguish among the types of argument.
+
+## When listeners are called
+
+In the current implementation, listener methods are called
+immediately the additions or removals are made, in the same thread
+as the one making the update. If a model has multiple listeners
+registered, the order in which they are informed about an update is
+unspecified and may change from update to update. If any listener
+throws an exception, that exception is thrown through the update
+call, and other listeners may not be informed of the update.
+Hence listener code should be brief and exception-free if at all
+possible.
+
+## Registering and unregistering
+
+A listener may be registered with the same model multiple times. If
+so, it will be invoked as many times as it is registered for each
+update event on the model.
+
+A listener *L* may be *unregistered* from a Model using the method
+`unregister(L)`. If *L* is not registered with the model, nothing
+happens.
+
+If a listener is registered multiple times with the same model,
+each `unregister()` for that listener will remove just one of the
+registrations.
+
+## Transactions and databases
+
+In the current design, listeners are not informed of transaction
+boundaries, and all events are fed to listeners as soon as they
+happen.
+In the current implementation, if an RDB model *M* is modified by
+some other client of the database, those changes are not seen and
+thus are not reported to listeners.
Added: incubator/jena/site/trunk/content/jena/documentation/notes/file-manager.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/file-manager.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/file-manager.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/file-manager.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,122 @@
+Title: The Jena FileManager and LocationMapper
+
+The FileManager is a utility to find and read files into models.
+There is a standard global FileManager and applications may also
+define specific ones by constructing addition FileManagers.
+
+The LocationMapper provides alternative locations for RDF data.
+
+## The File Manager
+
+Files are named by a string, according to the conventions of their
+storage system. Typically this is by URI. There are a number of
+storage system adapters provided:
+
+- File locator (with own current directory)
+- URL locator
+- Class loader locator
+- Zip file locator
+
+The global file manager has a file location, a URL locator and a
+class loader (tried in that order).
+A FileManager can have an associated LocationMapper that transforms
+names before use. This means local copies of documents can be used
+transparently to the rest of the application.
+
+There are two categories of operations: loadModel, readModel. Load
+operations fetch and parse the data into a new memory model. Read
+operations fetch and parse the data into an existing model. For
+more complex ways to create a new model see
+[the Assembler documentation](../assembler/index.html).
+
+Each FileManager has an optional in-memory cache of models. When
+on, loading models will look in the cache first and return a cached
+model if possible. This cached model is not copied - updates *will*
+change the cached version. The default is that cache is off.
+
+In fetching and parsing a file, the file manager will attempt to
+guess the serialization format, if not explicitly supplied. This is
+by name extension:
+
+- `.rdf` and `.owl` : RDF/XML
+- `.n3` : N3
+- `.nt` : N-Triples
+- Anything else: RDF/XML
+
+## The LocationMapper configuration file
+
+This example uses the RDF subset of
+[N3](http://www.w3.org/2000/10/swap/Primer). Jena has an RDF reader
+and RDF writer for N3. This is nearly the same as
+[Turtle](http://www.ilrt.bris.ac.uk/discovery/2004/01/turtle/) but
+allowing international characters and some restrictions due to N3.
+
+Location mapping files are RDF - they may be written in RDF/XML, N3
+(file suffix `.n3`) or N-Triples (file suffix `.nt`). The default
+is RDF/XML unless one of these suffices is found.
+
+ @prefix lm: <http://jena.hpl.hp.com/2004/08/location-mapping#>
+
+ [] lm:mapping
+ [ lm:name "file:foo.n3" ; lm:altName "file:etc/foo.n3" ] ,
+ [ lm:prefix "file:etc/" ; lm:altPrefix "file:ETC/" ] ,
+ [ lm:name "file:etc/foo.n3" ; lm:altName "file:DIR/foo.n3" ]
+ .
+
+There are two types of location mapping: exact match renaming and
+prefix renaming. When trying to find an alternative location, a
+LocationMapper first tries for an exact match; if none is found,
+the LocationMapper will search for the longest matching prefix. If
+two are the same length, there is no guarantee on order tried;
+there is no implied order in a location mapper configuration file
+(it sets up two hash tables).
+
+In the example above, `file:etc/foo.n3` becomes `file:DIR/foo.n3`
+because that is an exact match. The prefix match of file:/etc/ is
+ignored.
+
+All string tests are done case sensitively because the primary use
+is for URLs.
+
+Notes:
+
+- Property values are not URIs, but strings. This is a system
+ feature, not an RDF feature. Prefix mapping is name rewriting;
+ alternate names are not treated as equivalent resources in the rest
+ of Jena. While application writers are encouraged to use URIs to
+ identify files, this is not always possible.
+- There is no check to see if the alternative system resource is
+ equivalent to the original.
+
+A LocationMapper finds its configuration file by looking for the
+following files, in order:
+
+- `file:location-mapping.rdf`
+- `file:location-mapping.n3`
+- `file:etc/location-mapping.rdf`
+- `file:etc/location-mapping.n3`
+
+This is a specified as a path - note the path separator is always
+the character ';' regardless of operating system because URLs
+contain ':'.
+
+Applications can also set mappings programmatically. No
+configuration file is necessary.
+
+The base URI for reading models with the FileManager will be the
+original URI, not the alternative location.
+
+### Debugging
+
+Using log4j, set the logging level of the classes:
+ com.hp.hpl.jena.util.FileManager=ALL
+ com.hp.hpl.jena.util.LocationManager=ALL
+
+### See also
+
+Javadoc:
+[FileManager TODO](../javadoc/com/hp/hpl/jena/util/FileManager.html)
+[LocationMapper TODO](../javadoc/com/hp/hpl/jena/util/LocationMapper.html)
+
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/notes/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/index.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/index.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/index.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,4 @@
+Title: General notes and how-to's
+
+- [Concurrency how-to](concurrency-howto.mdtext) Handling concurrent access to Jena models
+- [Event handler how-to](event-handler-howto.mdtext) Responding to events
Added: incubator/jena/site/trunk/content/jena/documentation/notes/model-factory.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/model-factory.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/model-factory.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/model-factory.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,260 @@
+Title: Creating Jena models
+
+## Introduction
+
+Jena is a moderately complicated system, with several
+different kinds of `Model` and ways of constructing them. This note
+describes the Jena `ModelFactory`, a one-stop shop for
+creating Jena models. `ModelFactory` lives in Java package
+`com.hp.hpl.jena.rdf.model`.
+Most of `ModelFactory` methods have been around for a while now,
+but Jena 2.5's ModelFactory contains methods that use the
+`Assembler` API which appeared in Jena.4, which allows models to
+be created according to RDF descriptions that can be
+programmatically constructed or read in from external resources
+such as configuration files. (This API replaces the old `ModelSpec`
+API, which had proved unsatisfactory.)
+
+This note is an introduction, not an exhaustive description. As
+usual consult the Javadoc for details of the methods and classes to
+use.
+
+## Simple model creation
+
+The simplest way to create a model (if not the shortest) is to call
+`ModelFactory.createDefaultModel()`. This [by default] delivers a
+plain RDF model, stored in-memory, that does no inference and has
+no special ontology interface.
+
+## ModelMakers
+
+Plain models can be given names which allows them to be "saved" and
+looked up by name later. This is handled by implementations of the
+interface `ModelMaker`; each `ModelMaker` produces Models of the
+same kind. The simplest kind of `ModelMaker` is a memory model
+maker, which you get by calling
+`ModelFactory.createMemModelMaker()`. The methods you'd want to use
+to start with on a ModelMaker are:
+
+- `createModel(String)`: create a model with the given name in the
+ModelMaker. If a model with that name already exists, then that
+model is used instead.
+
+- `openModel(String)`: open an existing model with the given name. If
+no such model exists, create a new empty one and give it that name.
+[createModel(String) and openModel(String) behave in the same way,
+but each has a two-argument form for which the behaviour is
+different. Use whichever one best fits your intention.]
+
+- `createModel()`: create a fresh anonymous model.
+
+- `getModel()`: each `ModelMaker` has a *default model*; this method
+returns that model.
+
+There are other methods, for removing models, additional control
+over create *vs* open, closing the maker, and looking names up; for
+those consult the
+[ModelMaker javadoc TODO ](../javadoc/com/hp/hpl/jena/rdf/model/ModelMaker.html).
+
+### File-based models
+
+The method `ModelFactory.createFileModelMaker(String)` returns a
+`ModelMaker` which attaches models to filing-system files. The
+`String` argument is the *fileBase*. When a file-ModelMaker opens a
+file, it reads it from a file in the directory named by the
+fileBase; when the model is closed (and *only* then, in the current
+implementation), the contents of the model are written back to the
+file.
+
+Because the names of models in a modelMaker can be arbitrary
+character strings, in particular URIs, they are translated slightly
+to avoid confusion with significant characters of common filing
+systems. In the current implementation,
+
+- colon : is converted to \\_C
+- slash \/ is converted to \\_S
+- underbar \_ is converted to \\_U
+
+## Reification styles
+
+Jena models have different *reification styles*, which are
+described in more detail in the
+[reification howto](reification.html). `ModelFactory` provides
+constants for those styles:
+
+- `ModelFactory.Standard`
+- `ModelFactory.Convenient`
+- `ModelFactory.Minimal`
+
+And methods corresponding to those already discussed:
+
+- `ModelFactory.createDefaultModel(style)` creates a default model
+with the specified reification style.
+
+- `ModelFactory.createMemModelMaker(style)` creates a ModelMaker that
+creates memory models with the specified reification style.
+
+- `ModelFactory.createFileModelMaker(root,style)`
+creates a ModelMaker that creates file-associated models with the
+specified reification style.
+
+Reification styles also appear in other Modelfactory methods,
+although they are not required. We shall not discuss them further
+in this document; consult the Javadoc for appropriate details.
+
+## Database model creation
+
+Jena allows models to be created within databases. For an extensive
+discussion of the available options and controls, see the
+[database howto documents](../DB/index.html). The current
+ModelFactory interface only provides simple access to database
+model creation.
+ModelFactory creation of models takes place through RDB
+ModelMakers:
+
+- `createModelRDBMaker(IDBConnection c)`
+
+delivers a ModelMaker that makes (or finds) models by name in the
+Jena model database attached to the connection `c`. Models from an
+RDB maker are "just like" memory-based models, except that they can
+be much larger, are likely to be significantly slower, and persist
+over application termination.
+The connection can be created in two ways:
+
+- `ModelFactory.createSimpleRDBConnection(url,user,pass,type)`:
+creates a connection to the database with the given JDBC url, the
+given user and password, and the database type.
+
+- `ModelFactory.createSimpleRDBConnection()`: creates a connection to
+the database, taking the URL from the system property
+**jena.db.url**, the user name from **jena.db.user**, the password
+from **jena.db.password**, and the database type from
+**jena.db.type**.
+
+Details of these fields can be found in the database documentation,
+as well as direct ways to construct connections if required, and
+additional operations on RDB Models that may be useful.
+
+## Inference model creation
+
+An important feature of Jena is support for different kinds of
+inference over RDF-based models (used for RDFS, OWL, and DAML).
+Inference models are constructed by applying *reasoners* to
+*base models* and optionally *schema*. The statements deduced by
+the reasoner from the base model then appear in the inferred model
+alongside the statements from the base model itself.
+RDFS reasoning is directly available:
+
+- `createRDFSModel(Model base)` creates an inference model over the
+base model using the built-in RDFS inference rules and any RDFS
+statements in the base model.
+
+- `createRDFSModel(Model schema, Model base)` creates an RDFS
+inference model from the base model and the supplied schema model.
+The advantage of supplying the schema separately is that the
+reasoner may be able to compute useful information in advance on
+the assumption that the schema won't change, or at least not change
+as often as the base model.
+
+It's possible to use other reasoning systems than RDFS. For these a
+Reasoner is required:
+
+- `createInfModel(Reasoner reasoner, Model base)` creates an
+inference model using the rules of `reasoner` over the model
+`base`.
+
+- `createInfModel(Reasoner reasoner, Model schema, Model base)` Just
+as for the RDFS case, the schema may be supplied separately to
+allow the reasoner to digest them before working on the model.
+
+From where do you fetch your reasoners? From the
+*reasoner registry*, the class
+[ReasonerRegistry TODO](../javadoc/com/hp/hpl/jena/reasoner/ReasonerRegistry.html).
+This allows reasoners to be looked up by name, but also provides
+some predefined access methods for well-know reasoners:
+
+- `getOWLReasoner()`: the reasoner used for OWL inference
+
+- `getRDFSReasoner()`: the reasoner used for RDFS inference
+
+- `getTransitiveReasoner()`: a reasoner for doing subclass and
+sub-property closure.
+
+## Ontology model creation
+
+An *ontology model* is one that presents RDF as an ontology -
+classes, individuals, different kinds of properties, and so forth.
+Jena supports RDFS, OWL, and DAML ontologies through *profiles*.
+There is extensive documentation on
+[Jena's ontology support](../ontology/index.html), so all we'll do
+here is summarise the creation methods.
+
+- `createOntologyModel()` Creates an ontology model which is
+in-memory and presents OWL ontologies.
+
+- `createOntologyModel(OntModelSpec spec, Model base)` Creates an
+ontology model according the
+[OntModelSpec TODO](../javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html)
+`spec` which presents the ontology of `base`.
+
+- `createOntologyModel(OntModelSpec spec, ModelMaker maker, Model base)`
+Creates an OWL ontology model according to the `spec` over the
+`base` model. If the ontology model needs to construct additional
+models (for OWL imports), use the `ModelMaker` to create them. [The
+previous method will construct a `MemModelMaker` for this.]
+
+Where do `OntModelSpec`s come from? There's a cluster of
+constants in the class which provide for common uses; to name but
+three:
+- `OntModelSpec.OWL_MEM_RDFS_INF` OWL ontologies, model stored in
+memory, using RDFS entailment only
+
+- `OntModelSpec.RDFS_MEM` RDFS ontologies, in memory, but doing no
+additional inferences
+
+- `OntModelSpec.OWL_DL_MEM_RULE_INF` OWL ontologies, in memory, with
+the full OWL Lite inference
+
+## Creating models from Assembler descriptions
+
+A new feature of Jena since Jena 2.4 is the use of
+*assembler descriptions*, documented in the
+[assembler howto](../assembler/assembler-howto.html). Access to the
+assembler system for model creation is provided by three
+ModelFactory methods:
+
+- `assembleModelFrom( Model singleRoot )`: assemble a Model from the
+single Model description in `singleRoot`. If there is no such
+description, or more than one, an exception is thrown. If a
+description has to be selected from more than one available
+candidates, consider using the methods below.
+
+- `findAssemblerRoots( Model m )`: answer a Set of all the Resources
+in `m` which are of type `ja:Model`, ie descriptions of models to
+assemble. (Note that this will include sub-descriptions of embedded
+models if they are present.)
+
+- `assembleModelFrom( Resource root )`: answer a Model assembled
+according to the description hanging from `root`.
+Assemblers can construct other things as well as models, and the
+Assembler system is user-extensible: see the howto for details.
+
+## Miscellany
+
+Finally, `ModelFactory` contains a collection of methods for some
+special cases not conveniently dealt with elsewhere.
+
+- `createModelForGraph(Graph g)` is used when an advanced user with
+access to the Jena SPI has constructed or obtained a `Graph` and
+wishes to present it as a model. This method wraps the graph up as
+a plain model. Alterations to the graph are visible in the model,
+and *vice versa*.
+
+- `withHiddenStatements(Model)` returns a new Model in which any
+reification quadlets (see the reification howto) that may be hidden
+in the base model are exposed in the result. It may return the base
+model, if it does not hide quadlets. This is useful if you want to
+see all the statements of the model as they will appear in a
+serialisation.
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/notes/rdf-frames.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/rdf-frames.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/rdf-frames.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/rdf-frames.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,274 @@
+Title: Presenting RDF as frames
+
+The origins of RDF as a representation language include
+*frame languages*, in which an object, or frame, was the main unit
+of structuring data. Frames have *slots*, for example a `Person`
+frame might have an `age` slot, a `height`slot etc. RDF, however,
+has taken a step beyond frame languages by making `rdf:Property` a
+first class value, not an element of a frame or resource *per se*.
+In RDF, for example, an age property can be defined:
+`<rdf:Property rdf:ID="age">`, and then applied to any resource,
+including, but not limited to a `Person` resource.
+
+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 `rdfs:domain` 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:
+
+ <rdfs:Class rdf:ID="Person" />
+ <rdfs:Class rdf:ID="Truck" />
+ <rdf:Property rdf:ID="age">
+ <rdfs:domain rdf:resource="Person" />
+ </rdf:Property>
+
+ <Truck rdf:ID="truck1">
+ <age>2</a>
+ </Truck>
+
+Whereas many object-oriented or frame-oriented representations
+would regard it as an error that the `age` property was not being
+applied to a `Person`, RDF-based applications are simply entitled
+to infer that `truck1` is a (that is, has `rdf:type`) `Truck` as
+well as a `Person`. This is unlikely to be the case in any
+real-world domain, but it is a valid RDF inference.
+
+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 *C*?". 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.
+
+## Basic principles: the properties of a class
+
+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:
+
+ <rdfs:Class rdf:ID="Person" />
+ <rdf:Property rdf:ID="age" />
+
+ <Person rdf:ID="jane_doe">
+ <age>23</a>
+ </Person>
+
+Now consider that we add to this fragment that:
+
+ <rdf:Property rdf:about="age">
+ <rdfs:domain rdf:resource="Person" />
+ </rdf:Property>
+
+This additional information about the domain of the `age` property
+does not add any new entailments to the model. Why? Because we
+already know that `jane_doe` is a Person. So we can consider `age`
+to be one of the properties of `Person` type resources, because if
+we use the property as a predicate of that resource, it doesn't add
+any new `rdf:type` information about the resource. Conversely, if
+we know that some resource has an `age`, we don't learn any new
+information by declaring that it has `rdf:type Person`. In summary,
+for the purposes of this HOWTO we define the
+*properties of a class* 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.
+
+## Sub-classes, and more complex class expressions
+
+Given these basic principles, now consider the following RDF
+fragment:
+
+ <rdfs:Class rdf:ID="LivingThing" />
+
+ <rdfs:Class rdf:ID="Animal">
+ <rdfs:subClassOf rdf:resource="#LivingThing">
+ </rdfs:Class>
+
+ <rdfs:Class rdf:ID="Mammal">
+ <rdfs:subClassOf rdf:resource="#Animal">
+ </rdfs:Class>
+
+ <rdf:Property rdf:ID="hasSkeleton">
+ <rdfs:domain rdf:resource="Animal" />
+ </rdf:Property>
+
+Is `hasSkeleton` one of the properties of `Animal`? Yes, because
+any resource of `rdf:type Animal` can have a `hasSkeleton` property
+(with value either true or false) without adding type information.
+Similarly, any resource that is a `Mammal` also has
+`rdf:type Animal` (by the sub-class relation), so `hasSkeleton` is
+a property of `Mammal`. However, `hasSkeleton` is *not* a property
+of `LivingThing`, since we don't automatically know that a living
+thing is an animal - it may be a plant. Stating that a given
+`LivingThing` has a `hasSkeleton` property, even if the value is
+false, would entail the additional `rdf:type` statement that the
+`LivingThing` is also an `Animal`.
+
+For more complex class expressions in the domain, we look to see
+what simple domain constraints are entailed. For example, a domain
+constraint `AÂ â©Â B` (i.e. "A intersection B") for property `p`
+entails that both `p rdfs:domain A` and `p rdfs:domain B` are true.
+However, the properties of neither `A` nor `B` will include `p`. To
+see this, suppose we have a resource `x` that we already know is of
+type `A`, and a statement `x p y`. This entails `x rdf:type A`
+which we already know, but also `x rdf:type B`. So information is
+added, even if we know that `x` is an instance `A`, so `p` is not a
+property of `A`. The symmetrical argument holds for `p` not being a
+property of `B`.
+
+However, if the domain of `p` is `A âªÂ B` (i.e. "A union B"), then
+both `A` and `B` will have `p` as a property, since an occurrence
+of, say `x p y` does not allow us to conclude that either
+`x rdf:type A` or `x rdf:type B`.
+
+## Property hierarchies
+
+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 `Animal` and `Mammal` include both `hasSkeleton` and
+`hasEndoSkeleton`:
+
+ <rdf:Property rdf:ID="hasSkeleton">
+ <rdfs:domain rdf:resource="Animal" />
+ </rdf:Property>
+
+ <rdf:Property rdf:ID="hasEndoSkeleton">
+ <rdfs:subPropertyOf rdf:resource="#hasSkeleton" />
+ </rdf:Property>
+
+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.
+
+## Global properties
+
+Under the principled definition that we propose here, properties
+which do not express a domain value are *global*, 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 `rdfs:Resource` or `owl:Thing`, 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.
+
+A commonly used idiom in some OWL ontologies is to use
+*Restrictions* 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 `Person` should have a
+`familyName` property:
+
+ <owl:Class rdf:ID="Person">
+ <rdfs:subClassOf>
+ <owl:Restriction>
+ <owl:onProperty rdf:resource="#familyName" />
+ <owl:minCardinality rdf:datatype="&xsd;int">1</owl:minCardinality>
+ </owl:Restriction>
+ </rdfs:subClassOf>
+ </owl:Class>
+
+This approach shows the intent of the ontology designer that
+`Person` instances have `familyName` properties. We do regard
+`familyName` as one of the *properties of* `Person`, but only
+because of the global properties principle. Unless a domain
+constraint is also specified for `familyName`, it will appear as
+one of the properties of classes other than `Person`.
+**Note that this is a behaviour change from versions of Jena prior to release 2.2**.
+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.
+
+## The Java API
+
+Support for frame-like views of classes and properties is provided
+through the [ontology API](../ontology/index.html). The following
+methods are used to access the properties of a class, and the
+converse for properties:
+
+ OntClass.listDeclaredProperties();
+ OntClass.listDeclaredProperties( boolean direct );
+ OntClass.hasDeclaredProperty( Property prop, boolean direct );
+ OntProperty.listDeclaringClasses();
+ OntProperty.listDeclaringClasses( boolean direct );
+
+All of the above API methods return a Jena
+[`ExtendedIterator`](../javadoc/com/hp/hpl/jena/util/iterator/ExtendedIterator.html).
+
+**Note a change from the Jena 2.1 interface:** the optional Boolean
+parameter on `listDeclaredProperties` has changed name from `all`
+(Jena 2.1 and earlier) to `direct` (Jena 2.2 and later). The
+meaning of the parameter has also changed: `all` was intended to
+simulate some reasoning steps in the absence of a reasoner, whereas
+`direct` is used to restrict the associations to only the local
+associations. See more on
+[direct associations](../ontology/index.html#direct_relationships).
+
+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:
+
+ <rdfs:Class rdf:ID="A" />
+ <rdfs:Property rdf:ID="p">
+ <rdfs:domain rdf:resource="#A" />
+ </rdfs:Property>
+ <rdfs:Property rdf:ID="q">
+ <rdfs:subPropertyOf rdf:resource="#p" />
+ </rdfs:Property>
+
+ 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();
+
+Iterator `i1` will return `p` and `q`, while `i0` will return only
+`p`.
+
+## Summary of changes from Jena 2.2-beta-2 and older
+
+For users updating code that uses `listDeclaredProperties` from
+versions of Jena prior to 2.2-final, the following changes should
+be noted:
+
+- Global properties
+ `listDeclaredProperties` will treat properties with no specified
+ domain as global, and regard them as properties of all classes. The
+ use of the `direct` flag can hide global properties from non-root
+ classes.
+- Restriction properties
+ `listDeclaredProperties` no longer heuristically returns properties
+ associated with a class via the `owl:onProperty` predicate of a
+ restriction.
+- Limited simulated inference
+ The old version of `listDeclaredProperties` attempted to simulate
+ the entailed associations between classes and properties. Users are
+ now advised to attach a reasoner to their models to do this.
+- Change in parameter semantics
+ The old version of `listDeclaredProperties(boolean all)` 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 `listDeclaredProperties(boolean direct)`, where
+ calling the method with `direct = true` will compress the returned
+ results to use only the
+ [direct](../ontology/index.html#direct_relationships)
+ associations.
+
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/notes/reification.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/reification.mdtext?rev=1169979&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/reification.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/reification.mdtext Mon Sep 12 23:39:35 2011
@@ -0,0 +1,191 @@
+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
+details.
+
+Reification in RDF and Jena is the ability to treat a `Statement`
+as a `Resource`, and hence to make assertions *about* that
+statement. A statement may be reified as many different resources,
+allowing different manifestations ("statings") of that statement to
+be treated differently if required.
+
+RDF represents a reified statement as four statements with
+particular RDF properties and objects: the statement `(S, P, O)`,
+reified by resource `R`, is represented by:
+
+- `R rdf:type rdf:Statement`
+- `R rdf:subject S`
+- `R rdf:predicate P`
+- `R rdf:object O`
+
+We shall call these four such statements a *reification quad* and
+the components *quadlets*. Users of reification in Jena may, by
+default, simply manipulate reified statements as these quads.
+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.
+
+The interface `ReifiedStatement` is used to represent a reified
+statement as a Jena `Resource` that has direct access to the
+statement it reifies. The method
+
+- `ReifiedStatement::getStatement()`
+
+returns the `Statement` that the resource is reifying. All the
+other `Resource` methods, of course, may be applied to a
+`ReifiedStatement`.
+
+## Converting resources to reified statements
+
+If a resource `R` is associated with a reified statement, but might
+not itself be a `ReifiedStatement` object, the conversion method
+`RDFNode::as(Class)` can be used to find (or create) a
+`ReifiedStatement`:
+- `(ReifiedStatement) R.as(ReifiedStatement.class)`
+
+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.
+
+If there is no such associated reified statement, a
+`CannotReifyException` is thrown. To find out in advance if the
+conversion is possible, use the predicate
+`RDFNode::canAs(ReifiedStatement.class)`. (Jena only counts as "an
+associated reified statement" a resource with exactly one
+`rdf:subject`, `rdf:predicate`, and `rdf:object` which has
+`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
+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
+`Statement` is reified in *that* model; there is no test to see if
+a `Statement` is reified in any other models.
+
+## Listing reified statements
+
+Just as `listStatements` 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 `RSIterator` object, which is an
+iterator each of who's elements are `ReifiedStatement`s and for
+which the convenience method `nextRS()` will deliver a
+suitably-cast reified statement.
+- `Statement::listReifiedStatements()` - all the reifications of
+ this statement in its model.
+- `Model::listReifiedStatements()` - all the reified statements
+ in this model.
+- `Model::listReifiedStatements(Statement s)` - all the reified
+ statements reifiying `s` in this model.
+
+## 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
+`Statement`s using one of the methods:
+- `Statement::createReifiedStatement()`
+- `Statement::createReifiedStatement(String)`
+- `Model::createReifiedStatement(Statement)`
+- `Model::createReifiedStatement(String,Statement)`
+
+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
+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`.
+
+The additional method `Model::getAnyReifiedStatement(Statement)`
+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
+`Statement` in some `Model`:
+- `Statement::removeReification()`
+- `Model::removeAllReifications(Statement)`
+
+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
+- `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.
+
+