Enhanced Node HowTo

This note is a development of Ian's original note on the enhanced node and graph design of Jena 2.

Key objectives for the enhanced node design

One problem with the Jena 1 design was that both the DAML layer and the RDB layer independantly extended Resource with domain-specific information. That made it impossible to have a DAML-over-RDB implementation. While this could have been fixed by using the "enhanced resource" meachanism of Jena 1, that would have left a second problem.

In Jena 1.0, once a resource has been determined to be a DAML Class (for instance), that remains true for the lifetime of the model. If a resource starts out not qualifying as a DAML Class (no rdf:type daml:Class) then adding the type assertion later doesn't make it a Class. Similarly, of a resource is a DAML Class, but then the type assertion is retracted, the resource is still apparently a class.

Hence being a DAMLClass is a view of the resource that may change over time. Moreover, a given resource may validly have a number of different views simultaneously. Using the current DAMLClass implementation method means that a given resource is limited to a single such view.

A key objective of the new design is to allow different views, or facets, to be used dynamically when accessing a node. The new design allows nodes to be polymorphic, in the sense that the same underlying node from the graph can present different encapsulations - thus different affordances to the programmer - on request.

In summary, the enhanced node design in Jena 2.0 allows programmers to:

• provide alternative perspectives onto a node from a graph, supporting additional functionality particular to that perspective;
• dynamically convert a between perspectives on nodes;
• register implementations of implementation classes that present the node as an alternative perspective.

Terminology

To assist the following discussion, the key terms are introduced first.

node

A subject or object from a triple in the underlying graph

graph

The underlying container of RDF triples that simplifies the previous abstraction Model

enhanced node

An encapsulation of a node that adds additional state or functionality to the interface defined for node. For example, a bag is a resource that contains a number of other resources; an enhanced node encapsulating a bag might provide simplified programmatic access to the members of the bag.

enhanced graph

Just as an enhanced node encapsulates a node and adds extra functionality, an enhanced graph encapsulates an underlying graph and provides additional features. For example, both Model and DAMLModel can be thought of as enhancements to the (deliberately simple) interface to graphs.

polymorphic

An abstract super-class of enhanced graph and enhanced node that exists purely to provide shared implementation.

personality

An abstraction that circumscribes the set of alternative views that are available in a given context. In particular, defines a mapping from types (q.v.) to implementations (q.v.). This seems to be taken to be closed for graphs.

implementation

A factory object that is able to generate polymorphic objects that present a given enhanced node according to a given type. For example, an alt implementation can produce a sub-class of enhanced node that provides accessors for the members of the alt.

Class diagram

Key points

Some key features of the design are:

• every enhanced graph has a single graph personality, which represents the types of all the enhanced nodes that can be created in this graph;
• every enhanced node refers to that personality
• different kinds of enhanced graph can have different personalities, for example, may implement interfaces in different ways, or not implement some at all.
• enhanced nodes wrap information in the graph, but keep no independant state; they may be discarded and regenerated at whim.

How an enhanced node is created

creation from another enhanced node

If en is an enhanced node representing some resource we wish to be able to view as being of some (Java) class/interface T, the expression en.as(T.class) will either deliver an EnhNode of type C, if it is possible to do so, or throw an exception if not.

To check if the conversion is allowed, without having to catch exceptions, the expression en.canAs(T.class) delivers true iff the conversion is possible.

creation from a base node

EnhNode(Node,EnhGraph)

internal operation of the conversion

as(Class T) is defined on EnhNode to invoke asInternal(T) in Polymorphic. If the original enhanced node enis already a valid instance of T, it is returned as the result. Validity is checked by the method isValue().

If en is not already of type T, then a cache of alternative views of en is consulted to see if a suitable alternative exists. The cache is implemented as a sibling ring of enhanced nodes - each enhanced node has a link to its next sibling, and the "last" node links back to the "first". This makes it cheap to find alternative views if there are not too many of them, and avoids caches filling up with dead nodes and having to be flushed.

If there is no existing suitable enhanced node, the node's personality is consulted. The personality maps the desired class type to an Implementation object, which is a factory with a wrap method which takes a (plain) node and an enhanced graph and delivers the new enhanced node after checking that its conditions apply. The new enhanced node is then linked into the sibling ring.

How to build an enhanced node & graph

What you have to do to define an enhanced node/graph implementation:

1. define an interface I for the new enhanced node. (You could use just the implementation class, but we've stuck with the interface, because there might be different implementations)
2. define the implementation class C. This is just a front for the enhanced node. All the state of C is reflected in the graph (except for caching; but beware that the graph can change without notice).
3. define an Implementation class for the factory. This class defines methods canWrap and wrap, which test a node to see if it is allowed to represent I and construct an implementation of Crespectively.
4. Arrange that the personality of the graph maps the class of I to the factory. At the moment we do this by using (a copy of) the built-in graph personality as the personality for the enhanced graph.