Difference between revisions of "IS-Client"
Manuele.simi (Talk | contribs) (→Custom queries) |
Manuele.simi (Talk | contribs) (→Queries) |
||
(26 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | + | == Role == | |
− | + | The <code>ISClient</code> 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. | |
− | + | <code>ISClient</code> 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-Collector|IS-InformationCollector]] service). | |
− | + | ||
− | + | == Design == | |
+ | The entry point to the ISClient is the <code>ISClient</code> interface that defines the methods for obtain query objects and send them to the IS-InformationCollector instance in scope: | ||
− | * | + | * <code>getQuery(Class<QUERY> type)</code> – which takes as input parameter the type of the query; |
− | * '' | + | * <code>getQuery(String name)</code> – which takes as input parameter the name of the query; |
− | + | * <code>execute(ISQuery<RESULT> query, GCUBEScope scope)</code> – 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 <code>org.gcube.common.core.informationsystem.client.ISQuery</code> interface. Implementing classes declare also a type parameter <code>RESULT</code> 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 <code>org.gcube.common.core.informationsystem.client.ISQuery</code> 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 <code>getQuery()</code> method has to be invoked as follows: | |
− | + | ||
− | + | ||
<source lang="java"> | <source lang="java"> | ||
ISClient client = GHNContext.getImplementation(ISClient.class); | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
− | [GCUBE...Query] query = client.getQuery([GCUBE...Query].class); | + | [GCUBE...Query] query = client.getQuery([GCUBE...Query].class | name); |
</source> | </source> | ||
− | === Queries | + | === Pre-defined Queries: Querying GCUBEResources === |
+ | |||
+ | The following queries classes are available to query over [[Reference Model|gCube Resources]]: | ||
+ | |||
+ | * <code>GCUBECollectionQuery.class</code> | ||
+ | * <code>GCUBECSInstanceQuery.class</code> | ||
+ | * <code>GCUBECSQuery.class</code> | ||
+ | * <code>GCUBEExternalRIQuery.class</code> | ||
+ | * <code>GCUBEGenericResourceQuery.class</code> | ||
+ | * <code>GCUBEGHNQuery.class</code> | ||
+ | * <code>GCUBEMCollectionQuery.class</code> | ||
+ | * <code>GCUBERIQuery.class</code> ( with the implicit filters that the returned RIs are in the ''ready'' state) | ||
+ | * <code>GCUBEServiceQuery.class</code> | ||
+ | * <code>GCUBETPQuery.class</code> | ||
+ | * <code>GCUBEVREQuery.class</code> | ||
− | + | All of them return a <code>List</code> of specialized <code>org.gcube.common.core.resources.GCUBEResource</code> objects (e.g. <code>GCUBEServiceQuery</code> returns a list of <code>GCUBEService</code> objects). | |
− | Once obtained the desired object | + | Once obtained the desired query object, the developer can add filters to better target the query on his needs. |
Supported filters are: | Supported filters are: | ||
Line 56: | Line 66: | ||
</source> | </source> | ||
− | + | ===== Sample Usage ===== | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | ===== Usage | + | |
1) The following query retrieves all the HostingNode registered in the selected scope: | 1) The following query retrieves all the HostingNode registered in the selected scope: | ||
Line 106: | Line 99: | ||
</source> | </source> | ||
− | === | + | === Pre-defined Queries: Querying WS-ResourceProperties Documents === |
+ | |||
To query over GCUBEWSResources the following query class must be used: | To query over GCUBEWSResources the following query class must be used: | ||
+ | <source lang="java"> | ||
+ | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
+ | WSResourceQuery query = client.getQuery(WSResourceQuery.class); | ||
+ | </source> | ||
− | + | As for [[IS-Client#Pre-defined_Queries:_Querying_GCUBEResources|GCUBEResourceQuery]], also WSResourceQuery objects can be further refined with <code>AtomicCondition</code> and <code>GenericCondition</code> to better target the query. | |
− | + | Once executed, the query returns a <code>List</code> of <code>RPDocument</code> objects matching the query conditions. The RPDocument exposes the following getter methods for retrieving a set of common information about the resource: | |
+ | * <code>getEndpoint()</code>, returning the source WS-Resource endpoint | ||
+ | * <code>getKey()</code>, returning the source WS-Resource key | ||
+ | * <code>getServiceID()</code>, returning the identifier of the service of the WS-Resource | ||
+ | * <code>getServiceName()</code>, returning the name of the service of origin of the WS-Resource | ||
+ | * <code>getServiceClass()</code>, returning the class of the service of origin of the WS-Resource | ||
+ | * <code>getRIID()</code>, returning the identifier of the running instance of origin of the WS-Resource | ||
+ | * <code>getGHNID()</code>, returning the identifier of the gHN of origin of the WS-Resource | ||
+ | * <code>getScope()</code>, returning the scope(s) of the WS-Resource | ||
+ | * <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. | |
− | The following example returns all the WSResources generated by the services with ServiceClass "Sample": | + | ==== Sample Usage ==== |
+ | |||
+ | The following example returns all the WSResources generated by the services with ServiceClass equals to "Sample": | ||
<source lang="java"> | <source lang="java"> | ||
Line 121: | Line 130: | ||
WSResourceQuery wsquery = client.getQuery(WSResourceQuery.class); | WSResourceQuery wsquery = client.getQuery(WSResourceQuery.class); | ||
wsquery.addAtomicConditions(new AtomicCondition("//gc:ServiceClass","Samples")); | wsquery.addAtomicConditions(new AtomicCondition("//gc:ServiceClass","Samples")); | ||
− | for (RPDocument d : client.execute(wsquery,GCUBEScope.getScope("/gcube/devsec"))) | + | for (RPDocument d : client.execute(wsquery, GCUBEScope.getScope("/gcube/devsec"))) { |
− | logger. | + | logger.info("Source EPR: " + d.getEndpoint(); |
+ | logger.info("MyRP value:" + d.evaluate(\"//MyRP\").get(0)); | ||
+ | } | ||
</source> | </source> | ||
− | + | As showed in this example, the query internally defines a ''gc'' namespace for the [[IS-Publisher#Published_Structure_of_an_instance_state|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: | ||
<source lang="java"> | <source lang="java"> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
GCUBEGenericQuery query = client.getQuery("[one of the listed queries]"); | GCUBEGenericQuery query = client.getQuery("[one of the listed queries]"); | ||
− | |||
</source> | </source> | ||
− | to | + | Depending on the query, it is also possible to customize the query by setting specific parameters. To set a parameters: |
<source lang="java"> | <source lang="java"> | ||
− | + | query.addParameters(new QueryParameter("NAME","VALUE")); | |
− | + | ||
− | + | ||
</source> | </source> | ||
− | The following queries are | + | The following queries are available with the current implementation of the ISClient: |
− | * | + | * ''GCUBEResourceQuery'' allows to query all the gCube Resources |
** parameters: | ** parameters: | ||
*** TYPE | *** TYPE | ||
*** FILTER | *** FILTER | ||
*** RESULT (the default value returns IDs) | *** RESULT (the default value returns IDs) | ||
− | * | + | * ''GCUBEWSResourceQuery'' allows to query all the Resource Properties Documents |
** parameters: | ** parameters: | ||
*** FILTER | *** FILTER | ||
*** RESULT (the default value is the entire Properties Document Data) | *** RESULT (the default value is the entire Properties Document Data) | ||
− | * | + | * ''RIEndpoint'' looks for RI's endpoints |
** parameters: | ** parameters: | ||
*** NAME filters by the Service name | *** NAME filters by the Service name | ||
*** CLASS filters by the Service class | *** CLASS filters by the Service class | ||
*** ENTRY filters by the entry point | *** ENTRY filters by the entry point | ||
− | * | + | * ''RIOnGHN'' returns all the RIs grouped by the GHN on which they are hosted |
− | **parameters | + | ** parameters |
*** ID filters by the GHN id, i.e. returns the RIs hosted on that GHN | *** ID filters by the GHN id, i.e. returns the RIs hosted on that GHN | ||
− | *RISpecificData: | + | * ''RISpecificData'': |
− | ** NAME (Service name) | + | ** parameters |
− | ** CLASS (Service class) | + | *** NAME (Service name) |
− | ** ENTRY (the entry point) | + | *** CLASS (Service class) |
− | *GHNIDFromHostName: | + | *** ENTRY (the entry point) |
− | ** NAME (GHN name) | + | * ''GHNIDFromHostName'': |
− | ** RESULT (the default value returns Ids) | + | ** parameters |
− | *InternalCollections | + | *** NAME (GHN name) |
− | *InternalCollectionIDs | + | *** RESULT (the default value returns Ids) |
− | *UserCollectionIDsFromSchemaURI | + | * ''InternalCollections'' |
− | ** URI (the schema uri) | + | * ''InternalCollectionIDs'' |
− | *MCollectionIDForCollection | + | * ''UserCollectionIDsFromSchemaURI'' |
− | ** ID (related collection ID) | + | ** parameters |
− | *MCollectionFormatsForCollection | + | *** URI (the schema uri) |
− | ** ID (related collection ID) | + | * ''MCollectionIDForCollection'' |
− | *MCollectionIDFromCollectionIDAndRole | + | ** parameters |
− | ** ID (related collection ID) | + | *** ID (related collection ID) |
− | ** ROLE (secondary role) | + | * ''MCollectionFormatsForCollection'' |
− | *MCollectionIDFromMFLanguage | + | ** parameters |
− | ** LANGUAGE (metadata format language) | + | *** ID (related collection ID) |
− | *MCollectionIDFromName | + | * ''MCollectionIDFromCollectionIDAndRole'' |
− | ** NAME (metadata collection name) | + | ** parameters |
− | *MCollectionIDFromSchemaURI | + | *** ID (related collection ID) |
− | ** URI (schema uri) | + | *** 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 <code>XMLResult</code>. Each XMLResult object allows the caller to explore the resource by invoking the <code>evaluate()</code> method and passing an XPath expression. | ||
− | + | ==== Sample Usage ==== | |
− | + | The following example shows how to retrieve all the gCube Resources in scope: | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
<source lang="java"> | <source lang="java"> | ||
ISClient client = GHNContext.getImplementation(ISClient.class); | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
− | GCUBEScope scope = | + | GCUBEScope scope = ...; |
− | GCUBEGenericQuery query = client.getQuery( | + | GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery"); |
− | + | for (XMLResult result : client.execute(query,scope)) | |
− | + | logger.debug(result.evaluate("/ID/text()"));//get the resource ID | |
− | + | ||
− | logger.debug( | + | |
− | + | ||
− | + | ||
</source> | </source> | ||
+ | |||
+ | This example that shows how to filter the previous query by using the TYPE parameter defined in the query object: | ||
<source lang="java"> | <source lang="java"> | ||
ISClient client = GHNContext.getImplementation(ISClient.class); | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
− | GCUBEScope scope = | + | GCUBEScope scope = ...; |
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery"); | GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery"); | ||
+ | query.addParameters(new QueryParameter("TYPE", GCUBERunningInstance.TYPE)); //only RunningInstances | ||
for (XMLResult result : client.execute(query,scope)) | for (XMLResult result : client.execute(query,scope)) | ||
− | + | logger.debug(result.evaluate("/ID/text()")); | |
</source> | </source> | ||
+ | Finally, a more complete example showing how to filter the same query and customize the results: | ||
− | |||
<source lang="java"> | <source lang="java"> | ||
ISClient client = GHNContext.getImplementation(ISClient.class); | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec"); | GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec"); | ||
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery"); | GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery"); | ||
− | query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE)); | + | //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)) | for (XMLResult result : client.execute(query,scope)) | ||
− | + | logger.debug(result.evaluate("//Description")); //displays a singleton list | |
+ | |||
</source> | </source> | ||
+ | === 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 | |
+ | |||
+ | <source lang="java"> | ||
+ | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
+ | GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class); | ||
+ | query.setExpression("myqueryexpression"); | ||
+ | </source> | ||
+ | |||
+ | 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 [[IS-Collector#XML_Indexing|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 [[IS-Collector#Adding_an_XML_document|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: | ||
<source lang="java"> | <source lang="java"> | ||
ISClient client = GHNContext.getImplementation(ISClient.class); | ISClient client = GHNContext.getImplementation(ISClient.class); | ||
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec"); | GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec"); | ||
− | GCUBEGenericQuery query = client.getQuery( | + | GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class); |
− | + | query.setExpression("for $Profile in collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/ID"); | |
− | query. | + | List<XMLResult> result =client.execute(query, scope); |
− | + | for (XMLResult resultItem :result ) { | |
− | + | logger.debug(resultItem.evaluate("an XPath ... ")); | |
− | + | logger.debug(resultItem.toString()); | |
− | + | } | |
− | + | ||
</source> | </source> | ||
− | + | ||
[[Category:Information System]] | [[Category:Information System]] |
Latest revision as of 14:56, 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 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)
- 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.
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)
- parameters:
- GCUBEWSResourceQuery allows to query all the Resource Properties Documents
- parameters:
- FILTER
- RESULT (the default value is the entire Properties Document Data)
- parameters:
- 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
- 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:
- parameters
- NAME (Service name)
- CLASS (Service class)
- ENTRY (the entry point)
- parameters
- GHNIDFromHostName:
- parameters
- NAME (GHN name)
- RESULT (the default value returns Ids)
- parameters
- InternalCollections
- InternalCollectionIDs
- UserCollectionIDsFromSchemaURI
- parameters
- URI (the schema uri)
- parameters
- MCollectionIDForCollection
- parameters
- ID (related collection ID)
- parameters
- MCollectionFormatsForCollection
- parameters
- ID (related collection ID)
- parameters
- MCollectionIDFromCollectionIDAndRole
- parameters
- ID (related collection ID)
- ROLE (secondary role)
- parameters
- MCollectionIDFromMFLanguage
- parameters
- LANGUAGE (metadata format language)
- parameters
- MCollectionIDFromName
- parameters
- NAME (metadata collection name)
- parameters
- MCollectionIDFromSchemaURI
- parameters
- URI (schema uri)
- parameters
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()); }