Resource Registry Service - Query & Access
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.
Apart from the REST API this port type can be used also by using Resource Registry Client java client.
Resource Registry Client has the following maven coordinates
<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 need first get a ResourceRegistryClient instance.
By using ResourceRegistryClientFactory.create() method the library discover the correct endpoint to interact with the Resource Registry for the current context.
SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set ResourceRegistryClient resourceRegistryClient = ResourceRegistryClientFactory.create();
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]
|
Get Instance
REST API
GET /resource-registry/access/instance/{ER Type}/{Instance UUID}
Example
GET /resource-registry/access/instance/CPUFacet/69f0b376-38d2-4a85-bc63-37f9fa323f82
Response Body
{ "@class":"CPUFacet", "header": { "uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82", "creator":"luca.frosini", "lastUpdater":"luca.frosini", "creationTime":"2016-10-05 11:16:24", "lastUpdateTime":"2016-10-05 11:16:24 }, "model":"Opteron", "vendor":"AMD", "clockSpeed":"1 GHz" }
Java API
public <ERType extends ER> ERType getInstance(Class<ERType> clazz, UUID uuid) throws ERNotFoundException, ERAvailableInAnotherContextException, ResourceRegistryException;
Example
UUID uuid = UUID.fromString("69f0b376-38d2-4a85-bc63-37f9fa323f82"); CPUFacet cpuFacet = resourceRegistryClient.getInstance(CPUFacet.class, uuid);
Alternative Java API
public String getInstance(String type, UUID uuid) throws ERNotFoundException, ERAvailableInAnotherContextException, ResourceRegistryException;
Example
UUID uuid = UUID.fromString("69f0b376-38d2-4a85-bc63-37f9fa323f82"); String cpuFacetJsonString = resourceRegistryClient.getInstance("CPUFacet" uuid);
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.
Read Context
Allow to read the definition of a Context.
REST API
This API is also exposed in Context Port Type
GET /resource-registry/access/context/{Context UUID}
Example
Read the Context having UUID 9d73d3bd-1873-490c-b0a7-e3c0da11ad52
Request URL
GET /resource-registry/context/9d73d3bd-1873-490c-b0a7-e3c0da11ad52
Response Body
{ "@class":"Context", "name":"devVRE", "header": { "@class":"Header", "uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52", "creator":"luca.frosini", "lastUpdater":"luca.frosini", "creationTime":"2017-03-17 11:47:56", "lastUpdateTime":"2017-03-17 11:52:56" } }
Read Type Definition
Allow to read Type Definition This API is also exposed in Access Port Type
REST API
GET /resource-registry/access/schema/{ Type Name }
Example
GET /resource-registry/schema/ContactFacet
Response
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }