# inside assemblers

This document describes Jena's built-in assembler classes and how to write and integrate your own assemblers. If you just need a quick guide to the common model specifications, see the assembler quickstart; if you want mroe details on writing assembler descriptions, see the assembler howto.

# the Assembler interface

An `Assembler` is an object that builds objects (most importantly, `Model`s) from RDF descriptions.

    public Object open( Assembler a, Resource root, Mode mode );

    public Object open( Assembler a, Resource root );

    public Object open( Resource root );

    public Model openModel( Resource root );

    public Model openModel( Resource root, Mode mode );

The fundamental method is the first: all the others are shorthands for ways of calling it. The abstract class `AssemblerBase` implements `Assembler` leaving only that method abstract and defining the others in terms of it.

The definition of `a.open(Assembler sub, Resource root, Mode mode)` is that `a` will construct the object described by the properties of `root`. If this requires the construction of sub-objects from descriptions hanging off `root`, `sub.open` is to be used to construct those. If the object is to be constructed in some persistent store, `mode` defines whether objects can be re-used or created: see modes for more details.

# builtin assemblers

Jena comes with a collection of built-in assemblers: a bunch of basic assemblers and a composite general assembler. Each of these assemblers has a constant instance declared as a field of `Assembler`.

assembler | result class | Type | constant
--- | --- | --- | ---
ConnectionAssembler[Resource root] ja:Connection ConnectionDescription | dbUser String
dbUser String
dbUserProperty String
dbPassword String
dbPasswordProperty String
dbURL String
dbURLProperty String
dbType String
dbTypeProperty
dbClass Class
dbClassProperty Class
ContentAssembler[FileManager fm] ja:Content Content | content *Content
content *Content
externalContent Content
quotedContent Content
literalContent Content
contentEncoding String
DefaultModelAssembler ja:DefaultModel Model | /see/ ModelAssembler
/see/ ModelAssembler
DocumentManagerAssembler ja:DocumentManager OntDocumentManager
policyPath String default [OntDocumentManager.DEFAULT_METADATA_PATH]
fileManager *FileManager
FileManagerAssembler ja:FileManager FileManager | locationMapper !LocationMapper
locationMapper !LocationMapper
FileModelAssembler ja:FileModel FileModel | /see/ ModelAssembler
/see/ ModelAssembler
fileEncoding String
mapName boolean
directory String
InfModelAssembler ja:InfModel InfModel | baseModel *Model
baseModel *Model
reasoner *Reasoner
LocationMappingAssembler ja:LocationMapper LocationMapper | /see/ LocationMapper
/see/ LocationMapper
MemoryModelAssembler ja:MemoryModel Model | /see/ ModelAssembler
/see/ ModelAssembler
ModelAssemebler ja:Model Model | reificationModel ReificationStyle
reificationModel ReificationStyle
/see/ PrefixMapping
/see/ Content
ModelSourceAssembler ja:ModelSource ModelGetter | connection *Connection
connection *Connection
NamedModelAssembler [] Model
modelName String
OntModelAssembler ja:OntModel OntModel | /see/ InfModelAssembler
/see/ InfModelAssembler
subModel *Model
ontModelSpec *OntModelSpec
OntModelSpecAssembler ja:OntModelSpec OntModelSpec | importSource *ModelGetter
importSource *ModelGetter
ontLanguage String
reasonerURL ?ReasonerFactory
reasonerFactory *ReasonerFactory
documentManager *OntDocumentManager
PrefixMappingAssembler ja:PrefixMapping PrefixMapping | includes *PrefixMapping
includes *PrefixMapping
prefix BNODE[prefix, namespace]
RDBModelAssembler ja:RDBModel ModelRDB | /see/ NamedModelAssembler
/see/ NamedModelAssembler
connection *ConnectionDescription
ReasonerFactoryAssembler ja:ReasonerFactory ReasonerFactory | reasonerURL ReasonerFactory
reasonerURL ReasonerFactory
reasonerClass Class
/see/ RuleSetAssembler
RuleSetAssembler ja:RuleSet RuleSet | rules *RuleSet
rules *RuleSet
rulesFrom URL for rules
rule String rule
UnionModelAssembler ja:UnionModel Model | rootModel *Model
rootModel *Model
subModel *Model

    ConnectionAssembler
    ContentAssembler
    DefaultModelAssembler
    DocumentManagerAssembler
    FileManagerAssembler
    FileModelAssembler
    InfModelAssembler
    LocationMappingAssembler
    MemoryModelAssembler
    ModelAssemebler
    ModelSourceAssembler
    NamedModelAssembler
    OntModelAssembler
    OntModelSpecAssembler
    PrefixMappingAssembler
    RDBModelAssembler
    ReasonerFactoryAssembler
    RuleSetAssembler
    UnionModelAssembler

    AssemblerGroup

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

# inside Assemblers

`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:

- open( Resource root ) ? Object

The Assembler inspects the `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:

- openModel( Resource root ) ? Model

which constructs the object and checks that it's a Model before returning it.

When an `Assembler` requires sub-objects (for example, when an InfModel Assembler requires a Reasoner object), it uses the method:

- open( Assembler sub, Resource root ) ? Model

passing in a suitable Assembler object. In fact the standard implementation of `open(root)` is just

- open( this, root )

passing in itself as the sub-assembler and having `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

- open( Assembler sub, Resource root, Mode mode )

where the `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:

- open( sub, root, Mode.DEFAULT )

A `Mode` object has two methods:

- permitCreateNew( Resource root, String name )
- permitUseExisting( Resource root, String name )

`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.DEFAULT - reuse existing objects
- Mode.CREATE - create missing objects
- Mode.REUSE - reuse existing objects
- Mode.ANY - reuse existing objects, create missing ones

Since the `Mode` methods are passed the resource root and name, the user can write specialised `Mode`s 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.

## implementing your own assemblers

(Temporary documentation pasted in from email; will be integrated and made nice RSN.)

    You have to implement the Assembler interface, most straightforwardly
    done by subclassing AssemblerBase and overriding

        public Object open( Assembler a, Resource root, Mode mode );

        because AssemblerBase both implements the boring methods that are
        just specialisations of `open` and provides some utility methods
        such as getting the values of unique properties. The arguments are

        * a -- the assembler to use for any sub-assemblies
        * root -- the resource in the assembler description for this object
        * mode -- the persistent open vs create mode

        The pattern is to look for the known properties of the root, use
        those to define any sub-objects of the object you're assembling
        (including using `a` for anything that's itself a structured
        object) and then constructing a new result object from those
        components.

        Then you attach this new assembler object to its type in some
        AssemblerGroup using that group's `implementWith` method. You
        can attach it to the handy-but-public-and-shared group
        `Assembler.general` or you can construct your own group. The
        point about an AssemblerGroup is that it does the type-to-assembler
        mapping for you -- and when an AssemblerGroup calls a component
        assembler's `open` method, it passes /itself/ in as the `a` argument,
        so that the invoked assembler has access to all of the component
        assemblers of the Group.

# basic assemblers

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`.

## basic assembler ContentAssembler

The ContentAssembler constructs Content objects (using the `ja:Content` vocabulary) used to supply content to models. A Content object has the method:

- fill( Model m ) ? m

Invoking the `fill` method adds the represented content to the model. The supplied ModelAssemblers automatically apply the `Content` objects corresponding to `ja:content` property values.

## basic assembler ConnectionAssembler

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`

## basic assembler RulesetAssembler

A RulesetAssembler generates lists of Jena rules.

## basic assembler DefaultModelAssembler

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.

## AssemblerGroup

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:

- implementWith( Resource type, Assembler a ) ? this
- assemblerFor( Resource type ) ? Assembler

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.

### loading assembler classes

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.