Content Manager Library
ReadManager Calls
A ReadManagerCall
gives high-level write access to the content of a given collection, as allowed by a ReadManager
resource bound to that collection.
It follows the same patterns already illustrated for FactoryCall
s. In particular, it is created in a scope and, optionally, with a security manager.
//some scope GCUBEScope scope = ..... ReadManagerCall call = new ReadManagerCall(scope); //some security manager = .... GCUBESecurityManager manager = .... ReadManagerCall secureCall = new ReadManagerCall(scope,manager);
As a further option, it may be crated with the identifier of the target collection:
//some scope GCUBEScope scope = ..... ReadManagerCall call = new ReadManagerCall("... some collection identifier ...",scope); //some security manager = .... GCUBESecurityManager manager = .... ReadManagerCall secureCall = new ReadManagerCall("... some collection identifier ...",scope,manager);
note: the collection identifier may also be set after call construction (cf. |
The call object may be configured as a FactoryCall
, i.e. setting reference to resource endpoint for targeted interactions (cf. setEndpointReference(EndpointReference)
), or else relying on implicit discovery and best-effort strategy. In the latter case, the query that underlie the strategy can be customised and reset (cf. getQuery()
,resetQuery()
).
The call object may then be used to retrieve gDoc
trees from the target collection. To this end, its operations may be classified in two groups: the those that return single trees and those that return multiple trees. The first class includes lookup operations while the second class includes both lookup and query operations based on tree predicates. Multi-valued operations are execute asynchronously at the service, based on the ResultSet mechanism.
The following example illustrates the use single-valued lookups:
//synchronous: return one gDoc tree GDoc doc1 = call.get("... tree root identifier ..."); //some tree predicate to use for pruning Predicate projection = .... //synchronous: prune and return one gDoc tree GDoc doc2 = call.get("... tree root identifier ...",projection);
Here, get(String)
and get(String,Predicate)
bind the output tree to the object model of gDoc
tree API.
We note that there are semantically equivalent operations that return DOM bindings, so as to raise no further parsing costs if a binding other than to the gDoc
tree API is required upstream (cf. getAsElement(String)
and getAsElement(String,Predicate)
).
Muti-valued lookups may be exemplified as follows:
//a locator to a ResultSet of tree root identifiers, produced using standard ResultSet production idioms RSLocator identifiers = .... //asynchronous: returns a locator to a remote ResultSet of gDoc trees with given identifiers RSLocator locator1 = call.get(identifiers); //asynchronous: returns a locator to a remote ResultSet of gDoc trees with given identifiers, pruned by a tree predicate RSLocator locator2 = call.get(identifiers,predicate);
The ResultSets returned by the lookups contain XML representations of gDoc
trees. Standard ResultSet consumption idioms may then be used to extract the XML representations and bind them to object models of choice. The library supports more transparent idioms, however:
//a locator to a ResultSet of gDoc trees. RSLocator locator = .... GDocRSCollection docs = new GDocRSCollection(locator); //use standard for (GDoc doc : doc) ...process document...
Here, GDocRSCollection
is a collection of gDoc
trees which is backed by the ResultSet identified by the locator. The collection is 'lazily' assembled, in that it does not allow direct access to its elements, but can only be iterated over with standard language idioms, as shown. The iteration subsumes XML bindings to the native object model and hides binding failures in the process. Clients that wish to process failures can do so asynchronously with respect to the iteration, by previously registering a FaultListener
with the collection (e.g. at construction time):
//a locator to a ResultSet of gDoc trees. RSLocator locator = .... FaultListener listener = new FaultListener() { @Override void onFault(String unparsedResult, Throwable failure) {...process failure...} } GDocRSCollection docs = new GDocRSCollection(locator, listener); for (GDoc doc : doc) ...process document...
note: a note: a |
Clients which are not well-served by the asynchronous delivery of failures can instead opt for a GDocRSIterator
, which again offers binding transparencies but delivers failures synchronously:
//a locator to a ResultSet of gDoc trees. RSLocator locator = .... GDocRSIterator it = new GDocRSCollection(iterator); while (it.hasNext) { ... try { GDoc doc = it.next(); ....process document... } catch (Throwable failure) { ...handle failure... } ... }
note: |
Finally, we give an example of queries for gDoc
trees:
//asynchronous: return a locator to a remote ResultSet of many gDoc trees pruned by a tree predicate RSLocator locator3 = call.get(projection); //some tree predicate to use for filtering Predicate filter = .... //asynchronous: return a locator to a remote ResultSet of many pruned gDoc trees that satisfy a given filter RSLocator locator4= call.get(projection,filter); //asynchronous: return a locator to a remote ResultSet of all the gDoc trees in the collection RSLocator locator5 = call.get();
Again, the ResultSets returned by the queries can be consumed with standard ResultSet consumption idioms.