Revision as of 22:16, 8 February 2011

The gCube Document Model (gDM) is a descriptive model used in gCube for data associated with authoring and rendering processes.
The gCube Model Library (gML) is a client library that includes an object-based implementation of the gDM.
The gML is a component of the subsystem of gCube Information Services.

In what follows, we first summarise the gDM in abstract terms and then overview its implementation in the gML.

Model

The model defines five main structures with broad and well-known semantics:

• the document: a self-contained unit of content within a collection of related units;
• the metadata: a formal description of a document, in some model other than gDM;
• the annotation: a subjective observation or record about a document;
• the part: a component of a document;
• the alternative representation: a secondary manifestation of a document.

These structures are the elements of the model.

Elements may be associated with properties. A property is a named value that:

• may or may not occur within the element (optional vs. mandatory);
• may occur more times within the element (single vs. repeated);
• may be a piece of text, an integer, a datetime, or a bytestream (simple);
• may be a structure of other properties (structured)

Metadata, annotations, parts, and alternative representations are themselves optional and repeated properties of documents.
They are the inner elements of the document.

Some properties are common to documents and inner elements:

• identifier: identifies a document within its collection or an inner element within its document (mandatory, simple, single, text);
• name : free-form element descriptor (optional, simple, single, text);
• creation time: records the time in which the element description was created (optional, simple, single, datetime);
• last update time: records the time in which the element description was last changed (optional, simple, single, datetime);
• bytestream: a digital representation of the element (optional, simple, single, bytestream);
• mime type: the MIME type of the element’s bytestream (optional, simple, single, text in RFC 2046 syntax);
• length : number of octets in the element’s bytestream (number of octets) (optional, simple, single, positive integer);
• url : a URL to a digital representation of the element’s (optional, simple, single text compliant with RFC 2396/RFC 2732 syntax);
• language : the language of the element (optional, simple, single, text in ISO639 code list);
• schema uri: a schema for the (embedded/referred) bytestream of the element, if applicable (optional, simple, single, text compliant with RFC 2396/RFC 2732 syntax);
• schema name: a free-form descriptor (optional, simple, single, text compliant with RFC 2396/RFC 2732 syntax);
• property: an arbitrary property of the element (optional, structured, repeated);
  • key: identifies the property within the element (mandatory, simple, single, text);
  • type: free-form descriptor of property semantics (optional, simple, single, text);
  • value: the value of the property (mandatory, simple, single text).

A few properties are specific to individual elements.

• documents
  • collection identifier: identifies a document in a collection (mandatory, simple, single, text);
• annotations
  • previous: the identifier of an another annotation of the document which an annotation somehow refers or related to (optional, simple, single, text);
• parts
  • order: the order of a part within the document (optional, simple, single, positive integer):

Implementation

The gML is an object-based implementation of the gDM which is designed for distributed document management.
Clients can use its classes and interfaces to create, change, or inspect documents that have been or will be stored remotely within the system.

As one aspect of distribution, the gML defines an exchange format for documents. In that format, documents are constrained forms of the edge-labelled trees managed by the Content Management service|. This enables documents to be stored, updated, and retrieved through that service. While the gML itself does not implement CRUD operations for documents, it does prepare the ground for their implementation. One such implementation can be found in the gCube Document Library (gDL).

Element Classes

In the gML, all the elements of the gDM have the GCubeElement interface. The interface gives read-only access to common element properties and can be used for element-generic operations. It is then implemented by element-specific classes such as:

• GCubeDocument
• GCubeMetadata
• GCubeAnnotation
• GCubePart
• GCubeAlternative.

Clients use these classes to construct, update, and inspect elements. By design, none of these element classes is thread-safe. Clients that access their instances from multiple threads are responsible for synchronisation, typically through some form of shared lock.

New Elements and Element Proxies

All element classes define two constructors. The default constructor creates elements that have no identifier while a secondary constructor creates elements with identifiers. Since identifiers cannot be changed in the gML, elements that are created without an identifier may only receive one when they are stored in the system. Until then, these elements are new within the system, and the methodisNew() points this out. E.g. for documents:

GCubeDocument doc = new GCubeDocument(); //a new document
assert(doc.isNew());

In contrast, elements that are created with identifiers represent local proxies of elements that have been previously stored in the system, when they were given precisely those identifiers:

GCubeDocument proxy = new GCubeDocument("someid");  // a document proxy
assert(proxy.isNew()==false);

Most often, element proxies are created when documents are deserialised from their exchange format. The retrieval operations of the gDL, most noticeably, return proxies of remotely stored documents. Clients may also create element proxy manually, so as to express changes that they wish to be reflected in their remote counterparts. We discuss element updates later on and concentrate next on the creation of new elements.

Creating Elements

Since all elements share a set of common properties in the gDM, creating a new document is not much different from creating a new metadata element, a new annotation, a new alternative representation, or a new document part. We discuss here the common steps and deal later with the specifics of individual element types.

Like identifiers, the time of creation and last update cannot be set on new elements. Elements acquire the former when they are first stored in the system and the latter when they are updated in the system.

assert(doc.creationTime()==null);
assert(doc.lastUpdate()==null);

Other common properties may instead be assigned on new elements, e.g:

doc.setName("some document");
doc.setLanguage(Locale.ITALIAN);
doc.setURL(new URL("http://......");
doc.setSchemaName("someschema");
doc.setSchemaURI(new URI("http://..."));

Bytestreams are among these properties, and for this clients have a number of options:

byte[] bytes = ...
doc.setBytestream(bytes)
 
InputStream stream = ...
doc.setBytestream(stream)
 
Reader characterStream = ....
doc.setBytestream(characterStream)

Note: the stream-based methods are for the convenience of clients that read bytestreams from files, or that hold already stream-based references for them. They do not imply that arbitrarily large bytestreams should be inlined in an element. Large bytestreams ought to be made available at some public URL, and clients should set the URL on the element.

In all cases above, an attempt is made to guess the MIME type of the bytestream (if not already set by the client). Similarly, the length of the bytestream is automatically derived:

doc.setBytestream("<a>hello world</a>".getBytes());
assert (doc.mimeType()!=null)
assert (doc.length()!=0)

Clients may well override the guessed MIME types:

doc.setMimeType("text/xml");

but they do so knowing that both length and MIME type may be recomputed when elements are stored within the system, depending on the behaviour of the particular storage back-end.

Finally, adding generic properties to elements is straightforward:

GCubeElementProperty prop = new GCubeElementProperty("somekey","sometype","someval");
doc.addProperty(prop);

Here GCubeElementProperty is simply the triple required to represent a generic element property. If a property with the same key was previously added to the element, then this is replaced by the new property and returned to the client.

Creating Documents

In addition to common properties, documents may are associated with a collection and have inner elements.

Clients can set the identifier of the document's collection only once:

doc.setCollectionID("somecollectionid");
doc.setCollectionID("somecollectionid");  //raises an error

As to inner elements, clients add them to type-specific collections within the document, e.g.:

GCubeMetadata m = ...
doc.metadata().add(m);
 
GCubeAnnotation a= ...
doc.annotations().add(a);

Note: a new document can only have new elements. An attempt to add an element proxy to a new document is non-sensical and will raise an error.

An inner element that is added to a document becomes bound to it:

assert(m.document().equals(doc));
assert(a.document().equals(doc));

Note: the assertions above show that documents can be compared for equivalence. The same is true of all elements in gML.

The binding between a document and one of its inner elements can be broken by removing the element from the document. However, it cannot be overridden by adding the element to another document:

doc.metadata().remove(m); //ok
 
GCubeDocument anotherdoc = ...
anotherdoc.add(m)  //raises an error

Creating Metadata

In the current version of the gDM, metadata elements may only have common properties.

Creating Annotations

In addition to common properties, annotations of the same document may be 'threaded' in the gDM. To model this, clients can set an annotation to follow another in a thread, e.g.:

GCubeAnnotation a1 = ...
GCubeAnnotation a2 = ...
a2.setPrevious(a1);

The operation succeeds only if:

• a1 and a2 are linked to the same document;
• both the document and a1 are element proxies.

The identifier of a1 is required in order to record the relationship in the system, and a1 can only have an identifier if its document has already been stored in the system. This aligns with the pragmatics of threading, whereby users observe existing annotations and then create new ones to 'respond' to those annotations.

Because of these constraints, annotation threads are defined when a document is updated, as we discuss [#Updating Inner Elements|later].

Creating Alternative Representations

In the current version of the gDM, alternative representations may only have common properties.

Creating Parts

In addition to common properties, document parts may be ordered (e.g. document chapters). It is easy to set the order of a part:

GCubePart p = ...
p.setOrder(3);

but the operation succeeds only if

• p is already linked to a document,
• the document has another part wither order 2.

Thus clients may add ordered parts to new documents or document proxies, as long as they do so after they have added the parts to the document and in strict order, e.g.:

GCubePart part1 = new GCubePart();
...set part properties...
doc.parts().add(part1);
part1.setOrder(1);
 
GCubePart part2 = new GCubePart();
...set part properties...
doc.parts().add(part2);
part1.setOrder(2);

Updating Elements

Clients may use element proxies to express changes they wish to apply to documents that have been previously stored within the system.
Given a document proxy that is synchronised with its remote counterpart, we may ask it to track all future changes to its properties:

doc.trackChanges();

In response, the proxy takes a snapshot of its current properties. Later, it can use this snapshot to tell how the properties have changed since. This delta information may then be fed to the system as a minimal and exact specification of the changes that need to be reflected onto the proxied document. The update operations of the gDL do precisely this, extract delta information from document proxies and feed it to the system on behalf of clients.

Changes can only be tracked on a document proxy that is synchronised with its remote counterpart. Enabling change tracking on a new document is non-sensical and will generate an error. Again, clients can use the read operations of the gDL to obtain synchronised document proxies .

Staged Updates

When changes do not depend on the state of documents within the system, the cost of synchronisation can be conveniently avoided. In these cases, clients can perform staged updates on document proxies. As introduced #New Elements and Element Proxies|above], creating such proxies requires only knowledge of document identifiers:

GCubeDocument proxy = new GCubeDocument("someid");

Clients can then proceed as follows:

• stage the proxy, i.e. set dummy values for properties they wish to change or delete;
• enable change tracking on the proxy;
• change or delete the staged properties, or else add new properties to the proxy;

In essence, staging gives enough information to understand what properties have changed and how, regardless of their current value in the system, e.g:

proxy.setName("dummy");  //stage name of proxy
proxy.trackChanges();    //marks end of staging
proxy.setName("newname") //applies changes to staged property

Here, the client stages the name of the proxy and changes it to its new value after enabling change tracking. Clients can add or delete properties in a similar manner, e.g:

proxy.setBytestream("dummy".getBytes());
 
proxy.trackChanges();
 
proxy.setBytestream(null);
proxy.setLanguage(Locale.ENGLISH);

Here, the clients stages a bytestream and then erases that value after enabling change tracking. At that point, the client adds a language to the proxy, which is thus understood to be entirely new for it.

Staging extends to generic document properties:

GCubeElementProperty prop1 = new GCubeElementProperty("somekey","somevalue");
GCubeElementProperty prop3 = new GCubeElementProperty("someotherkey");
 
proxy.addProperty(prop1);
proxy.addProperty(prop2);
 
proxy.trackChanges();
 
//change value of first property
prop1.setValue("newval");
 
//delete second property
proxy.removeProperty("someotherkey");
 
//add new property
GCubeElementProperty newprop = new GCubeElementProperty("newkey","newtype","newvalue");
proxy.addProperty(newkey);

Finally, clients can use the method isTracked() on a document proxy, e.g.:

GCubeDocument proxy = new GCubeDocument("someid");
...
proxy.trackChanges();
...
assert(proxy.isTracked());

They can also use the method resetChanges() to delete the record of changes applied since they last enabled tracking:

proxy.resetChanges();
assert(proxy.isTracked()==false);

Resetting changes is rarely needed, however, as the update operations of the gDL do that automatically after committing the changes that have been tracked on a document proxy.

Updating Inner Elements

Updates to inner element follow a similar pattern, e.g.:

GCubeDocument proxy = new GCubeDocument("someid");
 
//stage first metadata
GCubeMetadata mdproxy1 = new GCubeMetadata("1");
mdproxy1.setLanguage(Locale.ENGLISH);
 
//stage second metadata
GCubeMetadata mdproxy2 = new GCubeMetadata("2");
 
proxy.metadata().add(mdproxy1);
proxy.metadata().add(mdproxy2);
 
//track change
proxy.trackChanges(); 
 
//effect change on first metadata
mdproxy1.setLangauge(Locale.ITALIAN);  //change metadata language
mdproxy1.setName("newname");  //add metadata name
 
//remove second metadata
proxy.metadata().remove(mdproxy2);
 
//add new metadata
GCubeMetadata newmd = new GCubeMetadata();  //new metadata
.... //build new metadata
proxy.metadata().add(newmd);

In this example, the client stages a set of changes to the metadata elements of a document. He stages one metadata proxy in order to change its language and add a name for it. He also stages another metadata proxy that he wishes to delete from the proxied document. The client then enables change tracking and performs the required changes, including removing the second metadata element from the proxy. Finally, he adds a new metadata element to the document proxy which he did not stage and thus appears new for the document.

As a further example, consider staging the definition of an annotation thread:

GCubeDocument proxy = new GCubeDocument("someid");
 
//stage first annotation
GCubeAnnotation annotationproxy = new GCubeAnnotation("1");
proxy.annotations().add(annotationproxy);
 
proxy.trackChanges();
 
GCubeAnnotation newannotation = new GCubeAnnotation("2");
 
...  //build new annotation
 
proxy.annotations().add(newannotation);
 
newannotation.setPrevious(annotationProxy);

And again, consider staging the addition of an ordered part:

GCubeDocument proxy = new GCubeDocument("someid");
 
//stage existing part
GCubePart partproxy = new GCubePart("1");
proxy.parts().add(partproxy);
partproxy.setOrder(5);
 
proxy.trackChanges();
 
GCubePart newpart = new GCubePart("2");
 
...  //build new part
 
proxy.parts().add(newpart);
 
newpart.setOrder(partproxy);

Inspecting Elements

Consuming elements is straightforward and the code documentation for the element classes shows clearly what accessor methods are available on them, what output they may return, and under what conditions they may fail. We discuss next only some case of particular interest.

Inspecting Inner Elements

Navigating the inner elements of documents, in particular, relies on the same type-specific collections used for additions e.g.:

for (GCubeMetadata m : doc.metadata())
	...m...
 
Iterator<GCubeAlternative> it = doc.alternatives().iterator(); 
while (it.hasNext()) {
   .... GCubeAlternative a = it.next()......
}
 
 
if (doc.parts().contains("somemetadataid")
	GCubePart p = doc.parts().get("somemetadataid")  //assuming document and part are not new
    ...m...
}
 
if (doc.annotations().size()>0)
	....

Type-specific collections are specialised, and behave like standard Java 'List's only insofar as iterations and size inspections are involved. Clients that wish to use other List-based methods on their elements, need to do so on a clone of the type-specific collection, which has the required Listtype. For example, to directly access a particular element of the collection, clients may do:

List<GCubeAnnotation> annotations = doc.annotations().toList();
...annotations.get(0)....

Inspecting Annotations

As discussed _above_, the annotations of a document may be related to each other so as to form a linear thread. Clients may navigate one such thread backwards starting from any annotation in a document proxy, e.g.:

GCubeAnnotation a = ....
GCubeAnnotation predecessor = a.previous();

There are two cases in which previous() returns null, when

• the annotation has genuinely no predecessor, e.g. is at the beginning a thread or is an isolated annotation of the document
• the annotation does have a predecessor but this element is not locally available in the document proxy.

A document proxy is only partially synchronised with the document when it's being locally staged, or when it has been parsed from a partial serialisation of the document. The latter case, for example, is common when clients use the read operations of the gDL to retrieve not less and no more information about the document than what they really require. In particular, they may retrieve some annotations of the document but not others.
After parsing a partial document serialisation, the proxy attempts to resolve all the the identifiers of previous annotations that can be resolved into objects. Those which cannot be resolved are still available to clients for inspection:

String predecessorID = a.previousID();

Under these constraints, clients can always ask for the the contiguous parts of the thread which could be fully resolved, e.g.

List<GCubeAnnotation> thread = a.thread();

When the document proxy contains all the annotations of the corresponding documents, thread() returns the all the annotations in the thread from the beginning to and including a.

Inspecting Parts

We have seen above that the parts of a document may be ordered. While the method order() can be used to inspect the order of a part, the method previous() can be used to access the part that precedes the part in that ordering:

GCubePart p = ....
GCubePart predecessor = p.previous();
if (predecessor!=null) 
  assert(predecessor.order()==p.order()=-1)

The reasons for the null check are analogous to those discussed above for annotation threads. In particular, previous() returns null when:

• the part has genuinely no predecessor, e.g. it is the first or has no order within the document;
• the part does have a predecessor but this element is not locally available in the document proxy. See the discussion on annotation threads for an explanation of when this may occur.