ExistClient

Introduction

The ExistClient is a Java library implementing the ISClient interface defined in the gCoreFramework. Therefore it can be plugged in a gCore distribution to interface the gCube Information System. This ExistClient implementation reduces possible range of queries (statically implemented), each of them has a template as more generic as possible. This has been thought for covering all the main cases, enabling the user to create dynamically the query as he/she likes better enriching the query with the parameters he/she needs. There are three kinds of queries to execute on the IS:

• GCUBEResourceQuery, to query the GCUBEResources' profile
• WSResourceQuery, to query WS-ResourceProperty documents
• and GCUBEGenericQuery, to make custom queries

Implementation Overview

The ExistClient implements all the queries defined in the ISClient Interface:

Queries over GCUBEResource:

• GCUBECollectionQuery
• GCUBECSInstanceQuery
• GCUBECSQuery
• GCUBEExternalRIQuery
• GCUBEGenericResourceQuery
• GCUBEGHNQuery
• GCUBEMCollectionQuery
• GCUBERIQuery
• GCUBEServiceQuery
• GCUBETPQuery
• GCUBEVREQuery

This queries returns a List of specialized GCUBEResource.

Queries over GCUBEWSResource:

• WSResourceQuery

This query returns a List of RPDocument. The RPDocument object allows developer to retrieve the informations on WSResourceProperties or to exceute XPath .

To get one of GCUBEResource or GCUBEWSResource queries:

 ... 
 [GCUBE...Query] query = client.getQuery([GCUBE...Query].class);    
 ... 

On this kind of queries the developer can reduce the number of results inserting a filter. Two type of filter are supported on this implementation:

• AtomicCondition
  • with the atomic conditions can be specified that a node with a determined path *MUST* have a specified value

 ...   new AtomicCondition("//Endpoint@EntryName","gcube/annotationmanagement/abe/factory")

• GenericCondition
  • with the generic conditions can be specified a entire condition string (using $result as starter node of every used path)

  ....addGenericCondition("$result/[path] eq '[something]' or $result/[another path] eq '[something else]'");

The ExistClient also offers the possibility to execute custom queries: GCUBEGenericQuery. GCUBEGenericQuery allows the developer to set the query expression to execute and to use a predefined set of queries which he should set some parameters on listed below:

• GCUBEResourceQuery:
  • TYPE
  • FILTER
  • RESULT (the default value returns Ids)
• GCUBEWSResourceQuery:
  • FILTER
  • RESULT (the default value is the entire Properties Document Data)
• RIEndpoint:
  • NAME (Service name)
  • CLASS (Service class)
  • ENTRY (the entry point)
• RIOnGHN:
  • ID (the GHN id)
• RISpecificData:
  • NAME (Service name)
  • CLASS (Service class)
  • ENTRY (the entry point)
• GHNIDFromHostName:
  • NAME (GHN name)
  • RESULT (the default value returns Ids)
• InternalCollections
• InternalCollectionIDs
• UserCollectionIDsFromSchemaURI
  • URI (the schema uri)
• MCollectionIDForCollection
  • ID (related collection ID)
• MCollectionFormatsForCollection
  • ID (related collection ID)
• MCollectionIDFromCollectionIDAndRole
  • ID (related collection ID)
  • ROLE (secondary role)
• MCollectionIDFromMFLanguage
  • LANGUAGE (metadata format language)
• MCollectionIDFromName
  • NAME (metadata collection name)
• MCollectionIDFromSchemaURI
  • URI (schema uri)

This kind of queries returns a List of XMLResult. The XMLResult object allows the developer to explore the contained document with XPaths. To get a predefined generic query:

 ... 
 GCUBEGenericQuery query = client.getQuery("[one of the listed queries]");    
 ... 

to set the parameters:

 ... 
 query.addParameters(new QueryParameter("[parameter to set]","[value]"), new QueryParameter("[parameter to set]","[value ...]"));
 ...

Usage Examples

Query over GCUBEResource examples:

GCUBERIQuery RIquery = client.getQuery(GCUBERIQuery.class);
RIquery.addAtomicConditions(new AtomicCondition("//Endpoint@EntryName","gcube/annotationmanagement/abe/factory"),new AtomicCondition("//ServiceName","ABE"));
for (GCUBERunningInstance instance : client.execute(RIquery,GCUBEScope.getScope("/gcube/devsec")))
logger.debug(instance.getServiceName()+"("+instance.getID()+")");

GCUBEGHNQuery GHNquery = client.getQuery(GCUBEGHNQuery.class);
for (GCUBEHostingNode node : client.execute(GHNquery,GCUBEScope.getScope("/gcube/devsec"))) l
logger.debug(node.getID()+"("+node.getNodeDescription().getName()+")");

GCUBERIQuery RIquery = client.getQuery(GCUBERIQuery.class);
RIquery.addGenericCondition("$result/Profile/ServiceName/string() eq 'GHNManager' or $result/Profile/ServiceName/string() eq 'SoftwareRepository'");
for (GCUBERunningInstance instance : client.execute(RIquery,GCUBEScope.getScope("/gcube/devsec")))
                      logger.debug(instance.getServiceName()+"("+instance.getID()+")");

Query over WSResource examples:

WSResourceQuery wsquery = client.getQuery(WSResourceQuery.class);
wsquery.addAtomicConditions(new AtomicCondition("//ServiceClass","Samples"));
for (RPDocument d : client.execute(wsquery,GCUBEScope.getScope("/gcube/devsec"))) 
logger.(d.getEndpoint()+":+d.getVO()+":"d.evaluate("//MyRP").get(0));

GCUBEGenericQuery example:

GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);
query.setExpression("for $Profile in collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");
List<XMLResult> result =client.execute(query, scope);
for (String resultItem :result ) {
logger.debug(resultItem.evaluate("an XPath ... ")); 
logger.debug(resultItem.toString());
}

Predefined generic query examples:

GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/ID/text()"));//displays a singleton list
//a bit of customisation goes a long way whilst keeping the previous abstractions
query.addParameters(new QueryParameter("RESULT","$result/Type"));
for (XMLResult result : client.execute(query, scope)) logger.debug(result.evaluate("/Type/text()"));

//specialise to GCUBE Running Instances (NB. queries can be composed incrementally, possibly by different objects in different methods)
query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE)); 
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/Type/text()"));
//introduce a filter (NB. parameters can be added in batches) 
query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE), //ovverride previous setting
     new QueryParameter("FILTER","$result/Profile/ServiceClass/string() eq 'Annotation'"),
     new QueryParameter ("RESULT", "$result/Profile/Description")); //any Xquery condition on $result would do
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("//Description")); //displays a singleton list