Common-gcore-resources

common-gcore-resources contains an object-based implementation of the gCube Resource Model, i.e. a set of classes that represent known resource types.

The object model improves over its counterpart in the gCube Core Framework (gCF) in that:

• it has no dependency on the gCore stack, or in fact any other 3rd party library.
• it offers simpler APIs for the construction and inspection of resources.

For its independence from gCore, the model can be easily used in a variety of client environments. Target clients may be external to gCube but also include the next-generation of gCube services. In this sense, common-gcore-resources is part of a new stack of gCube components that support featherweight gCube clients.

Model Classes

The model includes the following top-level resource classes:

• Software: describes services, libraries, plugins and other gCube components (corresponds to GCUBEService in the older model)
• GCoreEndpoint: describes endpoints of gCore services (corresponds to GCUBERunningInstance in the older model)
• ServiceEndpoint: describes endpoints of non-gCore services (corresponds to GCUBERuntimeResource in the oder model)
• ServiceInstance describes instances of (stateful) gCore services (not direct counterpart in the older model).
• HostingNode: describes gHNs (corresponds to GCUBEHostingNode in the older model)
• GenericResource: describes gCube resources which are not described by any of the previous classes (corresponds to GCUBEGenericResource in the older model).

Each class relies on static inner classes to model the complex properties of the corresponding resource type.

Collectively, resourcel classes and their inner classes are referred to as model classes.

All resources classes have the following property:

• serialisation: their instances can be serialised and deserialised to and from XML with the RI implementation of JAXB which is part of the Java platform since version 1.6.

All resource classes except ServiceInstance have also the following property:

• validation: the serialisation of their instances can be validated against the schema definition of the corresponding resource type. There is otherwise little or no validation logic within the model. Note that there is also no schema definition for ServiceInstances.

Finally, all model classes have the following property:

• equivalence: their instances can be compared for equivalence (implement equals()) and can serve as keys in hash-based structures (implement hashCode()).

The API of model classes are designed to support the following instance lifecycle:

• clients create instances and publish them with distinguished services of the gCube Information System.
• clients inspect instances retrieved from distinguished services of the gCube Information System.
• clients may update retrieved instances and re-publish them with distinguished services of the gCube Informaton System.

Clients that create or update instances are referred to as publishing clients. They interact with the write API of model classes.

Clients that inspect instances are referred to as discovery clients. They interact with the read API of model classes.

It is understood that publishing and discovery clients interact with clients libraries dedicated to resource publication and discovery.

Publishing libraries will serialise instances and discovery libraries will deserialise them. Publishing libraries may also validate them prior to publication.

While these libraries will have dependencies on the model, the model is totally independent from such libraries and the services of the gCube Information System.

Serialisation, Deserialisation, and Validation

Resource class instances can be serialised and deserialised using standard JAXB idioms. To illustrate, a GenericResource may be serialised to an in-memory character stream as follows:

GenericResource generic = …
JAXBContext ctx = JAXBContext.newInstance(GenericResource.class);
Marshaller marshaller = ctx.createMarshaller();
 
StringWriter writer = new StringWriter();
marshaller.marshal(generic,writer);

Consult the JAXBContext and Marshaller APIs for various configuration and output options. For convenience, the Resources class defines static methods that encapsulate this idiom under a reduced API:

• <T extends InputStream> InputStream marshal(Object,T)
• <T extends Writer> marshal(Object,T)
• <T extends Result> Result marshal(Object,T)

Refactoring the previous example:

Resources.marshal(generic,writer);

During testing, a common destination for instance serialisations is the standard output stream. The Resources class includes a print() method for the purpose:

• void print(Object)

Note: marshal() methods return the input destination, for cases in which doing so is convenient (e.g. round-tripping tests).

Similarly, the GenericResource may be deserialised from the previous character stream as follows:

Marshaller unmarshaller = ctx.createUnmarshaller();
StringReader reader = new StringReader(writer.toString());
GenericResource deserialised = (GenericResource) unmarhsaller.unmarshal(reader);

Again, consult the Unmarshaller APIs for different input options. For convenience, the Resources class defines static methods that encapsulate this idiom under a reduced API:

• <T> T unmarshal(Class<T>,InputStream)
• <T> T unmarshal(Class<T>,Reader)
• <T> T unmarshal(Class<T>,Source)

Refactoring the previous example:

GenericResource deserialised = Resources.unmarshal(generic,reader);

'Note: since serialisation and deserialisation failures are on average unlikely and unrecoverable errors, marshal() and unmarshal() methods throws them as unchecked exceptions (RuntimeExceptions).

Note also that the following holds true in all cases above:

generic.equals(unmarshalled);

Resource instance serialisations can then be validated using the following static method of the Resources class:

• validate(Object resource) throws IllegalArgumentException, Exception

The method throws an IllegalArgumentException if it receives a resource without a known schema. It throws a generic Exception if the resource has a known schema but it is not valid with respect to that schema.

Validation may be performed during testing, or before the instance serialisation is stored or transmitted over the network. Dedicates libraries for resource publishing will normally performed it a pre-condition to publication.