Difference between revisions of "Resource Registry Service - Instances Management"

From Gcube Wiki
Jump to: navigation, search
(IsRelatedTo)
(Resource Instances APIs)
Line 195: Line 195:
  
 
The method just need the UUID of the Facet to be deleted.
 
The method just need the UUID of the Facet to be deleted.
 
== Resource Instances APIs ==
 
 
=== Create Resource Instance ===
 
 
==== REST API ====
 
 
<pre>PUT /resource-registry/er/resource/{ResourceType}</pre>
 
 
===== Example =====
 
 
<pre>
 
PUT /resource-registry/er/resource/HostingNode
 
</pre>
 
 
'''''Request Body'''''
 
<pre>
 
{
 
"@class":"HostingNode",
 
"consistsOf":[
 
{
 
"@class":"ConsistsOf",
 
"target":{
 
"@class":"CPUFacet",
 
"model":"Opteron",
 
"vendor":"AMD",
 
"clockSpeed":"3 GHz"
 
}
 
},{
 
"@class":"IsIdentifiedBy",
 
"target":{
 
"@class":"NetworkingFacet",
 
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933"},
 
/* In this example we suppose that the NetworkingFacet was already created, so the UUID is enough to attach it by using IsIdentifiedBy relation */
 
}
 
}
 
],
 
"isRelatedTo":[
 
{
 
"@class":"Hosts",
 
"propagationConstraint":{
 
"add":"unpropagate",
 
"remove": "cascade"
 
},
 
"target":{
 
"@class":"EService",
 
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3"}
 
/* The EService was already created, so the UUID is enough to attach it by using Hosts relation */
 
}
 
}
 
]
 
}
 
 
</pre>
 
 
'''''Response'''''
 
<pre>
 
{
 
"@class":"HostingNode",
 
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"},
 
"consistsOf":[
 
{
 
"@class":"ConsistsOf",
 
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
 
"target":{
 
"@class":"CPUFacet",
 
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
 
"model":"Opteron",
 
"vendor":"AMD",
 
"clockSpeed":"1 GHz"
 
}
 
},{
 
"@class":"IsIdentifiedBy",
 
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
 
"target":{
 
"@class":"NetworkingFacet",
 
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
 
"ipAddress" : "146.48.87.183",
 
"hostName": "pc-frosini.isti.cnr.it",
 
"domainName" : "isti.cnr.it",
 
"mask" : "255.255.248.0",
 
"broadcastAddress":"146.48.87.255"
 
}
 
}
 
],
 
"isRelatedTo":[
 
{
 
"@class":"Hosts",
 
"header":{"uuid":"47494ad0-e606-4630-9def-4c607761ae14", ...},
 
"propagationConstraint":{
 
"add":"unpropagate",
 
"remove": "cascade"
 
},
 
"target":{
 
"@class":"EService",
 
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...}
 
}
 
}
 
]
 
}
 
</pre>
 
 
==== Java API ====
 
 
<pre>
 
public <R extends Resource> R createResource(R resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
 
</pre>
 
 
===== Example =====
 
 
<pre>
 
NetworkingFacet networkingFacet = new NetworkingFacetImpl();
 
networkingFacet.setIPAddress("146.48.87.183");
 
networkingFacet.setHostName("pc-frosini.isti.cnr.it");
 
networkingFacet.setDomainName("isti.cnr.it");
 
networkingFacet.setMask("255.255.248.0");
 
networkingFacet.setBroadcastAddress("146.48.87.255");
 
 
networkingFacet = resourceRegistryPublisher.createFacet(networkingFacet);
 
 
HostingNode hostingNode = new HostingNodeImpl();
 
 
CPUFacet cpuFacet = new CPUFacetImpl();
 
cpuFacet.setClockSpeed("1 GHz");
 
cpuFacet.setModel("Opteron");
 
cpuFacet.setVendor("AMD");
 
hostingNode.addFacet(cpuFacet);
 
 
isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
 
hostingNode.attachFacet(isIdentifiedBy);
 
 
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
 
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
 
propagationConstraint.setAddConstraint(AddConstraint.unpropagate);
 
 
Hosts<HostingNode, EService> hosts = new HostsImpl<HostingNode, EService>(hostingNode, eService, propagationConstraint);
 
hostingNode.attachResource(hosts);
 
 
hostingNode = resourceRegistryPublisher.createResource(hostingNode);
 
</pre>
 
 
 
==== Alternative JAVA API ====
 
 
There are also two other equivalent methods with the following signature:
 
 
<pre>
 
public String createResource(String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
 
 
public String createResource(String resourceType, String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
 
</pre>
 
 
The first methods get the Resource to be created as JSON string instead of as Java class.
 
The second get also the '''resourceType''' as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string.
 
The second method is more efficient but you have to be sure that the '''resourceType''' is the same specified in the header of the serialized resource.
 
 
=== Update Resource Instance ===
 
 
==== REST API ====
 
 
<pre>POST /resource-registry/er/resource/{Resource Instance UUID}</pre>
 
 
=====  Example =====
 
<pre>POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84</pre>
 
 
'''''Request Body'''''
 
<pre>
 
{
 
"@class":"HostingNode",
 
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
 
"consistsOf":[
 
{
 
"@class":"ConsistsOf",
 
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
 
"target":{
 
"@class":"CPUFacet",
 
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
 
"model":"Opteron",
 
"vendor":"AMD",
 
"clockSpeed":"1 GHz"
 
}
 
},{
 
"@class":"IsIdentifiedBy",
 
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
 
"target":{
 
"@class":"NetworkingFacet",
 
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
 
"ipAddress" : "146.48.87.183",
 
"hostName": "pc-frosini.isti.cnr.it",
 
"domainName" : "isti.cnr.it",
 
"mask" : "255.255.248.0",
 
"broadcastAddress":"146.48.87.255",
 
"username":"luca.frosini" /* Added this property */
 
}
 
}
 
]
 
}
 
</pre>
 
 
'''''Response'''''
 
<pre>
 
{
 
"@class":"HostingNode",
 
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
 
"consistsOf":[
 
{
 
"@class":"ConsistsOf",
 
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
 
"target":{
 
"@class":"CPUFacet",
 
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
 
"model":"Opteron",
 
"vendor":"AMD",
 
"clockSpeed":"1 GHz"
 
}
 
},{
 
"@class":"IsIdentifiedBy",
 
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
 
"target":{
 
"@class":"NetworkingFacet",
 
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
 
"ipAddress" : "146.48.87.183",
 
"hostName": "pc-frosini.isti.cnr.it",
 
"domainName" : "isti.cnr.it",
 
"mask" : "255.255.248.0",
 
"broadcastAddress":"146.48.87.255",
 
"username":"luca.frosini"
 
}
 
}
 
]
 
}
 
</pre>
 
 
==== Java API ====
 
<pre>
 
public <R extends Resource> R updateResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
 
</pre>
 
 
===== Example =====
 
 
<pre>
 
 
/* This is just a code example, here we suppose that there is only one identification Facet of the type (NetworkingFacet). This could not be true  in real scenario*/
 
networkingFacet = (NetworkingFacet) hostingNode.getIdentificationFacets().get(0);
 
networkingFacet.setAdditionalProperty("username", "luca.frosini");
 
 
hostingNode = resourceRegistryPublisher.updateResource(hostingNode);
 
</pre>
 
 
==== Alternative JAVA API ====
 
 
There are also two other equivalent methods with the following signature:
 
 
<pre>
 
public String updateResource(String resource) throws ResourceNotFoundException, ResourceRegistryException;
 
public String updateResource(UUID uuid, String resource) throws ResourceNotFoundException, ResourceRegistryException;
 
</pre>
 
 
The first methods get the Resource to be created as JSON string instead of as Java class.
 
The second get also the '''uuid''' as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string.
 
The second method is more efficient but you have to be sure that the '''uuid''' is the same specified in the header of the serialized resource.
 
 
=== Delete Resource Instance ===
 
 
==== REST API ====
 
 
<pre>DELETE /resource-registry/er/resource/{Resource Instance UUID}</pre>
 
 
=====  Example =====
 
 
<pre>DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84</pre>
 
 
==== Java API ====
 
<pre>
 
public <R extends Resource> boolean deleteResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
 
</pre>
 
 
===== Example =====
 
 
<pre>
 
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);
 
</pre>
 
 
==== Alternative JAVA API ====
 
 
There is also another equivalent methods with the following signature:
 
 
<pre>
 
public boolean deleteResource(UUID uuid) throws ResourceNotFoundException, ResourceRegistryException;
 
</pre>
 
 
The method just need the UUID of the Resource to be deleted.
 

Revision as of 16:55, 2 July 2021

This section provides information regarding how to interact with Resource Registry Service for Entities and Relations Management. 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 Publisher java client.

Resource Registry Publisher has the following maven coordinates

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-publisher</artifactId>
	<version>[1.0.0-SNAPSHOT, 2.0.0-SNAPSHOT)</version>
</dependency>

To use the client, you need first get a ResourceRegistryPublisher instance.

By using ResourceRegistryPublisherFactory.create() method the library discovers the correct endpoint to interact with the Resource Registry for the current context.

SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();

Facet Instances APIs

Create Facet Instance

REST API

PUT /resource-registry/er/facet/{FacetType}
Example
PUT /resource-registry/er/facet/CPUFacet

Request Body

{
	"@class":"CPUFacet",
	"header":null,
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"1 GHz"
}

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 <F extends Facet> F createFacet(F facet) throws FacetAlreadyPresentException, ResourceRegistryException;
Example
CPUFacet cpuFacet = new CPUFacetImpl();
cpuFacet.setClockSpeed("1 GHz");
cpuFacet.setModel("Opteron");
cpuFacet.setVendor("AMD");

CPUFacet createdCpuFacet = resourceRegistryPublisher.createFacet(cpuFacet);
UUID uuid = createdCpuFacet.getHeader().getUUID(); // 69f0b376-38d2-4a85-bc63-37f9fa323f82

Alternative JAVA API

There are also two other equivalent methods with the following signature:

public String createFacet(String facet) throws FacetAlreadyPresentException, ResourceRegistryException;

public String createFacet(String facetType, String facet) throws FacetAlreadyPresentException, ResourceRegistryException;

The first methods get the Facet to be created as JSON string instead of as Java class. The second get also the facetType as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string. The second method is more efficient but you have to be sure that the facetType is the same specified in the header of the serialized facet.

Update Facet Instance

REST API

POST /resource-registry/er/facet/{Facet Instance UUID}
Example
POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Request Body

{
	"@class":"CPUFacet",
	"header":{"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82"}, /* if you pass the header only the UUID is checked and must be the same of the one provided in the URL*/
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"2 GHz"
}

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:17:32"
	},
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"2 GHz"
}

Java API

public <F extends Facet> F updateFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
Example
createdCpuFacet.setClockSpeed("2 GHz");
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(createdCpuFacet);

Alternative JAVA API

There are also two other equivalent methods with the following signature:

public String updateFacet(String facet) throws FacetNotFoundException, ResourceRegistryException;
public String updateFacet(UUID uuid, String facet) throws FacetNotFoundException, ResourceRegistryException;

The first methods get the Facet to be created as JSON string instead of as Java class. The second get also the uuid as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string. The second method is more efficient but you have to be sure that the provided uuid is the same specified in the header of the serialized facet.

Delete Facet Instance

REST API

DELETE /resource-registry/er/facet/{Facet Instance UUID}
Example
DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Java API

public <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
Example
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);

Alternative JAVA API

There is also another equivalent methods with the following signature:

public boolean deleteFacet(UUID uuid) throws FacetNotFoundException, ResourceRegistryException;

The method just need the UUID of the Facet to be deleted.