Difference between revisions of "IS-Client"

Latest revision as of 15:56, 14 April 2011

Role

The ISClient is set of interfaces, templates and abstract classes defined in the context of the gCore Framework to model the discovery of resources belonging an infrastructureon the IS. ISClient is also the name of the main interface for retrieving and sending queries.

A reference implementation of the ISClient is provided with the gHN distribution to interact with the concrete IS services (namely the IS-InformationCollector service).

Design

The entry point to the ISClient is the ISClient interface that defines the methods for obtain query objects and send them to the IS-InformationCollector instance in scope:

• 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 a list of RESULT matching the query.

Queries cannot be instantiated with constructors as standard Java objects. They rather need to be obtained from the ISClient. A query object is an instance of a class implementing the org.gcube.common.core.informationsystem.client.ISQuery interface. Implementing classes declare also a type parameter RESULT indicating the type of the expected results. When the query is passed to the execute() method, instances of this type are returned.

Depending on the query, parameters and/or filters can be set to the query object to add further conditions.

Queries

There are three types of queries:

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

Each query is modeled by a class implementing the org.gcube.common.core.informationsystem.client.ISQuery interface. Query objects 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 | name);

Pre-defined Queries: Querying GCUBEResources

The following queries classes are available to query over gCube Resources:

• GCUBECollectionQuery.class
• GCUBECSInstanceQuery.class
• GCUBECSQuery.class
• GCUBEExternalRIQuery.class
• GCUBEGenericResourceQuery.class
• GCUBEGHNQuery.class
• GCUBEMCollectionQuery.class
• GCUBERIQuery.class ( with the implicit filters that the returned RIs are in the ready state)
• GCUBEServiceQuery.class
• GCUBETPQuery.class
• GCUBEVREQuery.class

All of them return a List of specialized org.gcube.common.core.resources.GCUBEResource objects (e.g. GCUBEServiceQuery returns a list of GCUBEService objects).

Once obtained the desired query object, the developer can add filters to better target the query on his 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]'");

Sample Usage

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()+")");

Pre-defined Queries: Querying WS-ResourceProperties Documents

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

 ISClient client = GHNContext.getImplementation(ISClient.class);
 WSResourceQuery query = client.getQuery(WSResourceQuery.class);

As for GCUBEResourceQuery, also WSResourceQuery objects can be further refined with AtomicCondition and GenericCondition to better target the query.

Once executed, the query returns a List of RPDocument objects matching the query conditions. The RPDocument exposes the following getter methods for retrieving a set of common information about the resource:

• getEndpoint(), returning the source WS-Resource endpoint
• getKey(), returning the source WS-Resource key
• getServiceID(), returning the identifier of the service of the WS-Resource
• getServiceName(), returning the name of the service of origin of the WS-Resource
• getServiceClass(), returning the class of the service of origin of the WS-Resource
• getRIID(), returning the identifier of the running instance of origin of the WS-Resource
• getGHNID(), returning the identifier of the gHN of origin of the WS-Resource
• getScope(), returning the scope(s) of the WS-Resource
• getTerminationTime(), returning the termination time of the WS-ResourceProperties document

Typically, a caller has also to access the values of the Resource Properties inside the document and this can be done by invoking the evaluate() method of the RPDocument object. This method accepts and executes an XPath expression on the WS-ResourceProperties document encapsulated inside the RPDocument.

Sample Usage

The following example returns all the WSResources generated by the services with ServiceClass equals to "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.info("Source EPR: " + d.getEndpoint();
    logger.info("MyRP value:" + d.evaluate(\"//MyRP\").get(0));
}

As showed in this example, the query internally defines a gc namespace for the RPs added by the IS-Publisher that can be used to create filters on them.

Named queries

Named queries are widely used queries that are distributed with the ISClient to easy the caller's life. They are identified by a name and from the implementation point of view they are GCUBEGenericQuery instances with an already injected query expression.

To get a named query:

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

Depending on the query, it is also possible to customize the query by setting specific parameters. To set a parameters:

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

The following queries are available with the current implementation of the ISClient:

• 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 looks 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:
  • parameters
    • NAME (Service name)
    • CLASS (Service class)
    • ENTRY (the entry point)
• GHNIDFromHostName:
  • parameters
    • NAME (GHN name)
    • RESULT (the default value returns Ids)
• InternalCollections
• InternalCollectionIDs
• UserCollectionIDsFromSchemaURI
  • parameters
    • URI (the schema uri)
• MCollectionIDForCollection
  • parameters
    • ID (related collection ID)
• MCollectionFormatsForCollection
  • parameters
    • ID (related collection ID)
• MCollectionIDFromCollectionIDAndRole
  • parameters
    • ID (related collection ID)
    • ROLE (secondary role)
• MCollectionIDFromMFLanguage
  • parameters
    • LANGUAGE (metadata format language)
• MCollectionIDFromName
  • parameters
    • NAME (metadata collection name)
• MCollectionIDFromSchemaURI
  • parameters
    • URI (schema uri)

All the queries above return a List of XMLResult. Each XMLResult object allows the caller to explore the resource by invoking the evaluate() method and passing an XPath expression.

Sample Usage

The following example shows how to retrieve all the gCube Resources in scope:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBEScope scope = ...;
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
for (XMLResult result : client.execute(query,scope)) 
   logger.debug(result.evaluate("/ID/text()"));//get the resource ID

This example that shows how to filter the previous query by using the TYPE parameter defined in the query object:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBEScope scope = ...;
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 filter the same query and customize the results:

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), //override previous setting
     new QueryParameter("FILTER","$result/Profile/ServiceClass/string() eq 'Annotation'"), //we want only Annotation RIs
     new QueryParameter ("RESULT", "$result/Profile/Description")); //we get only the Description element
for (XMLResult result : client.execute(query,scope)) 
    logger.debug(result.evaluate("//Description")); //displays a singleton list

Caller-defined queries

The library also offers the possibility to execute custom 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");

Custom queries can be over gCube Resource as well as WS-ResourceProperties documents. However, in order to successfully create them, the client has to be aware of the how the XML database organization on the IS-InformationCollector in order to target the proper collection or sub-collection of resources. Moreover, these queries can be used to retrieve generic XML Documents.

Sample Usage

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());
}