This document describes how to use the Assembler classes to construct models
-- and other things -- from RDF descriptions that use the
Jena Assembler vocabulary. That vocabulary is available in
ja-vocabulary.n3 as an RDFS schema
with conventional prefix ja for the URI
http://jena.hpl.hp.com/2005/11/Assembler#;
the class JA is its Jena Java rendition.
The examples used in this document are extracted from the examples file examples.n3. The pieces of RDF/OWL schema are extracted from the ja-vocabulary file and can be viewed as N3 or in a condensed notation of the form:
class ClassName [subClassOf SuperClasses] domainOf PropertyName [withRange RangeClasses] [Cardinality] ...
The property names selected are those which are the "declared
properties" (as per Jena's listDeclaredProperties
method) of the class. Only the most specialised superclasses and
rangeclasses are shown, so (for example) rdf:Resource
typically won't appear.
An Assembler specification is a Resource in some RDF Model. The properties of that Resource describe what kind of object is to be assembled and what its components are: for example, an InfModel is constructed by specifying a base model and a reasoner. The specifications for the components are themselves Assembler specifications given by other Resources in the same Model.For example, to specify a memory model with data loaded from a file:
The rdf:type of eg:model specifies that the constructed Model is to be a Jena memory-based model. The ja:content property specifies that the model is to be loaded with the content of the resource file:Data/example.n3. The content handler guesses from the ".n3" suffix that this file is to be read using the Jena N3 reader.
Unless otherwise specified by an application, Assembler specifications are interpreted after adding in the JA schema and doing (limited) RDFS inference. In the example above, eg:model has to be given an explicit type, but the externalContent bnode is implicitly typed by the domain of ja:externalContent. In this document, we will usually leave out inferrable types.
We can construct our example model from the specification like this (you may need to tweak the filename to make this work in your environment):
Model spec = FileManager.get().loadModel( "examples.n3" ); Resource root = spec.createResource( spec.expandPrefix( "eg:opening-example" ) ); Model m = Assembler.general.openModel( root );
The model is constructed from the "root resource",
eg:opening-example in our example. general
knows how to create all the kinds of objects -- not just Models --
that we describe in the next sections.
Assembler specifications can describe many kinds of models: memory, inference, database, ontology, and file-backed. All of these model specifications share a set of base properties for attaching content, prefix mappings, and reification modes.
All of a model's ja:content property values are
interpreted as specifying Content objects and a single
composite Content object is constructed and used
to initialise the model.
See Content for the description of Content
specifications. For example:
The model constructed for eg:A will be loaded with the
contents of Data/A.n3, Data/B.rdf,
and http://somewhere/RDF/ont.owl. If the model supports
transactions, then the content is loaded inside a transaction; if the
load fails, the transaction is aborted, and a
TransactionAbortedException thrown.
If the content has any prefix mappings, then they are also added
to the model.
All of a model's ja:includes, ja:prefix,
and ja:namespace properties are
interpreted as specifying a PrefixMapping object and
a single composite PrefixMapping is constructed and used
to set the prefixes of the model.
See PrefixMapping for the description of Content
specifications.
A model may have a single ja:reificationMode
property whose value must be one of the constants ja:standard,
ja:convenient, or ja:minimal. The
model's reification mode is set accordingly, if possible.
A ja:Content specification may have zero or more
ja:externalContent property values. These are URI
resources naming an external (file or http etc) RDF object.
The constructed Content object contains the union of the values of
all such resources. For example:
The string literal value of the any ja:literalContent
properties is interpreted as RDF in an appropriate language. The constructed
Content object contains that RDF. The language is either specified by an
explicit ja:contentEncoding property value, or guessed from
the content of the string. The only encodings permitted are "N3" and "RDF/XML".
For example:
The literal content is wrapped so that prefix declarations for rdf, rdfs, owl, dc, and xsd apply before interpretation.
The property values of any ja:quotedContent properties
should be resources. The subgraphs rooted at those resources (using the
algorithm from ResourceUtils.reachableClosure()) are added
to the content.
The description of an RDB model requires its name and a description of the JDBC connection for the database the model is in. For example:
ja:RDBModel is a subclass of ja:NamedModel
and shares the ja:ModelName property value naming the model
within the database.
The mandatory unique property value of ja:connection
specifies the connection to the database to be used.
The description of a connection requires the database name and type
and the user name and password. If the username and password are not
specified, Assembler.general will default them, normally
to the values of the system properties jena.dbUser and
jena.dbPassword.
The ja:dbURL property value specifies the
URL of the database to be connected to. If it is ommitted, the
ja:dbURLProperty value is the name of a Java system
property whose value is the URL of the database.
The ja:dbType property value
specifies the type of the database as a string. If it is omitted, the
ja:dbTypeProperty value is the name of a Java
system property whose value is the database type.
The unique ja:dbUser property value is a string
literal whose value is the name of the user connecting to the
database. If it is omitted, the value of the ja:dbUserProperty
is the name of a Java system property containing the user name.
The unique ja:dbPassword property value is the
password of the user connecting to the database. If it is omitted,
the value of the ja:dbPasswordProperty is the name
of a Java system property whose value is the password.
A FileModel specification builds a memory model that is backed by a file. By "backed", we mean that the model is loaded from that file and written back to the file when (if) it is closed. Furthermore, the model (weakly) supports transactions.
Here, the model is read from (and written to) the file /tmp/simple.
Directory names are given as resources (not literals) and of course file names
are system dependant -- this is what one might see on a Unix system. If the
directory name is to be shared by several different FileModels, it can be useful
to give it a namespace prefix so that it can be changed in one place as
necessary.
Model names can be mapped to allow them to be URIs without the
/s in URIs being taken as directory separators. Here, the base file name
will be FileModels/http_C_S_Ssomewhere.org_Sstuff.n3. The
encoding is not pretty, but is sufficient for simple URIs.
The ja:directory property specifies the directory in which the
model file is located. The ja:modelName property specifies the name of
the file within that directory.
The optional unique property ja:fileEncoding has as its value
a string which is the name of the encoding language of the model (ie one of
RDF/XML or N3, etc). If it is omitted, the language is guessed from the suffix
of the filename (as per FileUtils.guessLang()).
If the optional unique property ja:mapName has the value
ja:true, then the name of the model is mapped by replacing
any _, /, or : characters by the escape sequences __, _S, or _C. This
translation (which is the same one done by FileGraphMaker for
FileModelMaker) allows URIs to be used as model names without
conflicting with the filesystems use of / characters.
Inference models are specified by supplying a description of the reasoner that is used by the model and (optionally) a base model to reason over. For example:
describes an inference model that uses RDFS reasoning. The
reasonerURL property value is the URI used to identify the
reasoner (it is the value of the Jena constant
RDFSRuleReasonerFactory.URI). The base model is
specified as a memory model; if it is left out, an empty memory
model is used. Of course, you can specify a database model as a base
model:
The same reasoner as used as in the previous example, but now the base model is a database specified in the same way as our earlier example.
Because Jena's access to external reasoners goes through the same API as for its internal reasoners, you can access a DIG reasoner (such as Pellet running as a server) using an Assembler specification:
The internal rule reasoner can be supplied with rules written inside the specification, or outside from some resource (file or http: URL):
An InfModel's ja:baseModel property value specifies
the base model for the inference model; if omitted, an empty memory model is
used.
An InfModel's ja:ReasonerFactory property value specifies
the Reasoner for this inference model; if omitted, a GenericRuleReasoner
is used.
A Reasoner's optional ja:schema property
specifies a Model which contains the schema for the reasoner to
be bound to. If omitted, no schema is used.
If the Reasoner is a GenericRuleReasoner, it may have any of the
RuleSet properties ja:rules, ja:rulesFrom,
or ja:rule. The rules of the implied RuleSet
are added to the Reasoner.
A RuleSet specification allows rules (for ReasonerFactories)
to be specified inline, elsewhere in the specification model, or in an external
resource.
The optional repeatable property ja:rule has as its value
a literal string which is the text of a Jena rule or rules. All those rules
are added to the RuleSet.
The optional repeatable property ja:rulesFrom has as its value
a resource whose URI identifies a file or other external entity that can be
loaded as Jena rules. All those rules are added to the RuleSet.
The optional repeatable property ja:rules has as its value
a resource which identifies another RuleSet in the specification model.
All those rules from that RuleSet are added to this RuleSet.
Ontology models can be specified in several ways. The simplest is to use the name of an OntModelSpec from the Java OntModelSpec class:
This constructs an OntModel with an empty base model
and using the OWL_DL language and the full rule reasoner. All of the
OntModelSpec constants in the Jena implementation are available in this way.
A base model can be specified:
The OntModel has a base which is a memory model loaded with the contents
of http://jena.hpl.hp.com/some-jena-data.rdf. Since the ontModelSpec
was omitted, it defaults to OWL_MEM_RDFS_INF - the same default
as ModelFactory.createOntologyModel().
OntModel is a subclass of InfModel, and the
ja:baseModel property means the same thing.
The OntModelSpec property value is a resource. If that
resource has any properties in the specification model, it is interpreted
as an OntModelSpec description;
otherwise the local name of the value is interpreted as the name of an
OntModelSpec constant (looked up by reflection).
An OntModelSpec has several possible properties.
ja:importSource:
The value of this optional unique property is a ModelSource
description which describes where imports are obtained from. A ModelSource
my be of class ja:ModelSource, for which memory models are constructed,
or a ja:RDBModelSource with a ja:connection property,
for which models are constructed in the specified database.
ja:documentManager:
This value of this optional unique property is a DocumentManager specification.
If absent, the default document manager is used.
ja:reasonerURL:
The value of this optional unique property is the URL of the ReasonerFactory
to be used to construct this OntModelSpec's reasoner.
ja:ontLanguage:
The value of this optional unique property is one of the values in the
ProfileRegistry class which identifies the ontology language
of this OntModelSpec:
An OntDocumentManager can be specified by a
ja:DocumentManager specification which describes the
OntDocumentManager's file manager and policy settings.
In this example, eg:document-manager-example is a
ja:DocumentManager specification. It has its own
FileManager specification, the object of the
ja:fileManager property; that FileManager
has a location mapper, eg:mapper, that maps a single
filename.
The document manager also has an additional property to link it to
document manager meta-data: the sub-model of the assembler specification
reachable from eg:document-manager-example is passed to
the document manager when it is created. For the meanings of the
dm: properties, see the Jena ontology documentation and
the ontology.rdf ontology.
The ja:fileManager property value, if present, has as its object
a ja:FileManager specification; the constructed document manager
is given a new file manager constructed from that specification. If there is no
ja:fileManager property, then the default FileManager
is used.
The ja:policyPath property value, if present, should be a string
which is a path to policy files as described in the Jena ontology documentation.
If absent, the usual default path is applied.
If the sub-model of the assembler specification reachable from the DocumentManager resource contains any OntDocumentManager DOC_MGR_POLICY or ONTOLOGY_SPEC objects, they will be interpreted by the constructed document manager object.
A ja:FileManager object may have a ja:locationMapper
property value which identifies the specification of a LocationMapper
object initialising that file manager.
A ja:LocationMapper object may have lm:mapping
property values, describing the location mapping, as described in the
FileManager documentation. (Note that the vocabulary for those items is
in a different namespace than the JA properties and classes.)
Union models can be constructed from any number of submodels and a single root model. The root model is the one written to when the union model is updated; the submodels are untouched.
If the single ja:rootModel property is present, its value
describes a model to use as the root model of the union. All updates to the
union are directed to this root model. If no root model is supplied, the
union is given an immutable, empty model as its root.
Any ja:subModel property values have objects describing
the remaining sub-models of the union. The order of the sub-models in the
union is undefined (which is why there's a special rootModel
property).
The PrefixMappings of a model may be set from PrefixMapping specifications.
The ja:includes property allows a PrefixMapping to include the
content of other specified PrefixMappings.
The ja:prefix and ja:namespace properties
allow the construction of a single element of a prefix mapping by specifying
the prefix and namespace of the mapping.
There are two more Assembler directives that can be
used in an Assembler specification: the assembler and imports
directives.
A specification may contain statements of the form:
someResource ja:assembler "some.Assembler.class.name"
When someResource is used as the type of a root object,
the AssemblerGroup that processes the description will use an instance
of the Java class named by the object of the statement. That class
must implement the Assembler interface. See
loading assembler classes
for more details.
If a specification contains statements of the form:
anyResource owl:imports someURL
or, equivalently,
anyResource ja:imports someURL
then the specification is regarded as also containing the contents of the
RDF at someURL. That RDF may in turn contain
imports referring to other RDF.
Assembler.general is a particular implementation of
the Assembler interface. An Assembler knows
how to build the objects -- not just models -- described by an Assembler
specification. The normal route into an Assembler is through the method:
root resource properties and
decides whether it can build an object with that description. If not,
it throws an exception. Otherwise, it constructs and returns a suitable
object.
Since the creation of Models is the reason for the existance of Assemblers, there is a convenience wrapper method:
When an Assembler requires sub-objects (for example,
when an InfModel Assembler requires a Reasoner object), it uses the
method:
open(root) is just
open(Assembler,Resource) be the place where
all the work is done. (Amongst other things, this makes testing
easier.)
When working with named persistent objects (typically database models), sometimes you need to control whether new objects should be constructed or old models can be reused. There is an additional method
Mode argument controls the creation (or not)
of persistent models. The mode is passed down to all sub-object
creation. The standard implementation of open(sub,root)
is just:
Mode object has two methods:
root is the root resource describing the object to be
created or reused, and name is the name given to it.
The result is true iff the permission is granted.
Mode.DEFAULT permits the reuse of existing objects
and denies the creation of new ones.
There are four Mode constants:
Mode methods are passed the resource root and
name, the user can write specialised Modes that look at
the name or the other root properties to make their decision.
Note that the Modes only apply to persistent objects, so eg MemoryModels or PrefixMappings ignore their Mode arguments.
There is a family of basic assemblers, each of which knows how to
assemble a specific kind of object so long as they're given an
Assembler that can construct their sub-objects. There are defined constants
in Assembler for (an instance of) each of these basic
assembler classes.
| produces | Class | Type | constant |
|---|---|---|---|
| default models | DefaultModelAssembler | ja:DefaultModel | defaultModel |
| memory models | MemoryModelAssembler | ja:MemoryModel | memoryModel |
| inference models | InfModelAssembler | ja:InfModel | infModel |
| RDB models | RDBModelAssembler | ja:RDBModel | rdbModel |
| reasoners | ReasonerAssembler | ja:Reasoner | reasoner |
| connection descriptions | ConnectionAssembler | ja:Connection | connection |
| content | ContentAssembler | ja:Content | content |
| ontology models | OntModelAssembler | ja:OntModel | ontModel |
| rules | RuleSetAssembler | ja:RuleSet | rules |
| union models | UnionModelAssembler | ja:UnionModel | unionModel |
| prefix mappings | PrefixMappingAssembler | ja:PrefixMapping | prefixMapping |
| file models | FileModelAssembler | ja:FileModel | fileModel |
Assembler.general is an assembler group,
which ties together those basic assemblers. general
can be extended by Jena coders if required. Jena components that
use Assembler specifications to construct objects will use
general unless documented otherwise.
In the remaining sections we will discuss the Assembler
classes that return non-Model objects and conclude with a description
of AssemblerGroup.
The ContentAssembler constructs Content objects (using the
ja:Content vocabulary) used to supply
content to models. A Content object has the method:
fill method adds the represented content to
the model. The supplied ModelAssemblers automatically apply
the Content objects corresponding to
ja:content property values.
A ConnectionAssembler constructs ConnectionDescriptions according to the specification. An ConnectionDescription retains the information required to make a database connection, can constructs that connection on demand.
When a ConnectionAssembler is constructed, it may optionally be given a Resource describing (using the JA vocabulary) default values for any of the database properties. When that Assembler is used to create a Connection, missing values are filled in from the defaults. This allows sensitive information to be left out of the RDF description.
The ConnectionAssembler embedded in Assembler.general has
defaults taken from the system properties jena.dbUser
and jena.dbType
A RulesetAssembler generates lists of Jena rules.
A "default model" is a model of unspecified type which is implemented as
whatever kind the assembler for ja:DefaultModel generates.
The default for a DefaultModel is to create a MemoryModel with no special
properties.
The AssemblerGroup class allows a bunch of other Assemblers to be bundled together and selected by RDF type. AssemblerGroup implements Assembler and adds the methods:
AssemblerGroup's implementation of open(sub,root)
finds the most specific type of root that is a subclass
of ja:Object and looks for the Assembler that has been
associated with that type by a call of implementWith.
It then delegates construction to that
Assembler, passing itself as the sub-assembler. Hence each
component Assembler only needs to know how to assemble its own
particular objects.
The assemblerFor method returns the assembler associated
with the argument type by a previous call of implementWith,
or null if there is no associated assembler.
AssemblerGroups implement the ja:assembler functionality.
The object of an (type ja:assembler "ClassName") statement
is a string which is taken as the name of an Assembler
implementation to load. An instance of that class is associated with
type using implementWith.
If the class has a constructor that takes a single Resource
object, that constructor is used to initialise the class, passing in the
type subject of the triple. Otherwise the no-argument
constructor of the class is used.