Resource Registry Service - Query & Access
From Gcube Wiki
Revision as of 14:37, 6 July 2021 by Luca.frosini (Talk | contribs)
This section provides information regarding how to interact with Resource Registry Service for Query and Access. REST and JAVA API are presented for each functionality.
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.
Query & Access Collection
| Operation | HTTP Method | URL |
|---|---|---|
| List Contexts | GET | /access/contexts
|
| Read Context | GET | /access/contexts/{UUID}
|
| Read Type | GET | /access/types/{TYPE_NAME}[?polymorphic=true]
|
| List Instances | GET | /access/instances/{TYPE_NAME}[?polymorphic=true]
|
| Exists Instance | GET | /access/instances/{TYPE_NAME}/{UUID}
|
| Read Instace | GET | /access/instances/{TYPE_NAME}/{UUID}
|
| Get Instace Contexts | GET | /access/instances/{TYPE_NAME}/{UUID}/contexts
|
| Query | GET | /access/query?q=SELECT FROM EntityV&limit=20&fetchPlan=*:-1
|
| Prepared Query | GET | /access/query/{RESOURCE_TYPE_NAME}/{RELATION_TYPE_NAME}/{ENTITY_TYPE_NAME}[?reference={REFERENCE_ENTITY_UUID}&polymorphic=true&direction=out]
|
Resource Registry Client
Resource Registry Client is a java library providing RPC facilities to interact with [#Query & Access Collection | Query & Access Collection]]. The library hides all the complexity of marshalling and unmarshalling of requests and results. By using this library any client is able to manage java classes instead of JSON objects.
To use the Java library to interact with [#Query & Access Collection | Query & Access Collection]] declare the following dependency in your pom.xml file.
<dependency> <groupId>org.gcube.information-system</groupId> <artifactId>resource-registry-client</artifactId> <version>[4.0.0,5.0.0-SNAPSHOT)</version> <dependency>
To use the client you just need to instantiate the client via the provided factory.
import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClient; import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClientFactory; ... ResourceRegistryClient resourceRegistryClient = ResourceRegistryClientFactory.create();
APIs
Get All Instances in relation with a specific entity instance
REST API
GET /resource-registry/access/instances/{Entity Type}?[polymorphic=(true|false)]&reference={Entity Instance UUID}&direction=(in|out|both)
Default:
- polymorphic : false
- direction : both
Example
GET /resource-registry/access/instances/EService?polymorphic=true&reference=b0d15e45-62af-4221-b785-7d014f10e631&direction=out
In this example we retrieve all EServices that are target of a relation starting from the Entity identified by b0d15e45-62af-4221-b785-7d014f10e631
- HostingNode(b0d15e45-62af-4221-b785-7d014f10e631) -> Hosts -> Eservice(4a7daacb-f13b-4685-b5c1-040c86806c16)
- HostingNode(b0d15e45-62af-4221-b785-7d014f10e631) -> Hosts -> Eservice(6e6442b9-37f1-479d-92eb-f935a983caba))
Response
[
{
"@class":“EService",
"header":{"uuid":"4a7daacb-f13b-4685-b5c1-040c86806c16", ...},
"consistsOf":[
{
"@class":"IsIdentifiedBy",
"header":{"uuid":"6c6e7deb-a911-4612-989d-d770f30c0d69", ...},
"target":{
"@class":"SoftwareFacet",
"header":{"uuid":"92f30e88-eff1-4282-b773-f3884b179d8d", ...},
“group": "VREManagement",
“name" : "SmartExecutor",
“version" : "1.7.0",
}
},
....
]
},
{
"@class":“EService",
"header":{"uuid":"6e6442b9-37f1-479d-92eb-f935a983caba", ...},
"consistsOf":[
{
"@class":"IsIdentifiedBy",
"header":{"uuid":"068f8d72-9495-4bd4-85b9-0ee234e99af6", ...},
"target":{
"@class":"SoftwareFacet",
"header":{"uuid":"35546e56-6e76-4cc9-8c83-7320fd923597", ...},
“group": "VREManagement",
“name" : "WhnManager",
“version" : "2.0.0",
}
},
.....
]
},
....
]
Java API
public <ERType extends ER, E extends Entity, R extends Resource> List<R> getInstancesFromEntity(Class<ERType> clazz, Boolean polymorphic, E reference, Direction direction) throws ResourceRegistryException;
Example
UUID uuid = UUID.fromString("b0d15e45-62af-4221-b785-7d014f10e631");
HostingNode hostingNode = resourceRegistryClient.getInstance(HostingNode.class, uuid);
List<EService> eServices = resourceRegistryClient.getInstancesFromEntity(EService.class, true, hostingNode, Direction.out);
Alternative Java API
public <ERType extends ER, R extends Resource> List<R> getInstancesFromEntity(Class<ERType> clazz, Boolean polymorphic, UUID reference, Direction direction) throws ResourceRegistryException;
public String getInstancesFromEntity(String type, Boolean polymorphic, UUID reference, Direction direction) throws ResourceRegistryException;
Example
UUID uuid = UUID.fromString("b0d15e45-62af-4221-b785-7d014f10e631");
List<EService> eServices = resourceRegistryClient.getInstancesFromEntity(EService.class, true, uuid, Direction.out);
UUID uuid = UUID.fromString("b0d15e45-62af-4221-b785-7d014f10e631");
String eServicesJsonString = resourceRegistryClient.getInstancesFromEntity(EService.NAME, true, uuid, Direction.out);
Get Filtered Resource Instances
This API allow to retrieve all resource of a given Resource Type described by a Facet Type having certain keys and values. The relation between the Resource and the Facet must be of the specified ConsistsOf Type (polymorphism is always used, use ConsistsOf to be more generic).
REST API
GET /resource-registry/access/resourceInstances/{Resource Type}/{ConsistsOf Type}/{Facet Type}?[polymorphic=(true|false)]&key1=value1&key2=value2&...
Default:
- polymorphic : false
Example
GET /resource-registry/access/resourceInstances/EService/IsIdentifiedBy/SoftwareFacet?polymorphic=true&group=DataAccess&name=HomeLibraryWebapp
Response
{
"@class": "EService",
"header": {"uuid": "38823ddc-0713-4e83-9670-79e472408b0c", ...},
"consistsOf": [
{
"@class": "IsIdentifiedBy",
"header": {"uuid": "8829279d-70c1-4327-a817-169ed9a52467", ...},
"target": {
"@class": "SoftwareFacet",
"header": {"uuid": "747713c0-fcbf-42d9-8709-c782c2121f9d", ...},
"name": "HomeLibraryWebapp",
"group": "DataAccess",
"version": "1.5.0-SNAPSHOT",
"description": "home library webapp",
"qualifier": null,
"optional": false
}
},
...
]
}
Java API
public <R extends Resource> List<R> getFilteredResources(Class<R> resourceClass, Class<? extends ConsistsOf> consistsOfClass, Class<? extends Facet> facetClass,boolean polymorphic, Map<String, Object> map) throws ResourceRegistryException
Example
Map<String, Object> map = new HashMap<>();
map.put("group", "DataAccess");
map.put("name", "HomeLibraryWebapp");
List<EService> eServices = resourceRegistryClient.getFilteredResources(EService.class, IsIdentifiedBy.class, SoftwareFacet.class, true, map);
Alternative Java API
public List<Resource> getFilteredResources(String resourceType, String consistsOfType, String facetType, boolean polymorphic, Map<String, Object> map) throws ResourceRegistryException;
Example
Map<String, Object> map = new HashMap<>();
map.put("group", "DataAccess");
map.put("name", "HomeLibraryWebapp");
String eServiceJsonString = resourceRegistryClient.getFilteredResources(EService.NAME, IsIdentifiedBy.NAME, SoftwareFacet.NAME, true, map);
Raw Query
This API provides a way to query the underling database persistence by using the persistence query language dialect. This API does not provide any consistency with the IS Model concepts. The result is related how the service decide to represent the IS Model concepts on persistence data model.
At time of writing the underling database persistence is OrientDB. It should be used only for development purpose only because the way to represent the IS Model concepts can change at any time or can change the database persistence.
At time of writing the query language supported is OrientDB SQL Dialect
GET /resource-registry/access?query=SELECT FROM Facet
REST API
GET /resource-registry/access?query={Query}
Example 1
GET /resource-registry/access?query=SELECT FROM SoftwareFacet LIMIT 2
Response Body
{
"result": [
{
"@type": "d",
"@rid": "#99:5",
"@version": 12,
"@class": "SoftwareFacet",
"header": {
"@type": "d",
"@version": 0,
"@class": "Header",
"uuid": "6b724a7c-9f51-4a4e-8e8e-1636ca2e9d29",
"creator": "VREManagement:WhnManager:pc-frosini.isti.cnr.it_8080",
"creationTime": "2017-10-05 16:09:02.618 +0200",
"lastUpdateTime": "2017-10-05 17:23:44.191 +0200",
"@fieldTypes": "creationTime=t,lastUpdateTime=t"
},
"name": "WhnManager",
"description": "Web Hosting Node Service",
"optional": false,
"version": "2.0.0-SNAPSHOT",
"group": "VREManagement",
"_allow": [
"#4:12",
"#5:13",
"#4:14"
],
"_allowRead": [
"#4:13",
"#4:11"
],
"in_IsIdentifiedBy": [
"#168:5"
],
"@fieldTypes": "_allow=n,_allowRead=n,in_IsIdentifiedBy=g"
},
{
"@type": "d",
"@rid": "#99:6",
"@version": 5,
"@class": "SoftwareFacet",
"header": {
"@type": "d",
"@version": 0,
"@class": "Header",
"uuid": "bc98eec4-4365-49fd-83b3-2cacaf17f8bf",
"creator": "VREManagement:SmartExecutor:pc-frosini.isti.cnr.it_8080",
"creationTime": "2017-10-05 17:22:06.351 +0200",
"lastUpdateTime": "2017-10-05 17:23:44.206 +0200",
"@fieldTypes": "creationTime=t,lastUpdateTime=t"
},
"name": "SmartExecutor",
"description": "Smart Executor Service",
"optional": false,
"version": "1.7.0-SNAPSHOT",
"group": "VREManagement",
"_allow": [
"#4:12",
"#5:15",
"#4:14"
],
"_allowRead": [
"#4:13",
"#4:11"
],
"in_IsIdentifiedBy": [
"#168:6"
],
"@fieldTypes": "_allow=n,_allowRead=n,in_IsIdentifiedBy=g"
}
],
"notification": "Query executed in 0.147 sec. Returned 2 record(s)"
}
As you can see a lot of database specific informations are returned. You cannot use or rely on them to interact with registry.
Example 2
GET /resource-registry/access?query=SELECT FROM EService LIMIT 2
Response Body
{
"result": [
{
"@type": "d",
"@rid": "#138:2",
"@version": 12,
"@class": "EService",
"header": {
"@type": "d",
"@version": 0,
"@class": "Header",
"uuid": "077a389f-6676-49bb-a925-16bea54c5f5d",
"creator": "VREManagement:WhnManager:pc-frosini.isti.cnr.it_8080",
"creationTime": "2017-10-05 16:09:02.604 +0200",
"lastUpdateTime": "2017-10-05 17:23:44.191 +0200",
"@fieldTypes": "creationTime=t,lastUpdateTime=t"
},
"_allow": [
"#4:12",
"#5:13",
"#4:14"
],
"_allowRead": [
"#4:13",
"#4:11"
],
"out_IsIdentifiedBy": [
"#168:5"
],
"out_ConsistsOf": [
"#165:32",
"#166:32",
"#164:33"
],
"in_Hosts": [
"#230:2"
],
"@fieldTypes": "_allow=n,_allowRead=n,out_IsIdentifiedBy=g,out_ConsistsOf=g,in_Hosts=g"
},
{
"@type": "d",
"@rid": "#138:3",
"@version": 5,
"@class": "EService",
"header": {
"@type": "d",
"@version": 0,
"@class": "Header",
"uuid": "cabca29a-59e4-463d-9932-02c6d68c8ce0",
"creator": "VREManagement:SmartExecutor:pc-frosini.isti.cnr.it_8080",
"creationTime": "2017-10-05 17:22:06.340 +0200",
"lastUpdateTime": "2017-10-05 17:23:44.206 +0200",
"@fieldTypes": "creationTime=t,lastUpdateTime=t"
},
"_allow": [
"#4:12",
"#5:15",
"#4:14"
],
"_allowRead": [
"#4:13",
"#4:11"
],
"out_IsIdentifiedBy": [
"#168:6"
],
"out_ConsistsOf": [
"#164:36",
"#165:36",
"#166:36"
],
"in_Hosts": [
"#230:3"
],
"@fieldTypes": "_allow=n,_allowRead=n,out_IsIdentifiedBy=g,out_ConsistsOf=g,in_Hosts=g"
}
],
"notification": "Query executed in 0.197 sec. Returned 2 record(s)"
}
As you can notice only the Vertexes of EServices are returned which they doesn't contains the facets.
