IS-Client

Role

The ISClient is set of interfaces, templates and abstract classes defined in the context of the gCore Framework to decouple gCube Services from the specific implementation of the Information System. They globally model the way in which a gCube service can discover resources belonging an infrastructure. ISClient is also the name of the main interface for retrieving and sending queries. A reference implementation of them is provided with the gHN to interact with the concrete IS services.

Design

The ISClient interface exposes the following methods:

• getQuery(Class<QUERY> type) – which takes as input parameter the type of the query;
• getQuery(String name) – which takes as input parameter the name of the query;
• execute(ISQuery<RESULT> query, GCUBEScope scope) – which takes as input parameter the query and the scope and returns the list of Information Service entries matching the query.

Queries

There are three types of queries:

• pre-defined (or template) queries (GCUBEResourceQuery or WSResourceQuery)
• named queries
• caller-defined queries (GCUBEGenericQuery)

How to get a query object

Each query is modeled by a class implementing the org.gcube.common.core.informationsystem.client.ISQuery interface. Query object are not directly instantiated but must be obtained by the ISClient library. To get any of the query objects described in the following, the getQuery() method has to be invoked as follows:

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

The ISClient library comes also with a set of named queries. The related query object can be retrieved as follows:

 String name = ...;
 ISClient client = GHNContext.getImplementation(ISClient.class);
 [GCUBE...Query] query = client.getQuery(name);

Queries over resources

Filters on resources' queries

Once obtained the desired object to query over GCUBE Resource or WSRP Documents, the developer can add filters to target the query on his/her needs.

Supported filters are:

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

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

• GenericCondition
  • with the generic conditions can be specified an entire condition expression (using $result as starting node of every used path)

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

How to query over GCUBEResource profiles

The following queries classes are available to query over GCUBEResources:

• GCUBECollectionQuery
• GCUBECSInstanceQuery
• GCUBECSQuery
• GCUBEExternalRIQuery
• GCUBEGenericResourceQuery
• GCUBEGHNQuery
• GCUBEMCollectionQuery
• GCUBERIQuery (return all RI with state equals to ready)
• GCUBEServiceQuery
• GCUBETPQuery
• GCUBEVREQuery

All of them return a List of specialized GCUBE Resources's objects.

Usage Examples

1) The following query retrieves all the HostingNode registered in the selected scope:

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

2) The following query retrieves all the RunningInstances of the Service with ServiceName equals to "ABE" in the selected scope:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBERIQuery RIquery = client.getQuery(GCUBERIQuery.class);
RIquery.addAtomicConditions(new AtomicCondition("//ServiceName","ABE"));
for (GCUBERunningInstance instance : client.execute(RIquery,GCUBEScope.getScope("/gcube/devsec")))
   logger.debug(instance.getServiceName()+"("+instance.getID()+")");

3) The following query retrieves all the RunningInstances of the Service with ServiceName equals to "GHNManager" or "SoftwareRepository":

ISClient client = GHNContext.getImplementation(ISClient.class);
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()+")");

How to query over resource property documents

To query over GCUBEWSResources the following query class must be used:

• WSResourceQuery

The query returns a List of RPDocument object. The RPDocuments allows developer to retrieve information on WSResourceProperties or to execute XPath over its content.

Usage Example

The following example returns all the WSResources generated by the services with ServiceClass "Sample":

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

Named queries

get and use one of the predefined generic queries. Depending on the query, it is also possible to customize the query by setting specific parameters.

To get a predefined generic query:

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

to set the parameters:

query.addParameters(new QueryParameter("NAME","VALUE"));

The following queries are distributed with this implementation of the ISClient interface:

• GCUBEResourceQuery allows to query all the GCUBE Resources
  • parameters:
    • TYPE
    • FILTER
    • RESULT (the default value returns IDs)
• GCUBEWSResourceQuery allows to query all the Resource Properties Documents
  • parameters:
    • FILTER
    • RESULT (the default value is the entire Properties Document Data)
• RIEndpoint searches for RI's endpoints
  • parameters:
    • NAME filters by the Service name
    • CLASS filters by the Service class
    • ENTRY filters by the entry point
• RIOnGHN returns all the RIs grouped by the GHN on which they are hosted
  • parameters
    • ID filters by the GHN id, i.e. returns the RIs hosted on that GHN
• 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 class of queries returns a List of XMLResult. The XMLResult object allows the developer to explore the contained document with XPaths by invoking the evaluate() method.

For example:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
for (XMLResult result : client.execute(query,scope)) 
   logger.debug(result.evaluate("/ID/text()"));//displays a singleton list

Another example that shows the usage of the parameters:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE)); //only RunningInstances
for (XMLResult result : client.execute(query,scope)) 
      logger.debug(result.evaluate("/ID/text()"));

Finally, a more complete example showing how to retrieve profiles' Description for all the RunningInstances profiles with ServiceClass equals to "Annotation":

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
//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

Client-defined queries

The library also offers the possibility to execute generic queries by loading a GCUBEGenericQuery object and then set the whole query expression as follows

ISClient client =  GHNContext.getImplementation(ISClient.class);
GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);
query.setExpression("myqueryexpression");

The following example show how to retrieve the IDs of all the profiles stored on the Information System with a custom query:

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