Difference between revisions of "Content Manager: Interfaces"
(→Factory) |
(→Read Managers) |
||
(3 intermediate revisions by the same user not shown) | |||
Line 48: | Line 48: | ||
* <code>AnyHolder getByID(GetByIDParams params) throws GCUBEFault</code> | * <code>AnyHolder getByID(GetByIDParams params) throws GCUBEFault</code> | ||
− | : the operation returns | + | : the operation returns a <code>gDoc</code> tree. Invocations are parameterised by: |
:* the identifier of the tree root; | :* the identifier of the tree root; | ||
:* [optional] a tree predicate with respect to which the tree should be pruned before it is returned. | :* [optional] a tree predicate with respect to which the tree should be pruned before it is returned. | ||
+ | |||
+ | |||
+ | [[Image:getbyidop.jpg|center|The <code>getByID</code> operation of ReadManager resources]] | ||
+ | |||
* <code>String getByIDs(GetByIDsParams params) throws GCUBEFault</code> | * <code>String getByIDs(GetByIDsParams params) throws GCUBEFault</code> | ||
: the operation returns the locator of a ResultSet of <code>gDoc</code> trees. Invocations are parameterised by: | : the operation returns the locator of a ResultSet of <code>gDoc</code> trees. Invocations are parameterised by: | ||
− | :* the locator of a ResultSet of | + | :* 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. | :* [optional] a tree predicate with respect to which the trees should be pruned before they are returned. | ||
:'''note''': tree predicates in input and <code>gDoc</code> trees in output are contained in an <code>AnyHolder</code> wrapper (see WSDL definition). | :'''note''': tree predicates in input and <code>gDoc</code> trees in output are contained in an <code>AnyHolder</code> wrapper (see WSDL definition). | ||
+ | |||
+ | |||
+ | [[Image:getbyidsop.jpg|center|The <code>getByIDs</code> operation of ReadManager resources]] | ||
+ | |||
* <code>String get(GetParams params) throws GCUBEFault</code> | * <code>String get(GetParams params) throws GCUBEFault</code> | ||
: the operation returns the locator of a ResultSet of <code>gDoc</code> trees. Invocations are parameterised by: | : the operation returns the locator of a ResultSet of <code>gDoc</code> trees. Invocations are parameterised by: | ||
:* [optional] a tree predicate with respect to which the trees should be pruned before they are returned. | :* [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. | |
− | + | ||
− | : '''note''': invocations that specify no | + | |
+ | [[Image:getop.jpg|center|The <code>get</code> operation of ReadManager resources]] | ||
Line 71: | Line 80: | ||
* <code>TypeID</code>: the access type of the port-type, as per OCMA requirements. The value of this property is constant: <code>gDocRead</code>; | * <code>TypeID</code>: the access type of the port-type, as per OCMA requirements. The value of this property is constant: <code>gDocRead</code>; | ||
* <code>Plugin</code>: the name of the bound plugin; | * <code>Plugin</code>: the name of the bound plugin; | ||
+ | * <code>Cardinality</code>: an estimate of the number of documents in the bound collection; | ||
+ | * <code>LastUpdate</code>: an estimate of the time in which the bound collection was last updated; | ||
+ | |||
+ | |||
+ | [[Image:readmanagerps.jpg|center|The <code>getByIDs</code> operation of ReadManager resources]] | ||
=== Write Managers === | === Write Managers === | ||
Line 79: | Line 93: | ||
: the operation adds a <code>gDoc</code> tree to the bound collection and returns the identifier assigned to the tree root as a result. | : the operation adds a <code>gDoc</code> 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. | : '''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. | ||
+ | |||
+ | |||
+ | [[Image:Addop.jpg|center|The <code>add</code> operation of WriteManager resources]] | ||
+ | |||
* <code>String addRS(String locator) throws GCUBEFault</code> | * <code>String addRS(String locator) throws GCUBEFault</code> | ||
: the operation adds zero or more <code>gDoc</code> trees to the bound collection and returns a locator of a ResultSet of <code>AddOutcome</code>s, 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. | : the operation adds zero or more <code>gDoc</code> trees to the bound collection and returns a locator of a ResultSet of <code>AddOutcome</code>s, 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. | : '''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. | ||
+ | |||
+ | |||
+ | [[Image:AddRSop.jpg|center|The <code>addRS</code> operation of WriteManager resources]] | ||
+ | |||
* <code>VOID update(AnyHolder holder) throws UnknownDocumentFault, InvalidDocumentFault, GCUBEFault</code> | * <code>VOID update(AnyHolder holder) throws UnknownDocumentFault, InvalidDocumentFault, GCUBEFault</code> | ||
Line 93: | Line 115: | ||
:: '''note''': <code>NEW</code> nodes are leaves or inner nodes with <code>NEW</code> descendants. | :: '''note''': <code>NEW</code> nodes are leaves or inner nodes with <code>NEW</code> descendants. | ||
:: '''note''': depending on the bound plugin, <code>NEW</code> nodes may be assigned identifiers upon being added to the target tree. | :: '''note''': depending on the bound plugin, <code>NEW</code> nodes may be assigned identifiers upon being added to the target tree. | ||
+ | |||
+ | |||
+ | [[Image:Updateop.jpg|center|The <code>update</code> operation of WriteManager resources]] | ||
+ | |||
:As an example, consider the following <code>gDoc</code> tree, where <code>status</code> attributes are depicted as node markers: | :As an example, consider the following <code>gDoc</code> tree, where <code>status</code> attributes are depicted as node markers: | ||
Line 112: | Line 138: | ||
: the operation takes the locator of a ResultSet with delta trees for zero or more target <code>gDoc</code> trees and returns the locator of a ResultSet of <code>UpdateFailure</code>s (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. | : the operation takes the locator of a ResultSet with delta trees for zero or more target <code>gDoc</code> trees and returns the locator of a ResultSet of <code>UpdateFailure</code>s (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 <code>AnyHolder</code> wrappers (see WSDL definition). | :'''note''': delta trees in input are contained in <code>AnyHolder</code> wrappers (see WSDL definition). | ||
+ | |||
+ | |||
+ | [[Image:UpdateRS.jpg|center|The <code>updateRS</code> operation of WriteManager resources]] | ||
+ | |||
A <code>WriteManager</code> resource publishes the following Resource Properties: | A <code>WriteManager</code> resource publishes the following Resource Properties: | ||
Line 118: | Line 148: | ||
* <code>TypeID</code>: the access type of the port-type, as per OCMA requirements. The value of this property is constant: <code>gDocWrite</code>; | * <code>TypeID</code>: the access type of the port-type, as per OCMA requirements. The value of this property is constant: <code>gDocWrite</code>; | ||
* <code>Plugin</code>: the name of the bound plugin; | * <code>Plugin</code>: the name of the bound plugin; | ||
+ | * <code>Cardinality</code>: an estimate of the number of documents in the bound collection; | ||
+ | * <code>LastUpdate</code>: an estimate of the time in which the bound collection was last updated; | ||
+ | |||
+ | |||
+ | [[Image:WriteManagerRPs.jpg|center|The Resource Properties of WriteManager resources]] |
Latest revision as of 13:16, 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 (ReadManager
s and/or WriteManager
s). 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 theEprList
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 anAnyHolder
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 bound collection; -
LastUpdate
: an estimate of the time in which the bound 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 ofAddOutcome
s, 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 attributehttp://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
ofMODIFIED
orDELETED
;
- 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
ofNEW
.
- note:
NEW
nodes are leaves or inner nodes withNEW
descendants. - note: depending on the bound plugin,
NEW
nodes may be assigned identifiers upon being added to the target tree.
- all the nodes of the target tree which have changed, with the corresponding identifiers and with a
- As an example, consider the following
gDoc
tree, wherestatus
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 child5
and all its descendants; - node
3
has acquired a child and its descendants; - node
4
has lost the attributez
and the child6
, while the value of its child leaf7
has changed.
- the root has acquired or changed an attribute
- 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 ofUpdateFailure
s (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;