Difference between revisions of "IS-Client"
Manuele.simi (Talk | contribs) (→Design) |
Manuele.simi (Talk | contribs) (→Queries) |
||
Line 13: | Line 13: | ||
=== Queries === | === 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 === | === How to get a query object === |
Revision as of 00:17, 14 April 2011
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)
- with the generic conditions can be specified an entire condition expression (using
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 submit a Generic Query:
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 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)
- parameters:
-
GCUBEWSResourceQuery
allows to query all the Resource Properties Documents- parameters:
- FILTER
- RESULT (the default value is the entire Properties Document Data)
- parameters:
-
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
- parameters:
-
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
- parameters
- 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