Resource Registry Service - Query & Access

From Gcube Wiki
Revision as of 17:55, 9 November 2017 by Luca.frosini (Talk | contribs) (→‎REST API)

Jump to: navigation, search

This sections provide 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 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>[1.0.0-SNAPSHOT, 2.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();

Exists

REST API

HEAD /resource-registry/access/instance/{ER Type}/{Instance UUID}
Example
HEAD /resource-registry/access/instance/ContactFacet/4d28077b-566d-4132-b073-f4edaf61dcb9

Java API

public <ERType extends ER> boolean exists(Class<ERType> clazz, UUID uuid) throws ERNotFoundException, ERAvailableInAnotherContextException, ResourceRegistryException;
Example
UUID uuid = UUID.fromString("4d28077b-566d-4132-b073-f4edaf61dcb9");
resourceRegistryClient.exists(ContactFacet.class, uuid);

Alternative Java API

public boolean exists(String type, UUID uuid) throws ERNotFoundException, ERAvailableInAnotherContextException, ResourceRegistryException;
Example
UUID uuid = UUID.fromString("4d28077b-566d-4132-b073-f4edaf61dcb9");
resourceRegistryClient.exists("ContactFacet", uuid);

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 of a Specific Type

REST API

GET /resource-registry/access/instances/{ER Type}?[polymorphic=(true|false)]

Default:

  • polymorphic=false
Example 1
GET /resource-registry/access/instances/EService

Response 

[
	{
		"@class":“EService",
		"header":{"uuid":"0717b450-a698-11e2-900a-a46c6ff57f05", ...},
		"consistsOf":[
			{
				"@class":"IsIdentifiedBy",
				"header":{"uuid":"aa1340d3-2229-497f-9eeb-cc7db93950fe", ...},
				"target":{ 
					"@class":"SoftwareFacet",
					"header":{"uuid":"187bee6d-6742-49a7-be89-68bdb0f2f221", ...},
					“group": "DataStorage",
					“name" : "StorageManager",
					“version" : “2.3.0-0",
				}
			},{
				"@class":"ConsistsOf",
				"header":{"uuid":"1f5b5608-4a91-4fe3-a7c2-edf3aeb5dbd7", ...},
				"target": { 
					"@class":"AccessPointFacet",
					"header":{"uuid":" 3b6061f9-e2ab-4c01-b3b2-48b470a5b8a ", ...},
					endpoint  :  "mongo3-p-d4s.d4science.org"
					description  : "MongoDB server"
					authorization	: {
						@class	"ValueSchema"
						value	"d4sUser:Nxae6MegJrITUD6wyBTimw=="
						schema	"USERNAME:PASSWORD“
					}
				}
			}
		]
	}, 
	....
]
Example 2
GET /resource-registry/access/instances/EService?polymorphic=true

Response 

[
	{
		"@class":"RunningPlugin",
		"header":{"uuid":"66d69dab-203e-45ff-b49e-a8fa4126a392"},
		"consistsOf":[
			{
				"@class":"IsIdentifiedBy",
				"header":{"uuid":"5e8cf3e3-8c75-49d4-98db-95d4d08d61f9", ...},
				"target":{ 
					"@class":“SoftwareFacet",
					"header":{"uuid":"3715696d-796f-4e92-98a3-f9a38a2f8d5e", ...},
					“group": "Accounting",
					“name" : "accounting-aggregator-se-plugin",
					“version" : “1.3.0",
				}
			},
			...
		]
	},
	{
		"@class":“EService",
		"header":{"uuid":"0717b450-a698-11e2-900a-a46c6ff57f05", ...},
		"consistsOf":[
			{
				"@class":"IsIdentifiedBy",
				"header":{"uuid":"aa1340d3-2229-497f-9eeb-cc7db93950fe", ...},
				"target":{ 
					"@class":"SoftwareFacet",
					"header":{"uuid":"187bee6d-6742-49a7-be89-68bdb0f2f221", ...},
					“group": "DataStorage",
					“name" : "StorageManager",
					“version" : “2.3.0-0",
				}
			},{
				"@class":"ConsistsOf",
				"header":{"uuid":"1f5b5608-4a91-4fe3-a7c2-edf3aeb5dbd7", ...},
				"target": { 
					"@class":"AccessPointFacet",
					"header":{"uuid":" 3b6061f9-e2ab-4c01-b3b2-48b470a5b8a ", ...},
					endpoint  :  "mongo3-p-d4s.d4science.org"
					description  : "MongoDB server"
					authorization	: {
						@class	"ValueSchema"
						value	"d4sUser:Nxae6MegJrITUD6wyBTimw=="
						schema	"USERNAME:PASSWORD“
					}
				}
			},
			....
		]
	}, 
	....
]

Java API

public <ERType extends ER, R extends Resource> List<R> getInstances(Class<ERType> clazz, Boolean polymorphic) throws ResourceRegistryException;
Example 1
List<EService> eServices = resourceRegistryClient.getInstances(EService.class, false);
Example 2
List<EService> eServices = resourceRegistryClient.getInstances(EService.class, true);

Alternative Java API

public String getInstances(String type, Boolean polymorphic) throws ResourceRegistryException;
Example 1
String eServicesJsonString = resourceRegistryClient.getInstances("EService", false);
Example 2
String eServicesJsonString = resourceRegistryClient.getInstances("EService", true);

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)"
}
Example 1
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 */
		}
	]
}
Retrieved from "https://wiki.gcube-system.org/index.php?title=Resource_Registry_Service_-_Query_%26_Access&oldid=30080"