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

From Gcube Wiki
Jump to: navigation, search
(→‎REST API)
(→‎Read Instance)
 
(138 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
|}
 
|}
  
−
This sections provide information regarding how to interact with [[Information System Resource Registry#Resource_Registry Service | Resource Registry Service]] for Entities and Relations Management. REST and JAVA API are presented for each functionality.
+
These sections provide information regarding how to interact with [[Information System Resource Registry#Resource Registry Service | Resource Registry Service]] for Entities and Relations instances 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.
 
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 [[Information System Resource Registry#Resource_Registry_Publisher | Resource Registry Publisher]] java client.
+
== Instances Management ==
  
 +
Instances Management is responsible for the management of entities and relation instances. It offers the following APIs:
 +
* '''List''': it allows to list instances of a certain type;
 +
* '''Create''': it allows to create a new entity or relation instance in a certain context;
 +
* '''Exists''': it allows to check if an instance exists in a certain context;
 +
* '''Read''': it allows to get the representation of the requested instance in a certain context;
 +
* '''Update''': it allows to update an instance in a certain context;
 +
* '''Delete''': it allows to delete an instance.
  
−
[[Information System Resource Registry#Resource_Registry_Publisher | Resource Registry Publisher]] has the following maven coordinates
+
The Instances Management implements the following policies:
  
−
<pre>
+
* it manages the Header automatically;
−
<dependency>
+
* it allows identifying an instance via the Universally Unique Identifier (UUID) specified in the Header;
−
<groupId>org.gcube.information-system</groupId>
+
* it allows the creation of an instance only if the declared type is already present in the system (previously registered via the Types Collection;
−
<artifactId>resource-registry-publisher</artifactId>
+
* it validates the instance against the schema of the defined type;
−
<version>[1.0.0-SNAPSHOT, 2.0.0-SNAPSHOT)</version>
+
* it imposes the default values of propagation constraints (IsRelatedTo (remove=keep, add=unpropagate); ConsistsOf (remove=cascadeWhenOrphan, add=propagate).) when the client does not specify their values;
−
</dependency>
+
* it guarantees propagation constraints.
−
</pre>
+
  
−
To use the client you need first get a ''ResourceRegistryPublisher'' instance.
+
== Instances Collection ==
  
−
By using ''ResourceRegistryPublisherFactory.create()'' method the library discover the correct endpoint to interact with the Resource Registry for the current context.
+
The following table shows the exposed APIs as REST Collection.  
  
−
<pre>
+
{| class="wikitable"
−
SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set
+
! Operation || HTTP Method || URL
−
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
+
|-
−
</pre>
+
| List || GET || <code>/instances/{TYPE_NAME}[?polymorphic=true]</code>
 +
|-
 +
| Create || PUT || <code>/instances/{TYPE_NAME}/{UUID}</code>
 +
|-
 +
| Exists || HEAD || <code>/instances/{TYPE_NAME}/{UUID}</code>
 +
|-
 +
| Read || GET || <code>/instances/{TYPE_NAME}/{UUID}</code>
 +
|-
 +
| Update || PUT || <code>/instances/{TYPE_NAME}/{UUID}</code>
 +
|-
 +
| Delete || DELETE || <code>/instances/{TYPE_NAME}/{UUID}</code>
 +
|}
  
 +
Security configuration based on [[Authorization Framework]] make this port type accessible only from [[Information System Resource Manager|Resource Manager]].
 +
In other words, no others client is allowed to manage types rather than [[Information System Resource Manager|Resource Manager]].
  
−
=== Facet Instances APIs ===
+
==== Instances Collection Administrative capabilities ====
  
−
==== Create Facet Instance ====
+
{| class="wikitable"
 +
! Operation || HTTP Method || URL
 +
|-
 +
| List || GET || <code>/instances/{TYPE_NAME}[?polymorphic=true&hierarchical=false&includeContextsInHeader=false]</code>
 +
|-
 +
| Read || GET || <code>/instances/{TYPE_NAME}/{UUID}[?hierarchical=false&includeContextsInHeader=false]</code>
 +
|-
 +
| Get Instance Contexts || GET || <code>/instances/{TYPE_NAME}/{UUID}/contexts</code>
 +
|}
  
−
===== REST API =====
+
Administrators are entitled to specify the following two query parameter in case of read and list operation:
−
<pre>
+
−
PUT /resource-registry/er/facet/CPUFacet
+
−
</pre>
+
  
−
'''''Request Body'''''
+
* hierarchical (default=false): enable [[#Hierarchical Mode]]
−
<pre>
+
* includeContextsInHeader (default=false): include [[#Contexts in Header]]
−
{
+
−
"@class":"CPUFacet",
+
−
"header":null,
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
</pre>
+
  
−
'''''Response Body'''''
+
An administrator can also request the list of contexts an instance belongs to.
−
<pre>
+
The result is an array of strings containing the UUID of contexts.
−
{
+
−
"@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"
+
−
}
+
−
</pre>
+
  
−
===== Java API =====
+
===== Hierarchical Mode =====
  
−
<pre>
+
An administrator has the possibilities not only the instances belonging to the current context (i.e. the context identified by the gCube Token) but also all the instances in all contexts which are children of the current context.
−
public <F extends Facet> F createFacet(F facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
−
</pre>
+
  
−
====== Example ======
+
'''This functionality is only available for the list and the read operations.'''
−
<pre>
+
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
  
−
CPUFacet createdCpuFacet = resourceRegistryPublisher.createFacet(cpuFacet);
+
This functionality enables an administrator to have a complete overview of the instances at any context tree level.
−
UUID uuid = createdCpuFacet.getHeader().getUUID(); // 69f0b376-38d2-4a85-bc63-37f9fa323f82
+
−
</pre>
+
  
 +
Thanks to this functionality:
 +
* it is possible to create an instance at the VRE level, but it is not needed to add the instance at VO level just for administrator overview;
 +
* the administrator is capable of observing the instance at any higher level in the context hierarchy;
 +
* any "normal" client read only the context instance.
  
−
There are also two other equivalent methods with the following signature:
+
===== Contexts in Header =====
  
−
<pre>
+
This functionality allows listing all the contexts an instance belongs to.
−
public String createFacet(String facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
Used in conjunction with hierarchical mode provides the whole picture of the description of the resource and all different contexts it belongs.
 +
Please note that different facets in different contexts can describe a resource.
  
−
public String createFacet(String facetType, String facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
The list of contexts is included in the header as an array of strings containing the UUID of contexts.
−
</pre>
+
  
−
The first methods get the Facet to be created as JSON string instead of as Java class.
+
===== Get Instance Contexts =====
−
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 ====
+
====== Get Instance Contexts via Java Client ======
  
−
===== REST API =====
+
<source lang="java">
−
<pre>
+
public Set<UUID> getElementContexts(String type, UUID instanceUUID) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
−
POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82
+
−
</pre>
+
  
−
'''''Request Body'''''
+
public <ERElem extends ERElement> Set<UUID> getElementContexts(ERElem er) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
−
<pre>
+
</source>
−
{
+
−
"@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"
+
−
}
+
−
</pre>
+
  
−
'''''Response Body'''''
+
====== Get Instance Contexts via REST API ======
−
<pre>
+
−
{
+
−
"@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"
+
−
}
+
−
</pre>
+
  
−
===== Java API =====
+
<pre>GET /instances/{TYPE_NAME}/{UUID}/contexts</pre>
  
−
<pre>
+
{|class="wikitable"
−
public <F extends Facet> F updateFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
! Code
−
</pre>
+
! Type
 +
! Description
 +
|-
 +
| 200
 +
| String
 +
| A JSON Array containing the list of instances added to the context
 +
|}
  
−
====== Example ======
+
== Resource Registry Publisher ==
  
−
<pre>
+
Resource Registry Publisher is a java library providing RPC facilities to interact with [[Resource Registry Service - Instances Management | Instances Management]] and [[Resource Registry Service - Instances Sharing Management | Instances Sharing Management]].
−
createdCpuFacet.setClockSpeed("2 GHz");
+
The library hides all the complexity of marshalling and unmarshalling of requests and results.  
−
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(createdCpuFacet);
+
By using this library any client is able to manage java classes instead of JSON objects.
−
</pre>
+
  
−
There are also two other equivalent methods with the following signature:
+
To use the Java library to interact with Instances Collection declare the following dependency in your pom.xml file.
  
−
<pre>
+
<source lang="xml">
−
public String updateFacet(String facet) throws FacetNotFoundException, ResourceRegistryException;
+
<dependency>
−
public String updateFacet(UUID uuid, String facet) throws FacetNotFoundException, ResourceRegistryException;
+
<groupId>org.gcube.information-system</groupId>
−
</pre>
+
<artifactId>resource-registry-publisher</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
−
The first methods get the Facet to be created as JSON string instead of as Java class.
+
To use the client you just need to instantiate the client via the provided factory.  
−
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 ====
+
<source lang="java">
 +
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisher;
 +
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisherFactory;
  
−
===== REST API =====
+
...
−
<pre>
+
−
DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82
+
−
</pre>
+
  
−
'''''Response Body'''''
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
<pre>
+
</source>
−
true
+
−
</pre>
+
  
−
===== Java API =====
+
The provided client exposes the available methods and options as explained below.
  
−
<pre>
+
The source code of the resource-registry-publisher is available at [https://code-repo.d4science.org/gCubeSystem/resource-registry-publisher https://code-repo.d4science.org/gCubeSystem/resource-registry-publisher]
−
public <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
====== Example ======
+
== APIs ==
  
−
<pre>
+
=== List Instances ===
−
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);
+
−
</pre>
+
  
−
There is also another equivalent methods with the following signature:
+
==== List via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public boolean deleteFacet(UUID uuid) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The method just need the UUID of the Facet to be deleted.
+
<source lang="java">
 +
public <ERElem extends ERElement> List<ERElem> list(Class<ERElem> clazz, Boolean polymorphic) throws ResourceRegistryException;
 +
 +
public String list(String type, Boolean polymorphic) throws ResourceRegistryException;
 +
</source>
  
−
=== Resource Instances APIs ===
+
===== List via Java Client Example 1 =====
  
−
==== Create Resource Instance ====
+
The following snippet of code shows how to retrieve all the resource instances.
  
−
===== REST API =====
+
<source lang="java">
−
<pre>
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
PUT /resource-registry/er/resource/HostingNode
+
List<Resource> allResources = resourceRegistryPublisher.list(Resource.class, true);
−
</pre>
+
</source>
  
−
'''''Request Body'''''
+
===== List via Java Client Example 2 =====
−
<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 enought 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 enought to attach it by using Hosts relation */
+
−
}
+
−
}
+
−
]
+
−
}
+
  
−
</pre>
+
The following snippet of code shows how to retrieve all the EService instances (only the EService).
  
−
'''''Response'''''
+
<source lang="java">
−
<pre>
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
{
+
List<EService> allResources = resourceRegistryPublisher.list(EService.class, false);
−
"@class":"HostingNode",
+
</source>
−
"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 =====
+
==== List via REST API ====
  
−
<pre>
+
===== List via REST API Example 1 =====
−
public <R extends Resource> R createResource(R resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
−
</pre>
+
  
−
====== Example ======
+
The following request shows how to retrieve all the resource instances.
  
−
<pre>
+
'''Request URL'''
−
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);
+
<pre>GET /instances/Resource?polymorphic=true</pre>
  
−
HostingNode hostingNode = new HostingNodeImpl();
+
===== List via REST API Example 2 =====
  
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
The following request shows how to retrieve all the EService instances (only the EService).  
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
−
hostingNode.addFacet(cpuFacet);
+
  
−
isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
'''Request URL'''
−
hostingNode.attachFacet(isIdentifiedBy);
+
  
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
<pre>GET /instances/EService</pre>
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.unpropagate);
+
  
−
Hosts<HostingNode, EService> hosts = new HostsImpl<HostingNode, EService>(hostingNode, eService, propagationConstraint);
+
=== Create Instance ===
−
hostingNode.attachResource(hosts);
+
  
−
hostingNode = resourceRegistryPublisher.createResource(hostingNode);
+
==== Create via Java Client ====
−
</pre>
+
  
 +
'''Signature'''
  
−
There are also two other equivalent methods with the following signature:
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem create(ERElem er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
  
−
<pre>
+
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
−
public String createResource(String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
</source>
  
−
public String createResource(String resourceType, String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
The first method gets any instance of IdentifiableElement (i.e. Resources, Facets, ConsistsOf, IsRelatedTo)
−
</pre>
+
The second method gets the instance to be created as a JSON string instead of a Java class.
  
−
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 ====
+
===== Create via Java Client Example =====
 +
<source lang="Java">
 +
EService eService = new EServiceImpl();
 +
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
Header header = new HeaderImpl(uuid);
 +
eService.setHeader(header);
  
−
===== REST API =====
+
SoftwareFacet softwareFacet = new SoftwareFacetImpl();
−
<pre>
+
softwareFacet.setGroup("WhnManager");
−
POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
softwareFacet.setName("VREManagement");
−
</pre>
+
softwareFacet.setVersion("2.0.0-4.15.0-132431");
 +
softwareFacet.setDescription("Web Hosting Node Service");
  
−
'''''Request Body'''''
+
IsIdentifiedBy<Resource, Facet> isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(eService,
−
<pre>
+
softwareFacet, null);
 +
eService.addFacet(isIdentifiedBy);
 +
 
 +
AccessPointFacet accessPointFacet = new AccessPointFacetImpl();
 +
accessPointFacet.setEndpoint(new URI("http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager"));
 +
accessPointFacet.setEntryName("whnmanager");
 +
ValueSchema authz = new ValueSchemaImpl();
 +
authz.setValue("gcube-token");
 +
accessPointFacet.setAuthorization(authz);
 +
eService.addFacet(accessPointFacet);
 +
 
 +
AccessPointFacet accessPointFacet2 = new AccessPointFacetImpl();
 +
accessPointFacet2.setEndpoint(new URI("http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource"));
 +
accessPointFacet2.setEntryName("WhnManager-remote-management");
 +
ValueSchema authz2 = new ValueSchemaImpl();
 +
authz2.setValue("gcube-token");
 +
accessPointFacet2.setAuthorization(authz2);
 +
eService.addFacet(accessPointFacet2);
 +
 
 +
 
 +
EventFacet eventFacet = new EventFacetImpl();
 +
eventFacet.setDate(Calendar.getInstance().getTime());
 +
ValueSchema event = new ValueSchemaImpl();
 +
event.setSchema(new URI("String"));
 +
event.setValue("started");
 +
eventFacet.setEvent(event);
 +
eService.addFacet(eventFacet);
 +
 
 +
StateFacet stateFacet = new StateFacetImpl();
 +
stateFacet.setValue("started");
 +
eService.addFacet(stateFacet);
 +
 
 +
 
 +
eService = resourceRegistryPublisher.create(eService);
 +
 
 +
</source>
 +
 
 +
==== Create via REST API ====
 +
 
 +
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
 +
 
 +
===== Create via REST API Resource Example =====
 +
 
 +
The following listing shows an example of EService representation to be created.
 +
 
 +
'''Request URL'''
 +
 
 +
<pre>PUT PUT /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</pre>
 +
 
 +
Please note that '''EService''' and the UUID '''7f37a79d-0c00-4166-8a68-165de0a438bf''' are parts of the request URI
 +
 
 +
'''Request Body'''
 +
 
 +
<source lang="JavaScript">
 
{
 
{
−
"@class":"HostingNode",
+
    "@class": "EService",
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
    "header": {
−
"consistsOf":[
+
        "@class": "Header",
−
{  
+
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf"
−
"@class":"ConsistsOf",
+
    },
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
    "consistsOf": [
−
"target":{  
+
        {
−
"@class":"CPUFacet",
+
            "@class": "IsIdentifiedBy",
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
            "header": null,
−
"model":"Opteron",
+
            "propagationConstraint": null,
−
"vendor":"AMD",
+
            "target": {
−
"clockSpeed":"1 GHz"  
+
                "@class": "SoftwareFacet",
−
}
+
                "header": null,
−
},{
+
                "name": "WhnManager",
−
"@class":"IsIdentifiedBy",
+
                "group": "VREManagement",
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
                "version": "2.0.0-4.15.0-132431",
−
"target":{  
+
                "description": "Web Hosting Node Service",
−
"@class":"NetworkingFacet",
+
                "qualifier": null,
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
                "optional": false
−
"ipAddress" : "146.48.87.183",
+
            }
−
"hostName": "pc-frosini.isti.cnr.it",
+
        },
−
"domainName" : "isti.cnr.it",
+
        {
−
"mask" : "255.255.248.0",
+
            "@class": "ConsistsOf",
−
"broadcastAddress":"146.48.87.255",
+
            "header": null,
−
"username":"luca.frosini" /* Added this property */
+
            "propagationConstraint": null,
−
}
+
            "target": {
−
}
+
                "@class": "AccessPointFacet",
−
]
+
                "header": null,
 +
                "entryName": "whnmanager",
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
 +
                "protocol": null,
 +
                "description": null,
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "value": "gcube-token"
 +
                }
 +
            }
 +
        },
 +
        {
 +
            "@class": "ConsistsOf",
 +
            "header": null,
 +
            "propagationConstraint": null,
 +
            "target": {
 +
                "@class": "AccessPointFacet",
 +
                "header": null,
 +
                "entryName": "WhnManager-remote-management",
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
 +
                "protocol": null,
 +
                "description": null,
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "value": "gcube-token"
 +
                }
 +
            }
 +
        },
 +
        {
 +
            "@class": "ConsistsOf",
 +
            "header": null,
 +
            "propagationConstraint": null,
 +
            "target": {
 +
                "@class": "StateFacet",
 +
                "header": null,
 +
                "value": "started"
 +
            }
 +
        },
 +
        {
 +
            "@class": "ConsistsOf",
 +
            "header": null,
 +
            "propagationConstraint": null,
 +
            "target": {
 +
                "@class": "EventFacet",
 +
                "header": null,
 +
                "event": {
 +
                    "value": "started",
 +
                    "schema": "String"
 +
                },
 +
                "date": "2021-06-30 14:38:26.464 +0000"
 +
            }
 +
        }
 +
    ],
 +
    "isRelatedTo": []
 
}
 
}
−
</pre>
+
</source>
 +
 
 +
The following listing contains the response of the service containing the representation of the created EService:
 +
 
 +
'''Response Body'''
  
−
'''''Response'''''
+
<source lang="JavaScript">
−
<pre>
+
 
{
 
{
−
"@class":"HostingNode",
+
    "header": {
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
        "@class": "Header",
−
"consistsOf":[
+
        "creationTime": "2021-07-01 08:51:02.353 +0200",
−
{  
+
        "createdBy": "luca.frosini",
−
"@class":"ConsistsOf",
+
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
        "lastUpdateBy": "luca.frosini",
−
"target":{  
+
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
−
"@class":"CPUFacet",
+
    },
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
    "@class": "EService",
−
"model":"Opteron",
+
    "@superClasses": [
−
"vendor":"AMD",
+
        "Service",
−
"clockSpeed":"1 GHz"
+
        "GCubeResource",
−
}
+
        "Resource"
−
},{
+
    ],
−
"@class":"IsIdentifiedBy",
+
    "consistsOf": [
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
        {
−
"target":{  
+
            "header": {
−
"@class":"NetworkingFacet",
+
                "@class": "Header",
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
                "creationTime": "2021-07-01 08:51:02.312 +0200",
−
"ipAddress" : "146.48.87.183",
+
                "createdBy": "luca.frosini",
−
"hostName": "pc-frosini.isti.cnr.it",
+
                "uuid": "3b653a72-b182-41d6-bcc5-97e0141f0ceb",
−
"domainName" : "isti.cnr.it",
+
                "lastUpdateBy": "luca.frosini",
−
"mask" : "255.255.248.0",
+
                "lastUpdateTime": "2021-07-01 08:51:02.312 +0200"
−
"broadcastAddress":"146.48.87.255",
+
            },
−
"username":"luca.frosini"
+
            "propagationConstraint": {
−
}
+
                "@class": "PropagationConstraint",
−
}
+
                "add": "propagate",
−
]
+
                "remove": "cascade"
 +
            },
 +
            "@class": "IsIdentifiedBy",
 +
            "@superClasses": [
 +
                "ConsistsOf"
 +
            ],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "name": "WhnManager",
 +
                "description": "Web Hosting Node Service",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.298 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "97984812-90e6-4eb7-b804-50a9ad3fe4fb",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.298 +0200"
 +
                },
 +
                "optional": "false",
 +
                "version": "2.0.0-4.15.0-132431",
 +
                "group": "VREManagement",
 +
                "@class": "SoftwareFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.322 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "5c78bec3-2fa6-46b3-892d-d41bed93e136",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.322 +0200"
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema"
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
 +
                "entryName": "whnmanager",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.318 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "f66a9fdf-3d5c-45fd-8437-6fecec463c4c",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.318 +0200"
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.332 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d4aec29c-3f18-4464-94ae-5fb77306eb82",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.332 +0200"
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema"
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
 +
                "entryName": "WhnManager-remote-management",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.327 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "a18eb180-398e-4302-942e-c3d7e55ad496",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.327 +0200"
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.341 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d5e73a7f-d85b-437b-ab2e-64c94061c5ff",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.341 +0200"
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
 +
                },
 +
                "value": "started",
 +
                "@class": "StateFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.350 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "f1a41f5c-42a3-47ec-b289-6811e62a1c94",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.350 +0200"
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "date": "2021-06-30 16:38:26.464 +0200",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.346 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "6142d408-f43c-4db7-851f-1dfeb4d98b99",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.346 +0200"
 +
                },
 +
                "event": {
 +
                    "@class": "ValueSchema",
 +
                    "schema": "String",
 +
                    "value": "started"
 +
                },
 +
                "@class": "EventFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        }
 +
    ]
 
}
 
}
−
</pre>
+
</source>
  
−
===== Java API =====
 
−
<pre>
 
−
public <R extends Resource> R updateResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
 
−
</pre>
 
  
−
====== Example ======
+
Reading the response we can observe the following properties:
  
−
<pre>
+
* '''header''': The service generated/managed the ''header'' for each entity and relation instances;
 +
* '''propagationConstraint''': The service generated the ''propagationConstraint'' with default values when not provided by the client;
 +
* '''@superClasses''': The service included the '''@superClasses''' property. This is required because the client can be model agnostic or could not know the type of an instance. In any case, the client should be able to manage the unknown instances. The list of supertypes enables the client to instantiate the closer type. The list is ordered starting by the first supertype and arriving to the base type. As last resort, the client should be capable of instantiating the base type. When the type of an instance is a base type (e.g. ConsistsOf), the @superClasses property is empty.
  
−
/* 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*/
+
==== Schema Violation ====
−
networkingFacet = (NetworkingFacet) hostingNode.getIdentificationFacets().get(0);
+
−
networkingFacet.setAdditionalProperty("username", "luca.frosini");
+
−
+
−
hostingNode = resourceRegistryPublisher.updateResource(hostingNode);
+
−
</pre>
+
  
−
There are also two other equivalent methods with the following signature:
+
As example, if you omit to include the EventFacet in the EService the service reply with a Schema Violation Exception.
  
−
<pre>
+
<source lang="JavaScript">
−
public String updateResource(String resource) throws ResourceNotFoundException, ResourceRegistryException;
+
{
−
public String updateResource(UUID uuid, String resource) throws ResourceNotFoundException, ResourceRegistryException;
+
    "@type": "SchemaViolationException",
−
</pre>
+
    "cause": null,
 +
    "stackTrace": [....],
 +
    "message": "A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances. The constraint has been defined by EService type.",
 +
    "localizedMessage": "A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances. The constraint has been defined by EService type.",
 +
    "suppressed": []
 +
}
 +
</source>
  
−
The first methods get the Resource to be created as JSON string instead of as Java class.
+
The error message contains information regarding:
−
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 violated constraint (i.e. A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances.);
−
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.
+
* the type which defined such a constraint (i.e. The constraint has been defined by EService type.). Please note that is important that the service provides such information because a constraint could be defied by a parent type. In such a way the developer is capable of retrieving the schema of the indicated type.
  
−
==== Delete Resource Instance ====
+
This exception can also be raised in case of a client request to delete or remove from context a mandatory facet.
  
−
===== REST API =====
+
=== Read Instance ===
−
<pre>
+
−
DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
−
</pre>
+
  
−
===== Java API =====
+
The following examples show how to request the service to include Contexts in the Header.
−
<pre>
+
−
public <R extends Resource> boolean deleteResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
====== Example ======
+
==== Read via Java Client ====
  
−
<pre>
+
<source lang="java">
−
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);
+
public <ERElem extends ERElement> ERElem read(ERElem er) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
−
</pre>
+
  
−
There is also another equivalent methods with the following signature:
+
public <ERElem extends ERElement> ERElem read(Class<ERElem> clazz, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 +
 +
public String read(String type, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 +
</source>
  
−
<pre>
+
===== Read via Java Client Example =====
−
public boolean deleteResource(UUID uuid) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The method just need the UUID of the Resource to be deleted.
+
<source lang="java">
 +
// This is the way to enable Hierarchical Mode
 +
// ResourceRegistryPublisherFactory.setHierarchicalMode(true);
  
−
=== Relation Instances APIs ===
+
// This is the way to request the service to include the contexts in the header of the isntances
−
==== ConsistsOf ====
+
ResourceRegistryPublisherFactory.includeContextsInInstanceHeader(true);
  
−
===== Create ConsistsOf Instance =====
+
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
EService eService = resourceRegistryPublisher.read(EService.class, uuid);
 +
</source>
  
−
====== REST API ======
+
==== Read via REST API ====
  
−
'''Example 1'''
+
<pre>GET /instances/{TYPE_NAME}/{UUID}</pre>
−
<pre>
+
−
PUT /resource-registry/er/consistsOf/IsIdentifiedBy
+
−
</pre>
+
  
−
In this example the target Facet already exists. The Service set automatically
+
===== Read via REST Example =====
−
the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
to default values (i.e. remove=cascadeWhenOrphan, add=propagate)
+
  
−
'''''Request Body'''''
+
In the example, the EService with UUID 7f37a79d-0c00-4166-8a68-165de0a438bf and all its facets belong only to the context with UUID ca50eb95-b76c-44fd-9182-229d39c3c9e2 (the UUID of /gcube).
−
<pre>
+
−
{
+
−
"@class":"IsIdentifiedBy",  
+
−
"source" : {
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"} // The HostingNode must be already created. The header with UUId is enough.
+
−
}
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933"},
+
−
/* In this example we suppose that the NetworkingFacet already exists, so the UUID is enought to attach it by using IsIdentifiedBy relation */
+
−
}
+
−
}
+
−
</pre>
+
  
−
'''''Response'''''
+
'''Request URL'''
−
<pre>
+
−
{
+
−
"@class":"IsIdentifiedBy",
+
−
"propagationConstraint":{
+
−
"add":"propagate",
+
−
"remove": "cascadeWhenOrphan"
+
−
},
+
−
"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"
+
−
}
+
−
}
+
−
</pre>
+
  
−
'''Example 2'''
+
<pre>GET /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf?includeContextsInHeader=true</pre>
  
−
<pre>
+
'''Response Body'''
−
PUT /resource-registry/er/consistsOf/ConsistsOf
+
−
</pre>
+
  
−
In this example the target Facet is created contestually with ConsistsOf relation.
+
<source lang="JavaScript">
−
Moreover the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
are explicitly set (i.e. remove=cascade, add=propagate).
+
−
 
+
−
'''''Request Body'''''
+
−
<pre>
+
 
{
 
{
−
"@class":"ConsistsOf",  
+
    "header": {
−
"propagationConstraint":{
+
        "@class": "Header",
−
"add":"propagate",
+
        "creationTime": "2021-07-01 08:51:02.353 +0200",
−
"remove": "cascade"
+
        "createdBy": "luca.frosini",
−
},
+
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
−
"source" : {
+
        "lastUpdateBy": "luca.frosini",
−
"@class":"HostingNode",
+
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"} // The HostingNode must be already created. The header with UUId is enough.
+
        "contexts": [
−
}
+
            "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
−
"target":{  
+
        ]
−
"@class":"CPUFacet",
+
    },
−
"model":"Opteron",
+
    "@class": "EService",
−
"vendor":"AMD",
+
    "@superClasses": [
−
"clockSpeed":"3 GHz"
+
        "Service",
−
}
+
        "GCubeResource",
 +
        "Resource"
 +
    ],
 +
    "consistsOf": [
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.312 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "3b653a72-b182-41d6-bcc5-97e0141f0ceb",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.312 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "IsIdentifiedBy",
 +
            "@superClasses": [
 +
                "ConsistsOf"
 +
            ],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "name": "WhnManager",
 +
                "description": "Web Hosting Node Service",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.298 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "97984812-90e6-4eb7-b804-50a9ad3fe4fb",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.298 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "optional": "false",
 +
                "version": "2.0.0-4.15.0-132431",
 +
                "group": "VREManagement",
 +
                "@class": "SoftwareFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.322 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "5c78bec3-2fa6-46b3-892d-d41bed93e136",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.322 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "type": null,
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
 +
                "entryName": "whnmanager",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.318 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "f66a9fdf-3d5c-45fd-8437-6fecec463c4c",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.318 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.332 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d4aec29c-3f18-4464-94ae-5fb77306eb82",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.332 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "type": null,
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
 +
                "entryName": "WhnManager-remote-management",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.327 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "a18eb180-398e-4302-942e-c3d7e55ad496",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.327 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.341 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d5e73a7f-d85b-437b-ab2e-64c94061c5ff",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.341 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "value": "started",
 +
                "@class": "StateFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.350 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "f1a41f5c-42a3-47ec-b289-6811e62a1c94",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.350 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "date": "2021-06-30 16:38:26.464 +0200",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.346 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "6142d408-f43c-4db7-851f-1dfeb4d98b99",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.346 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "event": {
 +
                    "@class": "ValueSchema",
 +
                    "schema": "String",
 +
                    "value": "started"
 +
                },
 +
                "@class": "EventFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        }
 +
    ]
 
}
 
}
−
</pre>
+
</source>
  
−
'''''Response'''''
+
=== Update Instance ===
−
<pre>
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...},
+
−
"propagationConstraint":{
+
−
"add":"propagate",
+
−
"remove": "cascade"
+
−
},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
}
+
−
</pre>
+
  
−
====== Java API ======
+
==== Update via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> C createConsistsOf(C consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
'''Example 1'''
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem update(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
  
−
<pre>
+
public String update(String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
IsIdentifiedBy isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
−
resourceRegistryPublisher.createConsistsOf(isIdentifiedBy);
+
public String update(String type, String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
</pre>
+
 +
public String update(String type, String json, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 +
</source>
  
−
'''Example 2'''
+
The last is more efficient than the second and third because the client must not deserialize the JSON to get the instance UUID and/or the instance type.
  
−
<pre>
+
===== Update via Java Client Example =====
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
  
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
<source lang="java">
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
UUID uuid = UUID.fromString("44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9");
−
propagationConstraint.setAddConstraint(AddConstraint.propagate);
+
StateFacet stateFacet = resourceRegistryPublisher.read(StateFacet.class, uuid);
 +
stateFacet.setValue("ready");
 +
stateFacet = resourceRegistryPublisher.update(stateFacet);
 +
</source>
  
−
ConsistsOf consistsOf = new ConsistsOfImpl<Resource, Facet>(hostingNode, cpuFacet, propagationConstraint);
+
==== Update via REST API ====
−
consistsOf = resourceRegistryPublisher.createConsistsOf(consistsOf);
+
−
</pre>
+
  
 +
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
  
−
There are also two other equivalent methods with the following signature:
+
===== Update via REST API Example =====
  
−
<pre>
+
'''Request URL'''
−
public String createConsistsOf(String consistsOfType, String cnsistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
−
+
−
public String createConsistsOf(String consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The first methods get the '''consistsOfType''' to be created as JSON string instead of as Java class.
+
<pre>PUT  /instances/CPUFacet/44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9</pre>
−
The second get also the '''consistsOfType''' 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 '''consistsOfType''' is the same specified in the header of the serialized resource.
+
  
−
===== Delete ConsistsOf Instance =====
+
'''Request Body'''
  
−
====== REST API ======
+
<source lang="JavaScript">
 +
{
 +
  "header": {
 +
    "@class": "Header",
 +
    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
    "createdBy": "luca.frosini",
 +
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
    "lastUpdateBy": "luca.frosini",
 +
    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
 +
  },
 +
  "value": "ready",
 +
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 +
}
 +
</source>
 +
 
 +
'''Response Body'''
 +
 
 +
<source lang="JavaScript">
 +
{
 +
  "header": {
 +
    "@class": "Header",
 +
    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
    "createdBy": "luca.frosini",
 +
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
    "lastUpdateBy": "luca.frosini",
 +
    "lastUpdateTime": "2021-07-01 08:51:08.536 +0200"
 +
  },
 +
  "value": "ready",
 +
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 +
}
 +
</source>
  
−
'''Example 1'''
+
=== Delete Instance ===
−
<pre>
+
−
DELETE /resource-registry/er/consistsOf/02a7072c-4f72-4568-945b-9ddccc881e9f
+
−
</pre>
+
  
−
'''Example 2'''
+
==== Delete via Java Client ====
−
<pre>
+
−
DELETE /resource-registry/er/consistsOf/9bff49c8-c0a7-45de-827c-accb71defbd3
+
−
</pre>
+
  
−
====== Java API ======
+
<source lang="java">
−
<pre>
+
public <ERElem extends ERElement> boolean delete(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> boolean deleteConsistsOf(C consistsOf) throws ResourceRegistryException;
+
−
</pre>
+
  
−
'''Example 1'''
+
public boolean delete(String type, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
<pre>
+
</source>
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(isIdentifiedBy);
+
−
</pre>
+
  
−
'''Example 2'''
+
===== Delete via Java Client Example =====
−
<pre>
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(consistsOf);
+
−
</pre>
+
  
 +
<source lang="java">
 +
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
boolean deleted = resourceRegistryPublisher.delete(EService.NAME, uuid);
 +
</source>
  
−
There is also another equivalent methods with the following signature:
+
==== Delete via REST API ====
  
−
<pre>
+
<pre>DELETE  /instances/{TYPE_NAME}/{UUID}</pre>
−
public boolean deleteConsistsOf(UUID uuid) throws ResourceRegistryException;
+
−
</pre>
+
  
−
The method just need the UUID of the ConsistsOf relation to be deleted.
+
===== Delete via REST Example =====
  
−
'''Example 1'''
+
'''Request URL'''
−
<pre>
+
−
UUID uuid = UUID.fromString("02a7072c-4f72-4568-945b-9ddccc881e9f")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+
  
−
'''Example 2'''
+
<pre>DELETE /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</pre>
−
<pre>
+
−
UUID uuid = UUID.fromString("9bff49c8-c0a7-45de-827c-accb71defbd3")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+

Latest revision as of 10:21, 18 September 2021

These sections provide information regarding how to interact with Resource Registry Service for Entities and Relations instances 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.

Instances Management

Instances Management is responsible for the management of entities and relation instances. It offers the following APIs:

  • List: it allows to list instances of a certain type;
  • Create: it allows to create a new entity or relation instance in a certain context;
  • Exists: it allows to check if an instance exists in a certain context;
  • Read: it allows to get the representation of the requested instance in a certain context;
  • Update: it allows to update an instance in a certain context;
  • Delete: it allows to delete an instance.

The Instances Management implements the following policies:

  • it manages the Header automatically;
  • it allows identifying an instance via the Universally Unique Identifier (UUID) specified in the Header;
  • it allows the creation of an instance only if the declared type is already present in the system (previously registered via the Types Collection;
  • it validates the instance against the schema of the defined type;
  • it imposes the default values of propagation constraints (IsRelatedTo (remove=keep, add=unpropagate); ConsistsOf (remove=cascadeWhenOrphan, add=propagate).) when the client does not specify their values;
  • it guarantees propagation constraints.

Instances Collection

The following table shows the exposed APIs as REST Collection.

Operation HTTP Method URL
List GET /instances/{TYPE_NAME}[?polymorphic=true]
Create PUT /instances/{TYPE_NAME}/{UUID}
Exists HEAD /instances/{TYPE_NAME}/{UUID}
Read GET /instances/{TYPE_NAME}/{UUID}
Update PUT /instances/{TYPE_NAME}/{UUID}
Delete DELETE /instances/{TYPE_NAME}/{UUID}

Security configuration based on Authorization Framework make this port type accessible only from Resource Manager. In other words, no others client is allowed to manage types rather than Resource Manager.

Instances Collection Administrative capabilities

Operation HTTP Method URL
List GET /instances/{TYPE_NAME}[?polymorphic=true&hierarchical=false&includeContextsInHeader=false]
Read GET /instances/{TYPE_NAME}/{UUID}[?hierarchical=false&includeContextsInHeader=false]
Get Instance Contexts GET /instances/{TYPE_NAME}/{UUID}/contexts

Administrators are entitled to specify the following two query parameter in case of read and list operation:

An administrator can also request the list of contexts an instance belongs to. The result is an array of strings containing the UUID of contexts.

Hierarchical Mode

An administrator has the possibilities not only the instances belonging to the current context (i.e. the context identified by the gCube Token) but also all the instances in all contexts which are children of the current context.

This functionality is only available for the list and the read operations.

This functionality enables an administrator to have a complete overview of the instances at any context tree level.

Thanks to this functionality:

  • it is possible to create an instance at the VRE level, but it is not needed to add the instance at VO level just for administrator overview;
  • the administrator is capable of observing the instance at any higher level in the context hierarchy;
  • any "normal" client read only the context instance.
Contexts in Header

This functionality allows listing all the contexts an instance belongs to. Used in conjunction with hierarchical mode provides the whole picture of the description of the resource and all different contexts it belongs. Please note that different facets in different contexts can describe a resource.

The list of contexts is included in the header as an array of strings containing the UUID of contexts.

Get Instance Contexts
Get Instance Contexts via Java Client
public Set<UUID> getElementContexts(String type, UUID instanceUUID) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
 
public <ERElem extends ERElement> Set<UUID> getElementContexts(ERElem er) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
Get Instance Contexts via REST API
GET /instances/{TYPE_NAME}/{UUID}/contexts
Code Type Description
200 String A JSON Array containing the list of instances added to the context

Resource Registry Publisher

Resource Registry Publisher is a java library providing RPC facilities to interact with Instances Management and Instances Sharing Management. 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 Instances Collection declare the following dependency in your pom.xml file. 

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-publisher</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.publisher.ResourceRegistryPublisher;
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisherFactory;
 
...
 
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();

The provided client exposes the available methods and options as explained below.

The source code of the resource-registry-publisher is available at https://code-repo.d4science.org/gCubeSystem/resource-registry-publisher

APIs

List Instances

List via Java Client

Signature 

public <ERElem extends ERElement> List<ERElem> list(Class<ERElem> clazz, Boolean polymorphic) throws ResourceRegistryException;
 
public String list(String type, Boolean polymorphic) throws ResourceRegistryException;
List via Java Client Example 1

The following snippet of code shows how to retrieve all the resource instances. 

ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
List<Resource> allResources = resourceRegistryPublisher.list(Resource.class, true);
List via Java Client Example 2

The following snippet of code shows how to retrieve all the EService instances (only the EService). 

ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
List<EService> allResources = resourceRegistryPublisher.list(EService.class, false);

List via REST API

List via REST API Example 1

The following request shows how to retrieve all the resource instances.

Request URL 

GET /instances/Resource?polymorphic=true
List via REST API Example 2

The following request shows how to retrieve all the EService instances (only the EService).

Request URL 

GET /instances/EService

Create Instance

Create via Java Client

Signature 

public <ERElem extends ERElement> ERElem create(ERElem er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
 
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;

The first method gets any instance of IdentifiableElement (i.e. Resources, Facets, ConsistsOf, IsRelatedTo) The second method gets the instance to be created as a JSON string instead of a Java class.


Create via Java Client Example
EService eService = new EServiceImpl();
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
Header header = new HeaderImpl(uuid);
eService.setHeader(header);
 
SoftwareFacet softwareFacet = new SoftwareFacetImpl();
softwareFacet.setGroup("WhnManager");
softwareFacet.setName("VREManagement");
softwareFacet.setVersion("2.0.0-4.15.0-132431");
softwareFacet.setDescription("Web Hosting Node Service");
 
IsIdentifiedBy<Resource, Facet> isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(eService,
		softwareFacet, null);
eService.addFacet(isIdentifiedBy);
 
AccessPointFacet accessPointFacet = new AccessPointFacetImpl();
accessPointFacet.setEndpoint(new URI("http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager"));
accessPointFacet.setEntryName("whnmanager");
ValueSchema authz = new ValueSchemaImpl();
authz.setValue("gcube-token");
accessPointFacet.setAuthorization(authz);
eService.addFacet(accessPointFacet);
 
AccessPointFacet accessPointFacet2 = new AccessPointFacetImpl();
accessPointFacet2.setEndpoint(new URI("http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource"));
accessPointFacet2.setEntryName("WhnManager-remote-management");
ValueSchema authz2 = new ValueSchemaImpl();
authz2.setValue("gcube-token");
accessPointFacet2.setAuthorization(authz2);
eService.addFacet(accessPointFacet2);
 
 
EventFacet eventFacet = new EventFacetImpl();
eventFacet.setDate(Calendar.getInstance().getTime());
ValueSchema event = new ValueSchemaImpl();
event.setSchema(new URI("String"));
event.setValue("started");
eventFacet.setEvent(event);
eService.addFacet(eventFacet);
 
StateFacet stateFacet = new StateFacetImpl();
stateFacet.setValue("started");
eService.addFacet(stateFacet);
 
 
eService = resourceRegistryPublisher.create(eService);

Create via REST API

PUT  /instances/{TYPE_NAME}/{UUID}
Create via REST API Resource Example

The following listing shows an example of EService representation to be created.

Request URL 

PUT PUT /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf

Please note that EService and the UUID 7f37a79d-0c00-4166-8a68-165de0a438bf are parts of the request URI

Request Body 

{
    "@class": "EService",
    "header": {
        "@class": "Header",
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf"
    },
    "consistsOf": [
        {
            "@class": "IsIdentifiedBy",
            "header": null,
            "propagationConstraint": null,
            "target": {
                "@class": "SoftwareFacet",
                "header": null,
                "name": "WhnManager",
                "group": "VREManagement",
                "version": "2.0.0-4.15.0-132431",
                "description": "Web Hosting Node Service",
                "qualifier": null,
                "optional": false
            }
        },
        {
            "@class": "ConsistsOf",
            "header": null,
            "propagationConstraint": null,
            "target": {
                "@class": "AccessPointFacet",
                "header": null,
                "entryName": "whnmanager",
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
                "protocol": null,
                "description": null,
                "authorization": {
                    "@class": "ValueSchema",
                    "value": "gcube-token"
                }
            }
        },
        {
            "@class": "ConsistsOf",
            "header": null,
            "propagationConstraint": null,
            "target": {
                "@class": "AccessPointFacet",
                "header": null,
                "entryName": "WhnManager-remote-management",
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
                "protocol": null,
                "description": null,
                "authorization": {
                    "@class": "ValueSchema",
                    "value": "gcube-token"
                }
            }
        },
        {
            "@class": "ConsistsOf",
            "header": null,
            "propagationConstraint": null,
            "target": {
                "@class": "StateFacet",
                "header": null,
                "value": "started"
            }
        },
        {
            "@class": "ConsistsOf",
            "header": null,
            "propagationConstraint": null,
            "target": {
                "@class": "EventFacet",
                "header": null,
                "event": {
                    "value": "started",
                    "schema": "String"
                },
                "date": "2021-06-30 14:38:26.464 +0000"
            }
        }
    ],
    "isRelatedTo": []
}

The following listing contains the response of the service containing the representation of the created EService:

Response Body 

{
    "header": {
        "@class": "Header",
        "creationTime": "2021-07-01 08:51:02.353 +0200",
        "createdBy": "luca.frosini",
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
        "lastUpdateBy": "luca.frosini",
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
    },
    "@class": "EService",
    "@superClasses": [
        "Service",
        "GCubeResource",
        "Resource"
    ],
    "consistsOf": [
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.312 +0200",
                "createdBy": "luca.frosini",
                "uuid": "3b653a72-b182-41d6-bcc5-97e0141f0ceb",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.312 +0200"
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "IsIdentifiedBy",
            "@superClasses": [
                "ConsistsOf"
            ],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "name": "WhnManager",
                "description": "Web Hosting Node Service",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.298 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "97984812-90e6-4eb7-b804-50a9ad3fe4fb",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.298 +0200"
                },
                "optional": "false",
                "version": "2.0.0-4.15.0-132431",
                "group": "VREManagement",
                "@class": "SoftwareFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.322 +0200",
                "createdBy": "luca.frosini",
                "uuid": "5c78bec3-2fa6-46b3-892d-d41bed93e136",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.322 +0200"
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "authorization": {
                    "@class": "ValueSchema"
                    "value": "gcube-token"
                },
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
                "entryName": "whnmanager",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.318 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "f66a9fdf-3d5c-45fd-8437-6fecec463c4c",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.318 +0200"
                },
                "@class": "AccessPointFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.332 +0200",
                "createdBy": "luca.frosini",
                "uuid": "d4aec29c-3f18-4464-94ae-5fb77306eb82",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.332 +0200"
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "authorization": {
                    "@class": "ValueSchema"
                    "value": "gcube-token"
                },
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
                "entryName": "WhnManager-remote-management",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.327 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "a18eb180-398e-4302-942e-c3d7e55ad496",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.327 +0200"
                },
                "@class": "AccessPointFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.341 +0200",
                "createdBy": "luca.frosini",
                "uuid": "d5e73a7f-d85b-437b-ab2e-64c94061c5ff",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.341 +0200"
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.336 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
                },
                "value": "started",
                "@class": "StateFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.350 +0200",
                "createdBy": "luca.frosini",
                "uuid": "f1a41f5c-42a3-47ec-b289-6811e62a1c94",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.350 +0200"
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "date": "2021-06-30 16:38:26.464 +0200",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.346 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "6142d408-f43c-4db7-851f-1dfeb4d98b99",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.346 +0200"
                },
                "event": {
                    "@class": "ValueSchema",
                    "schema": "String",
                    "value": "started"
                },
                "@class": "EventFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        }
    ]
}


Reading the response we can observe the following properties:

  • header: The service generated/managed the header for each entity and relation instances;
  • propagationConstraint: The service generated the propagationConstraint with default values when not provided by the client;
  • @superClasses: The service included the @superClasses property. This is required because the client can be model agnostic or could not know the type of an instance. In any case, the client should be able to manage the unknown instances. The list of supertypes enables the client to instantiate the closer type. The list is ordered starting by the first supertype and arriving to the base type. As last resort, the client should be capable of instantiating the base type. When the type of an instance is a base type (e.g. ConsistsOf), the @superClasses property is empty.

Schema Violation

As example, if you omit to include the EventFacet in the EService the service reply with a Schema Violation Exception. 

{
    "@type": "SchemaViolationException",
    "cause": null,
    "stackTrace": [....],
    "message": "A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances. The constraint has been defined by EService type.",
    "localizedMessage": "A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances. The constraint has been defined by EService type.",
    "suppressed": []
}

The error message contains information regarding:

  • the violated constraint (i.e. A EService must be described by ConsistsOf -> EventFacet with the following constraint: max:null, min:1. Found 0 instances.);
  • the type which defined such a constraint (i.e. The constraint has been defined by EService type.). Please note that is important that the service provides such information because a constraint could be defied by a parent type. In such a way the developer is capable of retrieving the schema of the indicated type.

This exception can also be raised in case of a client request to delete or remove from context a mandatory facet.

Read Instance

The following examples show how to request the service to include Contexts in the Header.

Read via Java Client

public <ERElem extends ERElement> ERElem read(ERElem er) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 
public <ERElem extends ERElement> ERElem read(Class<ERElem> clazz, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 
public String read(String type, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
Read via Java Client Example
// This is the way to enable Hierarchical Mode
// ResourceRegistryPublisherFactory.setHierarchicalMode(true);
 
// This is the way to request the service to include the contexts in the header of the isntances
ResourceRegistryPublisherFactory.includeContextsInInstanceHeader(true);
 
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
EService eService = resourceRegistryPublisher.read(EService.class, uuid);

Read via REST API

GET /instances/{TYPE_NAME}/{UUID}
Read via REST Example

In the example, the EService with UUID 7f37a79d-0c00-4166-8a68-165de0a438bf and all its facets belong only to the context with UUID ca50eb95-b76c-44fd-9182-229d39c3c9e2 (the UUID of /gcube).

Request URL 

GET /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf?includeContextsInHeader=true

Response Body 

{
    "header": {
        "@class": "Header",
        "creationTime": "2021-07-01 08:51:02.353 +0200",
        "createdBy": "luca.frosini",
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
        "lastUpdateBy": "luca.frosini",
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
        "contexts": [
            "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
        ]
    },
    "@class": "EService",
    "@superClasses": [
        "Service",
        "GCubeResource",
        "Resource"
    ],
    "consistsOf": [
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.312 +0200",
                "createdBy": "luca.frosini",
                "uuid": "3b653a72-b182-41d6-bcc5-97e0141f0ceb",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.312 +0200",
                "contexts": [
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                ]
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "IsIdentifiedBy",
            "@superClasses": [
                "ConsistsOf"
            ],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "name": "WhnManager",
                "description": "Web Hosting Node Service",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.298 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "97984812-90e6-4eb7-b804-50a9ad3fe4fb",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.298 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "optional": "false",
                "version": "2.0.0-4.15.0-132431",
                "group": "VREManagement",
                "@class": "SoftwareFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.322 +0200",
                "createdBy": "luca.frosini",
                "uuid": "5c78bec3-2fa6-46b3-892d-d41bed93e136",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.322 +0200",
                "contexts": [
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                ]
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "authorization": {
                    "@class": "ValueSchema",
                    "type": null,
                    "value": "gcube-token"
                },
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
                "entryName": "whnmanager",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.318 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "f66a9fdf-3d5c-45fd-8437-6fecec463c4c",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.318 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "AccessPointFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.332 +0200",
                "createdBy": "luca.frosini",
                "uuid": "d4aec29c-3f18-4464-94ae-5fb77306eb82",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.332 +0200",
                "contexts": [
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                ]
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "authorization": {
                    "@class": "ValueSchema",
                    "type": null,
                    "value": "gcube-token"
                },
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
                "entryName": "WhnManager-remote-management",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.327 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "a18eb180-398e-4302-942e-c3d7e55ad496",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.327 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "AccessPointFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.341 +0200",
                "createdBy": "luca.frosini",
                "uuid": "d5e73a7f-d85b-437b-ab2e-64c94061c5ff",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.341 +0200",
                "contexts": [
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                ]
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.336 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "value": "started",
                "@class": "StateFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        },
        {
            "header": {
                "@class": "Header",
                "creationTime": "2021-07-01 08:51:02.350 +0200",
                "createdBy": "luca.frosini",
                "uuid": "f1a41f5c-42a3-47ec-b289-6811e62a1c94",
                "lastUpdateBy": "luca.frosini",
                "lastUpdateTime": "2021-07-01 08:51:02.350 +0200",
                "contexts": [
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                ]
            },
            "propagationConstraint": {
                "@class": "PropagationConstraint",
                "add": "propagate",
                "remove": "cascade"
            },
            "@class": "ConsistsOf",
            "@superClasses": [],
            "source": {
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "@class": "EService",
                "@superClasses": [
                    "Service",
                    "GCubeResource",
                    "Resource"
                ]
            },
            "target": {
                "date": "2021-06-30 16:38:26.464 +0200",
                "header": {
                    "@class": "Header",
                    "creationTime": "2021-07-01 08:51:02.346 +0200",
                    "createdBy": "luca.frosini",
                    "uuid": "6142d408-f43c-4db7-851f-1dfeb4d98b99",
                    "lastUpdateBy": "luca.frosini",
                    "lastUpdateTime": "2021-07-01 08:51:02.346 +0200",
                    "contexts": [
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
                    ]
                },
                "event": {
                    "@class": "ValueSchema",
                    "schema": "String",
                    "value": "started"
                },
                "@class": "EventFacet",
                "@superClasses": [
                    "Facet"
                ]
            }
        }
    ]
}

Update Instance

Update via Java Client

Signature 

public <ERElem extends ERElement> ERElem update(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 
public String update(String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 
public String update(String type, String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 
public String update(String type, String json, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;

The last is more efficient than the second and third because the client must not deserialize the JSON to get the instance UUID and/or the instance type.

Update via Java Client Example
UUID uuid = UUID.fromString("44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9");
StateFacet stateFacet = resourceRegistryPublisher.read(StateFacet.class, uuid);
stateFacet.setValue("ready");
stateFacet = resourceRegistryPublisher.update(stateFacet);

Update via REST API

PUT  /instances/{TYPE_NAME}/{UUID}
Update via REST API Example

Request URL 

PUT  /instances/CPUFacet/44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9

Request Body 

{
  "header": {
    "@class": "Header",
    "creationTime": "2021-07-01 08:51:02.336 +0200",
    "createdBy": "luca.frosini",
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
    "lastUpdateBy": "luca.frosini",
    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
  },
  "value": "ready",
  "@class": "StateFacet",
  "@superClasses": [
    "Facet"
  ]
}

Response Body 

{
  "header": {
    "@class": "Header",
    "creationTime": "2021-07-01 08:51:02.336 +0200",
    "createdBy": "luca.frosini",
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
    "lastUpdateBy": "luca.frosini",
    "lastUpdateTime": "2021-07-01 08:51:08.536 +0200"
  },
  "value": "ready",
  "@class": "StateFacet",
  "@superClasses": [
    "Facet"
  ]
}

Delete Instance

Delete via Java Client

public <ERElem extends ERElement> boolean delete(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 
public boolean delete(String type, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
Delete via Java Client Example
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
boolean deleted = resourceRegistryPublisher.delete(EService.NAME, uuid);

Delete via REST API

DELETE  /instances/{TYPE_NAME}/{UUID}
Delete via REST Example

Request URL 

DELETE /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf
Retrieved from "https://wiki.gcube-system.org/index.php?title=Resource_Registry_Service_-_Instances_Management&oldid=34640"