Difference between revisions of "IS-Client"
Manuele.simi (Talk | contribs) (→Pre-defined Queries: Querying WS-ResourceProperties Documents) |
Manuele.simi (Talk | contribs) (→Pre-defined Queries: Querying WS-ResourceProperties Documents) |
||
Line 120: | Line 120: | ||
* <code>getTerminationTime()</code>, returning the termination time of the WS-ResourceProperties document | * <code>getTerminationTime()</code>, 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 ==== | ==== Sample Usage ==== |
Revision as of 05:02, 14 April 2011
Contents
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 the list of Information Service entries 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 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 | 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)
- 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]'");
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.
The query returns a List
of RPDocument
objects. 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 "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 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)
- 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 XPath expressions by invoking the evaluate()
method.
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()"));//displays a singleton list
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()); }