Difference between revisions of "Content Manager: Interfaces"

Revision as of 13:15, 5 October 2010

As overviewed above, the interface of the Content Manager is distributed across three stateful port-types:

• the Factory port-type, which is the interface of a single WS-Resource;
• the ReadManager port-type, which is the read-only interface of many, collection-specific WS-Resources;
• the WriteManager port-type, which is the write-only interface of many, collection-specific WS-Resources.

In this Section, we discuss in more detail the operations of the port-types and the Resource Properties of the corresponding WS-Resources. For clarity, we show and comment the signatures of operations in terms of the underlying Java implementation, which mirror the WSDL definitions. We point directly to the WSDL for the definition of auxiliary data structures for input and outputs (e.g. values of Resource Properties or records of ResultSets).

note: The service offers client-side libraries which operate at a higher level of abstraction than its public interface. The operations discussed below are of interest to clients that choose to bypass those facilities.

Factory

The Factory resource exposes two operations, both which are intended for clients that wish to create Collection Managers (ReadManagers and/or WriteManagers). The operations are not for generic use, in that clients are expected to target a specific plugin to which the Factory resource ought to delegate the creation of Collection Managers. The operations, their inputs, and their outputs are defined in the WSDL of the port-type.

The first operation is synchronous, in that clients block waiting for the creation of the Collection Managers:

• public EprList create(CMSCreateParameters parameters) throws GCUBEFault

the operation creates Collection Managers and returns a list of references to their endpoints, indexed by the name of the corresponding port-type. The creation of resource is paremetrised by:

• the name of the plugin to which the service ought to dispatch the request, the target plugin.
• the directive to the service to broadcast the request for state replication, in line with OCMA patterns.
• an arbitrary payload of parameters specific to the target plugin.

these may vary from plugin to plugin, but typically will contain sufficient information to directly or indirectly identify one or more collections and the repository that hosts them.

The second operation is instead asynchronous and it is indicated when target plugins declare long creation times in their documentation:

• String createAsync(CMSCreateParameters parameters) throws GCUBEFault

the operation takes the same input as the synchronous version but returns immediately with the locator of a ResultSet which will be populated by the service only when the Collection Managers are created by the target plugin. Specifically, the ResultSet will contain a single CMSCreateOutcome, which captures the outcome of the operation (see WSDL definition). This can be a success or else a failure. In the first case, clients obtain the EprList described above. In the second case, they obtain the fault that occurred during the creation of the Collection Managers.

FInally, the Factory resource publishes a multi-valued Resource Property Plugin, which contains a PluginDescription for each of the plugins hosted by the running instance (see WSDL definition).

Read Managers

A ReadManager resource exposes three read-only operations over the content of the bound collection. The operations are intended for generic use, in that clients are not required to know the repository that hosts the collection or the service plugin that mediates access to that repository. The operations, their inputs, and their outputs are defined in the WSDL of the port-type.

• AnyHolder getByID(GetByIDParams params) throws GCUBEFault

the operation returns a gDoc tree. Invocations are parameterised by:

• the identifier of the tree root;
• [optional] a tree predicate with respect to which the tree should be pruned before it is returned.

• String getByIDs(GetByIDsParams params) throws GCUBEFault

the operation returns the locator of a ResultSet of gDoc trees. Invocations are parameterised by:

• the locator of a ResultSet of tree root identifiers;
• [optional] a tree predicate with respect to which the trees should be pruned before they are returned.

note: tree predicates in input and gDoc trees in output are contained in an AnyHolder wrapper (see WSDL definition).

• String get(GetParams params) throws GCUBEFault

the operation returns the locator of a ResultSet of gDoc trees. Invocations are parameterised by:

• [optional] a tree predicate with respect to which the trees should be pruned before they are returned.

note: invocations that specify no predicate effectively ask for the contents of the whole collection.

A ReadManager resource publishes the following Resource Properties:

• CollectionID: the identifier of the bound collection, as per OCMA requirements;
• TypeID: the access type of the port-type, as per OCMA requirements. The value of this property is constant: gDocRead;
• Plugin: the name of the bound plugin;
• Cardinality: an estimate of the number of documents in the collection;
• LastUpdate: an estimate of the time in which the collection was last updated;

Write Managers

A WriteManager exposes four write-only operations over the content of a bound collection. The operations are intended for generic use, in that clients are not required to know the repository that hosts the collection or the service plugin that mediates access to that repository. The operations, their inputs, and their outputs are defined in the WSDL of the port-type.

• String add(AnyHolder holder) throws InvalidDocumentFault, GCUBEFault

the operation adds a gDoc tree to the bound collection and returns the identifier assigned to the tree root as a result.

note: the operation assumes that all nodes of the input tree acquire identifiers as a result of a successful addition. Depending on the plugin that serves the request, the operation may fail if the nodes already have an identifier.

• String addRS(String locator) throws GCUBEFault

the operation adds zero or more gDoc trees to the bound collection and returns a locator of a ResultSet of AddOutcomes, one for each tree in input (see WSDL definition). In the case of successful outcome, clients obtain the identifier assigned to the tree root. In the case of failure, they obtain the stack trace of the fault that prevented the addition of the tree.

note: again, the operation assumes that all nodes of the input tree acquire identifiers as a result of a successful addition. Depending on the plugin that serves the request, the operation may fail if the nodes already have an identifier.

• VOID update(AnyHolder holder) throws UnknownDocumentFault, InvalidDocumentFault, GCUBEFault

the operation updates a gDoc tree in the bound collection (the target tree). Invocations are parameterised by delta trees, gDoc trees that capture all the updates to be applied to target trees, including addition or removal of attributes, changes to attribute values, addition and removal of nodes, and changes to leaf values. In more detail, a delta tree is comprised of nodes marked with an attribute http://gcube-system.org/namespaces/contentmanagement/gdoc:status and includes:

• all the nodes of the target tree which have changed, with the corresponding identifiers and with a status of MODIFIED or DELETED;

note: attributes of the target tree that have been removed occur in the delta tree with a value of _null;

note: DELETED nodes are either leaves with a value of _null_ or inner nodes with no children.

note: nodes that have no identifiers cannot be referred to in the delta tree, hence cannot be updated.

• all the nodes that should be added to the target tree, without identifiers and with a status of NEW.

note: NEW nodes are leaves or inner nodes with NEW descendants.

note: depending on the bound plugin, NEW nodes may be assigned identifiers upon being added to the target tree.

As an example, consider the following gDoc tree, where status attributes are depicted as node markers:

Here, the delta tree captures a set of updates to the descendants of a gDoc tree:

• the root has acquired or changed an attribute x;
• node 2 has lost its child 5 and all its descendants;
• node 3 has acquired a child and its descendants;
• node 4 has lost the attribute z and the child 6, while the value of its child leaf 7 has changed.

note: all the nodes of the target tree that have not changed do not occur in the delta tree.

• String updateRS(String locator) throws GCUBEFault

the operation takes the locator of a ResultSet with delta trees for zero or more target gDoc trees and returns the locator of a ResultSet of UpdateFailures (see WSDL definition), one for each delta tree that could not be processed into an update of the corresponding target tree. In particular, clients obtain the identifier of the root of the target tree and the stacktrace of the error that occurred during its update.

note: delta trees in input are contained in AnyHolder wrappers (see WSDL definition).

A WriteManager resource publishes the following Resource Properties:

• CollectionID: the identifier of the bound collection, as per OCMA requirements;
• TypeID: the access type of the port-type, as per OCMA requirements. The value of this property is constant: gDocWrite;
• Plugin: the name of the bound plugin;
• Cardinality: an estimate of the number of documents in the bound collection;
• LastUpdate: an estimate of the time in which the bound collection was last updated;