Jena 2.5.5

Provides the core interfaces through which datatypes are described to Jena. Instances of RDFDatatype describe serialization, parsing and equality-testing functions for a single Datatype. The TypeMapper provides a user-extensible registry through which datatype definitions can be registered against URIs. It is prepopulated with XML datatype definitions.

Provides datatype definitions for the XML Schema datatypes support by Jena. This allows XSD typed literal to be used in RDF data. The static fields on the class XSDDatatype provide instances of each of the datatype definitions but these are preregistered with the TypeMapper.

This package includes code adapated from Xerces 2.6.0, which is maked and is Copyright (c) 1999-2002 The Apache Software Foundation. All rights reserved.

Provides implementations of the XSD datatype. These implementations are currently just thin wrappers onto a set of internal classes defined by Xerces. This does make Jena reliant on the Xerces version and alternative implementations may be explored in the future.

A general database backend for persistent storage of Jena models. This Jena2 release runs on three database engines, MySQL, Oracle, PostgreSQL on two platforms, Linux and WindowsXP. The Jena2 persistence subsystem is largely compatible with Jena1 but does not support the various Jena1 layouts. Existing Jena1 databases cannot be accessed by Jena2 and must be reloaded.

For details on creating and accessing persistent models, see doc/DB/howto.html. For details on options for configuring and accessing persistent models see the doc/DB/options.html. For particulars on persistent models for the various database engines, see doc/DB/mysql-howto.html, doc/DB/oracle-howto.html,doc/DB/postgresql-howto.html.

Note that the recommended mechanism for creating and opening persistent models has changed from Jena1 and also from the preliminary releases of Jena2. Previous mechanisms are now deprecated and users are encouraged to use the new factory mechanisms. See doc/how-to/model-factory.html for details.

Jena N3 Parser, RDF Reader and Writer

This package contains

• an N3 parser
• a Jena reader, for reading the RDF subset of N3 into a Model
• a Jena writer for outputting RDF in an N3 syntax.

The N3 writer is aimed at producing readable N3 and analysies the model before writing.  It may unsuitable for some forms of very large model.

This package does not contains a rules engine to interprete or execute N3 formulae.  It is not a replacement for cwm; this system aims to provide daat input fo RDF in N3 format.

The Parser

The N3 parser provided parses the whole of the N3 language.  It is a streaming parser that emits parser events (see the class N3ParserEventHandler) when a new triple is encountered.

It is a permissive parser, it does not aim to validate an N3 and mioght even parse some constructs which are not valid (examples include named formulae and named DAML lists;  the generated parser events do not expressive the named objects).  It does not check the characters comprising URIs and is more permissive on qnames that strict defintion would require.

The parser is built using antlr. The grammar file is "n3.g".  An application will need access to the antlr runtime classes which are provided in antlr.jar in the Jena lib/ directory.

There is a simple application in jena.n3 that accesses the N3 parser directly or via the RDF generator for file conversion or for simple file checking.

The RDF generator

The RDF generator takes a stream of parser events and turns them into additions to a Jena model.  The Jena reader is then a class that wraps up this functionality to conform to the Jena reader interface.  The RDF generator does not allow formulae and will cause an error if one is encountered.

Performance

The parser alone runs at about 18K triples/second on Pentium4 750Mhz PC (it is I/O bound in the lexer).  When generating RDF, the rate is about 9K statements/second.

Notes

N3 files are UTF-8: not raw bytes or ISO-8859-1.  Applications should pass UTF-8 character set readers and writers to the appropriate Jena operations model.read and model.write.  Often, this does not make a difference but can cause silent loss or change of character information.

Other Information on N3

• http://www.w3.org/2000/10/swap/doc/cwm
• http://www.w3.org/DesignIssues/Notation3.html
• http://infomesh.net/2002/notation3/
• http://notabug.com/2002/n3/
• http://www.agfa.com/w3c/euler

Acknowledgements

The grammar was not written from scratch.  The grammar is based on cwm, Dan Connerly's python grammar and Graham Klyne's N3Parser as well as "Notation3 : A Rough Guide" which lists other parsers.

Provides a set of abstractions and convenience classes for accessing and manipluating ontologies represented in RDF. The two prevalent ontology languages based on RDF are OWL and DAML+OIL. Since these two languages are similar, this package attempts to present a common set of abstractions, parameterised by vocabularies fot the different languages.

Note: this package primarily seeks to provide easy programmatic access to the terms in the ontologies. The ontology languages have well-defined semantics that provide entailment rules for triples not directly asserted by the ontology. By and large, an inference engine is needed to access these entailed triples, for which several options and an open architecture are provided elsewhere in Jena.

Provides default implementations for the abstractions defined in the com.hp.hpl.jena.ontology package.

Unit test cases for classes at general ontology layer (i.e. language independent features).

A parser for RDF/XML.

See the ARP documentation and the I/O mini howto for more information.

Language support for RDF.

A package defining some useful implementations of ModelChangedListener, for listening to (a) all triples added or removed, exploding composite objects, (b) all objects added or removed, as themselves, (c) notification of additions/removals, but no details, and (d) accepting but ignoring all changes, as a base-class to be extended.

A package for creating and manipulating RDF graphs.

The Jena2 reasoner subsystem is designed to allow a range of inference engines to be plugged into Jena. Such reasoners are primarily used to derive additional RDF assertions which are entailed from some base RDF together with any optional ontology information and the axioms and rules associated with the reasoner. In addition, they can be used to test global properties of an RDF graph such as consistency.

This machinery, and the rest of this description, are appropriate for developers working with Graphs and Nodes at the SPI level. Application developers using Models should see the convenience methods built into ModelFactory.

Each available reasoner is represented by an factory object which is an instance of a ReasonerFactory. It is also given a URI through which it can be identified. This URI is used both as the base of a set of RDF assertions which describe the reasoner capabilitiesand as an identifier for registering the reasoner with a central registry. If you only need to access a specific built-in reasoner you can use the factory class directly or the convenience methods built into ModelFactory [TODO: ref]. However, if you need to dynamically check what reasoners are registered with the Jena2 installation and examine their capabilities use the machinery in ReasonerRegistry.

Once you have an appropriate factory you can create a reasoner instance. The instance can then be bound to a set of RDF data for processing. The result of such binding is an InfGraph , this is a specialization of the standard Graph interface - all the RDF assertions entailed from the base data via the reasoner appear as "virtual" triples within this InfGraph. Some additional methods on InfGraph offer access to the reasoner, the raw data and some additional capabilities.

For example, using the SPI all of the steps involved in generated an RDFS closure of a graph are:

  ReasonerFactory rf = RDFSReasonerFactory.theInstance();
  Reasoner reasoner  = rf.create(null);
  InfGraph graph     = reasoner.bindSchema(tbox) // optional
                               .bind(data);
  Model model        = new ModelMem(graph);

For application developers working with the API then this code is accessible through the convenience methods in ModelFactory.

If the resulting graph or model are queried using find/listStatements they contain the sum of all the assertions in the tbox graph, the data graph and the triples entailed from them via RDF+RDFS entailment.

The ability to separately bind rule or ontology information (tbox in the example) and raw assertional information (data in the example) is optional. Some reasoners may require a strict separation of terminology and instance data, others may allow both binds but be lax about the allowed contents of each, others may not support the bindSchema stage.

The existing built-in reasoners allow a single tbox together with a single data bind but the tbox is optional and unrestricted. In the case of the RDFSReasoner in the example, some work is done at bindSchema time to cache information on property and class lattices that may be reused across multiple data sets but the extent of that reuse is lessened if the data graph also contains such schema assertions.

All RDFS implementations need to make tradeoffs. This implementation is intended to be complete (it can cope with metadata level declarations such as declaring and using a subPropertyOf rdfs:subPropertyOf). It requires all schema information to be loadable into main memory - the property and class lattices are stored reasonably efficiently but they will often be the limiting factor on size (and certainly on performance). These lattices are processed at the time the reasoner is bound to the schema and instance data. However, the rest of the RDFS inference rules will operate in a backwards chaining mode so that significant processing will be required to answer a given query. Highly ground queries will operate reasonably efficiently, queries with wildcards in predicate slot will operate particularly inefficiently and will make redundant passes across the data.

Implementation notes

The subClassOf and subPropertyOf relationships are cached in memory using the TransitiveReasoner. This stores those relationships as explicit graphs containing the full relationship closure. The direct links are represented by direct versions of the subClassOf and subPropertyOf relations which can be constructed using ReasonerFactory#makeDirect or found as class variables on the TransitiveReasoner.

The schema rules such as domain, range and subPropertyOf inference are also checked at the time the data is bound but the result is the addition of a set of backward chaining rewrite rules which can match a given query against possible inferences.  For example the domain rule is:

   ?p rdfs:domain ?z -> ?s rdf:type ?z <- ?s ?p _

Thus the processing of a (p,domain,z) declaration generates a backward rule of the form "if you are looking for something of type z then check if there is any individual which is the subject of a p property.

All of these backward rules are implemented using the Graph iterators together with some simple triple rewrite machinery.

One special case to be aware of is the processing of container membership property entailments. By default the reasoner does a scan of the entire tbox+data looking for properties of the form rdf:_n and for each one found it asserts the appropriate entailments. This involves a pass over the whole dataset (we take the opportunity to cache all [p,type, Property] and [p, subPropertyOf,p] entailments at the same time). This behaviour can be switched off using the configuration option [TODO: document] which considerably reduces to the initial processing time but [x,type,containerMembershipProperty] and [x,subPropertyOf,member] entailments will then be missed. This may or may not be a useful trade-off depending on the application.

Provides a selection of simple rule engines for Jena inference models. Currently this includes a simple forward chaining engine (BasicForwardRuleReasoner). This is currently a pure interpreter (no RETE network) with an extensible set of Builtin actions (see Builtin).

We include two example reasoners built using this rule engine. The first is an alternative RDFS implementation (RDFSRuleReasonerFactory) which implements the full RDFS rule set forward style.

The second is an implementation of the OWL-lite subset of OWL-full (OWLRuleReasonerFactory). This omits some of the RDFS entailments (everything is a Resource, every Class is a subclass of Resource) because those conclusions are general not that useful and lead to rather a lot of pointless deductions in forward chaining mode.

Implementations of the Builtin class which provides primitive operations to the rule engines. The current set is small - just enought to implement OWL and demonstrate the principle of Builtin's - not comprehensive.

Internal implementation objects used by the rule system interpreters and compilers. Note that the class in here are not intended for general use. In particular, they are primarily stucts rather than correctly encasulated objects (i.e. they access each other's fields directly in some cases, instead of indirectly through accessor methods).

Contains code which has been obsoleted by new versions of the rule engines but which is being retained temporarily during the transition phase. In particular it contains the components of the original tabled backward chaining engine that have been replaced by the LP (SLG-WAM style) engine.

Provides testing support for the rule engines.

The generated InfGraph will appear to contain the union of the data graph, the tbox graph, the reflexive-transitive closure of any subPropertyOf and subClassOf relations together with direct versions of these.

Defects

The current implementation is flawed in its handling of multiple data bindings - you can't actually reuse the work of tbox binding across different data sets. This will be fixed soon.

Miscellaneous collection of utility classes.

A package for defining useful iterators and iterator operations, including concatenation, mapping, filtering, empty and singleton iterators, iterator wrappers, and the ExtendedIterator class used in many places in Jena.

A package containing constant classes with predefined constant objects for classes and properties defined in well known vocabularies.

Writing RDF/XML.

A package for some Jena command-line programs, including

• copying RDF data with representation conversion, eg XML to N3
• comparing two RDF files for isomorphism (extended equality)
• an interface to the ARP RDF parser
• access to the RDQL interpreter
• a schema-to-Java generator