Difference between revisions of "IS-Client"

Revision as of 21:41, 31 August 2010

ISClient Interface is an interface defined in the context of the gCore Framework to decouple gCube Services from the specific implementation of the Information Service. In conjunction with the IS-Publisher it represents the mediation layer gCube Services will rely on to interact with the Information Service as a whole. Such interfaces implement respectively the production/publishing (IS-Publisher) and the consumption/query (IS-Client).

Interface

There are two main methods defined in the ISClient interface:

• getQuery() – which takes as input parameter a message characterising the interface implementation to be used and instructing the framework to use it (by relying on the dynamic class loader mechanism);
• execute() – which takes as input parameter a message containing a query, a query scope and a context the requestor is operating in and returns the list of Information Service entries matching the query and the rest of constraints.

In addition, the interface defines a list of query typologies (a.k.a. templates) that must be implemented for the most popular queries grouped in these 3 classes:

• gCube Resources query, i.e. a query template to identify gCube Resources by imposing constraints on their profiles. For each existing gCube Resource a query template of this type exists, e.g. there is a GCUBERIQuery for issuing queries on Running Instance Resources, GCUBEGHNQuery for issuing queries on gHN Resources;
• WS-Resource query, i.e. a query template to identify properties exposed through WS-ResourceProperty;
• generic query, i.e. a query template to execute custom queries on the entries stored in the Information Service.

Implementation Overview

The IS-Client component is a Java library implementing the ISClient interface defined in the gCore Framework. Therefore it can be plugged in a gCore distribution to interface the gCube Information System. This IS-Client 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.

The following classes of queries can be executed against the IS's content:

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

All the queries defined in the ISClient Interface are implemented by the library.

Moreover, it is possible to define custom queries; for this, the component supports the XQuery dialect offered by the eXist XML Database.

How to get a query object

Before to execute a query, the related object has to be obtained by the ISClient library. To get any of the query objects described in the following, the getQuery() method has to be invoked on the ISClient implementation as follows:

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

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

Custom queries

The library also offers the possibility to execute generic queries by loading a GCUBEGenericQuery object.

There exist two ways to use the Generic Queries:

1. get the GCUBEGenericQuery implementation and then set the whole query expression as follows:

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

2. get and use one of the predefined generic queries. Depending on the query, it is also possible to further 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.

Usage Example

1) The following two examples show how to retrieve the IDs of all the profiles stored on the Information System:

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

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

2) This example represents how to retrieve Profiles IDs for all RunningInstances:

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

3) This example describes how to retrieve profiles' Description for all the RunningInstances profiles instance of services 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