Difference between revisions of "ExistClient"

From Gcube Wiki
Jump to: navigation, search
(→‎Usage Examples)
(→‎Usage Examples)
 
(53 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
=== Introduction ===
 
=== Introduction ===
  
−
The ExistClient is a Java library that implements the ISClient interface provided by the gCoreFramework. This library allow the developer to execute queries on the Information System.
+
The ExistClient is a Java library implementing the ISClient interface defined in the gCoreFramework. Therefore it can be plugged in a gCore distribution to interface the gCube Information System.
 +
This ExistClient 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. 
 +
There are three kinds of queries to execute on the IS:
 +
* ''GCUBEResourceQuery'', to query the GCUBEResources' profiles
 +
* ''WSResourceQuery'', to query WS-ResourceProperty documents
 +
* and ''GCUBEGenericQuery'', to make custom queries
  
 +
The name of the component derives from the XQuery dialect supported, which is the one offered by the eXist XML Database on top of which it is built the gCube Information Collector component.
  
 
=== Implementation Overview ===
 
=== Implementation Overview ===
  
  
−
The ExistClient implements all the query defined in the ISClient Interface:  
+
The ExistClient implements all the queries defined in the ISClient Interface (to obtain the ExistClient implementation see [[https://wiki.gcore.research-infrastructures.eu/gCube/index.php/Advanced_Topics#Interfacing_the_Information_System ISClient Interface]] ):  
−
 
+
  
 +
==== How to query over GCUBEResource profiles ====
 
Queries over GCUBEResource:
 
Queries over GCUBEResource:
  
Line 19: Line 25:
 
*GCUBEGHNQuery
 
*GCUBEGHNQuery
 
*GCUBEMCollectionQuery
 
*GCUBEMCollectionQuery
−
*GCUBERIQuery
+
*GCUBERIQuery (Return all RI with state equals to ready)
 
*GCUBEServiceQuery
 
*GCUBEServiceQuery
 
*GCUBETPQuery
 
*GCUBETPQuery
Line 26: Line 32:
 
This queries returns a List of specialized GCUBEResource.
 
This queries returns a List of specialized GCUBEResource.
  
 +
===== Usage Examples =====
  
 +
This following query retrieves all the RunningInstances of the Service with ServiceName "ABE" in the selected scope:
 +
 +
<pre>
 +
 +
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()+")");
 +
 +
</pre>
 +
 +
 +
The following query retrieves all the HostingNode registered in the selected scope:
 +
 +
<pre>
 +
 +
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()+")");
 +
 +
</pre>
 +
 +
 +
The following query retrieves all the RunningInstances of the Service with ServiceName "GHNManager" or "SoftwareRepository":
 +
 +
<pre>
 +
 +
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>
 +
 +
==== How to query over resource property documents ====
 
Queries over GCUBEWSResource:
 
Queries over GCUBEWSResource:
  
Line 34: Line 79:
  
  
 +
To get one of GCUBEResource or  GCUBEWSResource queries:
 +
<pre>
 +
...
 +
[GCUBE...Query] query = client.getQuery([GCUBE...Query].class);   
 +
...
 +
</pre>
 +
 +
On this kind of queries the developer can reduce the number of results inserting a filter. The supported filters are:
 +
* ''AtomicCondition''
 +
** with the atomic conditions can be specified that a node with a determined path *MUST* have a specified value
 +
<pre>
 +
...  new AtomicCondition("//Endpoint/@EntryName","gcube/annotationmanagement/abe/factory")
 +
</pre>
 +
 +
* ''GenericCondition''
 +
** with the generic conditions can be specified a entire condition string (using $result as starter node of every used path)
 +
<pre>
 +
  ....addGenericCondition("$result/[path] eq '[something]' or $result/[another path] eq '[something else]'");
 +
</pre>
 +
 +
 +
 +
===== Usage Example =====
 +
 +
The following example returns all the WSResources generated by the services with ServiceClass "Sample":
 +
 +
<pre>
 +
 +
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));
 +
 +
</pre>
 +
 +
==== Custom queries ====
  
−
The ExistClient also offers the possibility to execute custom queries: GCUBEGenericQuery.
+
The ExistClient also offers the possibility to execute custom queries: ''GCUBEGenericQuery''.
 
GCUBEGenericQuery allows the developer to set the query expression to execute and to use a predefined set of queries which he should set some parameters on listed below:  
 
GCUBEGenericQuery allows the developer to set the query expression to execute and to use a predefined set of queries which he should set some parameters on listed below:  
  
−
*GCUBEResourceQuery  
+
*GCUBEResourceQuery:
−
*GCUBEWSResourceQuery  
+
** TYPE
−
*RIEndpoint  
+
** FILTER
−
*RIOnGHN  
+
** RESULT (the default value returns Ids)
−
*RISpecificData
+
*GCUBEWSResourceQuery:
−
*GHNIDFromHostName
+
** FILTER
 +
** RESULT (the default value is the entire  Properties Document Data)
 +
*RIEndpoint:
 +
** NAME (Service name)
 +
** CLASS (Service class)
 +
** ENTRY (the entry point)
 +
*RIOnGHN:
 +
** ID (the GHN id)
 +
*RISpecificData:
 +
** NAME (Service name)
 +
** CLASS (Service class)
 +
** ENTRY (the entry point)
 +
*GHNIDFromHostName:
 +
** NAME (GHN name)
 +
** RESULT (the default value returns Ids)
 
*InternalCollections
 
*InternalCollections
 +
*InternalCollectionIDs
 
*UserCollectionIDsFromSchemaURI
 
*UserCollectionIDsFromSchemaURI
 +
** URI (the schema uri)
 
*MCollectionIDForCollection
 
*MCollectionIDForCollection
 +
** ID (related collection ID)
 
*MCollectionFormatsForCollection
 
*MCollectionFormatsForCollection
 +
** ID (related collection ID)
 
*MCollectionIDFromCollectionIDAndRole
 
*MCollectionIDFromCollectionIDAndRole
−
*MCollectionIDFromFormatLanguage
+
** ID (related collection ID)
−
*MCollectionIDFromFormatLanguage
+
** ROLE (secondary role)
 +
*MCollectionIDFromMFLanguage
 +
** LANGUAGE (metadata format language)
 
*MCollectionIDFromName
 
*MCollectionIDFromName
 +
** NAME (metadata collection name)
 
*MCollectionIDFromSchemaURI
 
*MCollectionIDFromSchemaURI
 +
** URI (schema uri)
  
  
 
This kind of queries returns a List of XMLResult. The XMLResult object allows the developer to explore the contained document with XPaths.
 
This kind of queries returns a List of XMLResult. The XMLResult object allows the developer to explore the contained document with XPaths.
−
 
+
To get a predefined generic query:
−
=== Usage Examples ===
+
−
 
+
−
Query over GCUBEResource examples:
+
−
 
+
 
<pre>
 
<pre>
 +
...
 +
GCUBEGenericQuery query = client.getQuery("[one of the listed queries]");   
 +
...
 +
</pre>
 +
to set the parameters:
 +
<pre>
 +
...
 +
query.addParameters(new QueryParameter("[parameter to set]","[value]"), new QueryParameter("[parameter to set]","[value ...]"));
 +
...
 
</pre>
 
</pre>
  
  
−
Query over WSResource examples:
 
  
−
<pre>
+
===== Usage Example =====
−
</pre>
+
  
−
GCUBEGenericQuery example:
+
The first two examples are queries used to retrieve all the IDs of the profiles stored on the DB:  
  
 
<pre>
 
<pre>
  
 +
ISClient client = GHNContext.getImplementation(ISClient.class);
 +
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
 
GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);
 
GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);
−
query.setExpression("for $Profile in collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");
+
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);
 
List<XMLResult> result =client.execute(query, scope);
−
for (String resultItem :result ) {
+
for (XMLResult resultItem :result ) {
−
System.out.println(resultItem.evaluate("an XPath ... "));  
+
logger.debug(resultItem.evaluate("an XPath ... "));  
−
System.out.println(resultItem.toString());
+
logger.debug(resultItem.toString());
 
}
 
}
  
 
</pre>
 
</pre>
−
 
−
Predefined generic query examples:
 
−
 
 
<pre>
 
<pre>
  
 +
ISClient client = GHNContext.getImplementation(ISClient.class);
 +
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
 
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
 
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
 
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/ID/text()"));//displays a singleton list
 
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/ID/text()"));//displays a singleton list
−
//a bit of customisation goes a long way whilst keeping the previous abstractions
 
−
query.addParameters(new QueryParameter("RESULT","$result/Type"));
 
−
for (XMLResult result : client.execute(query, scope)) logger.debug(result.evaluate("/Type/text()"));
 
  
−
//specialise to GCUBE Running Instances (NB. queries can be composed incrementally, possibly by different objects in different methods)
+
</pre>
 +
 
 +
 
 +
 
 +
This example represents how to retrieve Profiles IDs for all RunningInstances:
 +
<pre>
 +
 
 +
ISClient client = GHNContext.getImplementation(ISClient.class);
 +
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
 +
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
 
query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE));  
 
query.addParameters(new QueryParameter("TYPE",GCUBERunningInstance.TYPE));  
 
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/Type/text()"));
 
for (XMLResult result : client.execute(query,scope)) logger.debug(result.evaluate("/Type/text()"));
−
//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
 
  
 
</pre>
 
</pre>
  
−
You can use a predefined ISQuery Object as well:
 
  
 +
This Example describes how to retrieve profiles Descriptions for all the RunningInstances Profiles of all the services with ServiceClass "Annotation":
 
<pre>
 
<pre>
  
−
GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery query = client.getQuery(GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery.class);  
+
ISClient client = GHNContext.getImplementation(ISClient.class);
−
GCUBEWSProperty property = new GCUBEWSProperty("IndexTypeName","index_type_string_string");
+
GCUBEScope scope = GCUBEScope.getScope("/gcube/devsec");
−
 
+
GCUBEGenericQuery query = client.getQuery("GCUBEResourceQuery");
−
GCUBEWSProperty property2 = new GCUBEWSProperty("IndexID","999ba610-e9fb-11dc-b51b-84732c1e88f2");
+
//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
  
−
ArrayList <GCUBEWSProperty> properties = new ArrayList();
 
−
properties.add(property);
 
−
properties.add(property2);
 
−
query.setPropertiesValuesAndNamespace(properties, "http://gcube-system.org/namespaces/index/ForwardIndexManagementService");
 
−
 
−
List<EndpointReferenceType> result = client.execute(query, scope);
 
−
 
−
for (EndpointReferenceType resultItem :result ) {
 
−
System.out.println(resultItem.toString());
 
−
 
−
}
 
 
</pre>
 
</pre>

Latest revision as of 16:31, 3 June 2009

Introduction

The ExistClient is a Java library implementing the ISClient interface defined in the gCoreFramework. Therefore it can be plugged in a gCore distribution to interface the gCube Information System. This ExistClient 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. There are three kinds of queries to execute on the IS:

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

The name of the component derives from the XQuery dialect supported, which is the one offered by the eXist XML Database on top of which it is built the gCube Information Collector component.

Implementation Overview

The ExistClient implements all the queries defined in the ISClient Interface (to obtain the ExistClient implementation see [ISClient Interface] ):

How to query over GCUBEResource profiles

Queries over GCUBEResource:

  • GCUBECollectionQuery
  • GCUBECSInstanceQuery
  • GCUBECSQuery
  • GCUBEExternalRIQuery
  • GCUBEGenericResourceQuery
  • GCUBEGHNQuery
  • GCUBEMCollectionQuery
  • GCUBERIQuery (Return all RI with state equals to ready)
  • GCUBEServiceQuery
  • GCUBETPQuery
  • GCUBEVREQuery

This queries returns a List of specialized GCUBEResource.

Usage Examples

This following query retrieves all the RunningInstances of the Service with ServiceName "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()+")");


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


The following query retrieves all the RunningInstances of the Service with ServiceName "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

Queries over GCUBEWSResource:

  • WSResourceQuery

This query returns a List of RPDocument. The RPDocument object allows developer to retrieve the informations on WSResourceProperties or to exceute XPath .


To get one of GCUBEResource or GCUBEWSResource queries: 

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

On this kind of queries the developer can reduce the number of results inserting a filter. The supported filters are:

  • AtomicCondition
    • with the atomic conditions can be specified that a node with a determined path *MUST* have a specified value
 ...   new AtomicCondition("//Endpoint/@EntryName","gcube/annotationmanagement/abe/factory")
  • GenericCondition
    • with the generic conditions can be specified a entire condition string (using $result as starter node of every used path)
  ....addGenericCondition("$result/[path] eq '[something]' or $result/[another path] eq '[something else]'");


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 ExistClient also offers the possibility to execute custom queries: GCUBEGenericQuery. GCUBEGenericQuery allows the developer to set the query expression to execute and to use a predefined set of queries which he should set some parameters on listed below:

  • GCUBEResourceQuery:
    • TYPE
    • FILTER
    • RESULT (the default value returns Ids)
  • GCUBEWSResourceQuery:
    • FILTER
    • RESULT (the default value is the entire Properties Document Data)
  • RIEndpoint:
    • NAME (Service name)
    • CLASS (Service class)
    • ENTRY (the entry point)
  • RIOnGHN:
    • ID (the GHN id)
  • 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 kind of queries returns a List of XMLResult. The XMLResult object allows the developer to explore the contained document with XPaths. To get a predefined generic query: 

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

to set the parameters: 

 ... 
 query.addParameters(new QueryParameter("[parameter to set]","[value]"), new QueryParameter("[parameter to set]","[value ...]"));
 ...


Usage Example

The first two examples are queries used to retrieve all the IDs of the profiles stored on the DB: 


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


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


This Example describes how to retrieve profiles Descriptions for all the RunningInstances Profiles of all the services with ServiceClass "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
Retrieved from "https://wiki.gcube-system.org/index.php?title=ExistClient&oldid=6672"