ModelSpec howto - describing models in RDF

introduction

This note briefly describes a new, experimental feature of Jena 2: the ability to specify models in RDF. The intention is to be able to specify how a model is constructed using a configuration file, input stream, URL, or other way of getting RDF into a Jena process.

A more formal document is available: the ModelSpec design document. Here we concentrate on how to use ModelSpecs in general.

creating a ModelSpec

ModelSpecs are created by calling the ModelFactory method createSpec(desc), passing it the Model containing the RDF description. The description uses the JMS (Jena Model Specification) vocabulary. The result is a ModelSpec object specialised to the description. createSpec finds the unique resource in desc with RDF.type JMS.ModelSpec, and then find the "most specific" subtype of JMS.ModelSpec that resource has. [Fortunately, the current type tree allows this.]

That type identifies the kind of Java ModelSpec to create. The constructor for that type analyses the description to find the relevant properties: irrelevant ones are ignored. [The mapping from RDF types to ModelSpecCreators is driven from the ModelSpecCreatorRegistry and is extensible.]

The createSpec(Resource,Model) method performs the same function, but the ModelSpec resource (which must have type JMS.ModelSpec) is passed as the first argument, rather than being the unique ModelSpec resource in the description.

In both cases, the Model can be replaced by a [non-bnode] Resource whose URI names the model to be loaded.

using a ModelSpec

ModelSpecs can be used to create models, and they can regenerate their descriptions. The full set of methods is described in ModelSpec's javadoc, but the three directly useful to users are:

createModel(): create a new model according to the specification. This method is used by ModelFactory.createModel(ModelSpec).
createModelOver(String name): most ModelSpecs have an underlying ModelMaker. This method creates a new Model where any underlying Model has the given name in that ModelMaker. For particularly simple ModelSpecs, the result is that Model.
getDescription(): returns an RDF description which describes this ModelSpec. If the original RDF description had no superfluous statements, this model is likely "the same" as that original, ie isomorphic. This is a useful way to save an RDF description to be used in a later createSpec.

Some simple ModelSpec descriptions

In these descriptions, we write triples one per line, using the Jena standard prefixes and _A, _B etc being bnodes. The root subject of the description we call _this. Your own descriptions can use whatever named resources and bnodes you like.

PlainModelSpec, no frills

A PlainModelSpec is described by a ModelMaker specification. For a memory-based model, that just describes a reification mode.

    _this jms:maker _A
    _A jms:reificationMode jms:rsMinimal

The ModelSpec construction uses RDFS reasoning over the supplied model, so that using jms:maker is sufficient to say that _this is a jms:ModelSpec.

PlainModelSpec, file-based

A FileModelMaker needs a fileBase to be specified as well.

    _this jms:maker _A
    _A jms:reificationMode jms:rsConvenient
    _A jms:fileBase "/tmp"

The resulting PlainModelSpec makes models backed by files found in "/tmp" (file-system names are implementation-specific).

PlainModelSpec from a database

Database model makers need to have their connection specified. Each such ModelSpec will create its own connection.

    _this jms:maker _A
    _A jms:reificationMode jms:rsStandard
    _A jms:dbURL "jdbc:mysql://some.database.machine.eg/jenaDB"
    _A jms:dbUser "william.blake"
    _A jms:dbPassword "tyger, tyger"
    _A jms:dbType "MySQL"

an inference model

Inference models require a reasoner specification as well as a base ModelMaker. In the current ModelSpec implementation, the reasoner only requires the URI describing the necessary inference: other reasoner properties will be introduced in later revisions.

    _this jms:maker _M
    _this jms:reasonsWith _R
    _M jms:reificationMode jms:rsMinimal
    _R jms:reasoner http://jena.hpl.hp.com/2003/RDFSExptRuleReasoner

an ontology model

Finally, here's the description of an ontology model for OWL Lite over a database model, while doing RDFS inference.

    _this jms:importMaker _D
    _this jms:ontLanguage "http://www.w3.org/TR/owl-features/#term_OWLLite"
    _this jms:docManager _DM
    _this jms:reasonsWith _R
    
    _D jms:dbURL "jdbc:mysql://some.database.machine.eg/jenaDB"
    _D jms:dbUser "william.blake"
    _D jms:dbPassword "tyger, tyger"
    _D jms:dbType "MySQL"    

    _R jms:reasoner http://jena.hpl.hp.com/2003/RDFSExptRuleReasoner

The docManager bnode has no attached properties; in this case, the resulting OntModelSpec will use the default document manager. Adding the triple

    _DM jms:policyPath "file:/somehere/policy"

will use a document manager which takes its policy from the specified file; see the OntDSocumentManager documentation for more details.