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 FactoryCalls. 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. setCollectionID(String)).

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 GDocRSCollection may be iterated over an arbitrary number of times, as expected. Due to its lazy nature, however, the iteration may unconventionally fail at the start. note: a GDocRSCollection may be optionally created with an indication of how many elements one would like to be in it. These elements are then localised prior to iteration, using underlying ResultSet facilities. GCUBERSIterator#LOCALISE_ALL is a constant that indicates the entire ResultSet ought to be localised prior to iteration.

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: GDocRSCollection and GDocRSIterator are specialisation of more generic facilities: RSCollection<T> and RSIterator<T>, respectively, where T can be specialised to bindings other than GDoc (e.g. JAXB bindings), and in fact to results other than gDoc trees. For this, clients must define a suitable implementation of ResultParser<T>. For more details, see the code documentation.

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.