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

From Gcube Wiki
Jump to: navigation, search
(→‎IsRelatedTo)
(→‎Read Instance)
 
(115 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>
+
  
−
==== Alternative JAVA API ====
+
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>
+
  
−
==== Alternative JAVA API ====
+
To use the Java library to interact with Instances Collection declare the following dependency in your pom.xml file.
  
−
There are also two other equivalent methods with the following signature:
+
<source lang="xml">
 +
<dependency>
 +
<groupId>org.gcube.information-system</groupId>
 +
<artifactId>resource-registry-publisher</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
−
<pre>
+
To use the client you just need to instantiate the client via the provided factory.
−
public String updateFacet(String facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
public String updateFacet(UUID uuid, String facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The first methods get the Facet to be created as JSON string instead of as Java class.
+
<source lang="java">
−
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.  
+
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisher;
−
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.
+
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisherFactory;
  
−
=== Delete Facet Instance ===
+
...
  
−
==== REST API ====
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
<pre>
+
</source>
−
DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82
+
−
</pre>
+
  
−
'''''Response Body'''''
+
The provided client exposes the available methods and options as explained below.
−
<pre>
+
−
true
+
−
</pre>
+
  
−
==== Java API ====
+
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]
  
−
<pre>
+
== APIs ==
−
public <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
=== List Instances ===
  
−
<pre>
+
==== List via Java Client ====
−
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
'''Signature'''
  
−
There is also another equivalent methods with the following signature:
+
<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>
  
−
<pre>
+
===== List via Java Client Example 1 =====
−
public boolean deleteFacet(UUID uuid) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The method just need the UUID of the Facet to be deleted.
+
The following snippet of code shows how to retrieve all the resource instances.
  
−
== Resource Instances APIs ==
+
<source lang="java">
 +
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
 +
List<Resource> allResources = resourceRegistryPublisher.list(Resource.class, true);
 +
</source>
  
−
=== Create Resource Instance ===
+
===== List via Java Client Example 2 =====
  
−
==== REST API ====
+
The following snippet of code shows how to retrieve all the EService instances (only the EService).
−
<pre>
+
−
PUT /resource-registry/er/resource/HostingNode
+
−
</pre>
+
  
−
'''''Request Body'''''
+
<source lang="java">
−
<pre>
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
{
+
List<EService> allResources = resourceRegistryPublisher.list(EService.class, false);
−
"@class":"HostingNode",
+
</source>
−
"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>
+
==== List via REST API ====
  
−
'''''Response'''''
+
===== List via REST API Example 1 =====
−
<pre>
+
−
{
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"},
+
−
"consistsOf":[
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
},{
+
−
"@class":"IsIdentifiedBy",
+
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
−
"ipAddress" : "146.48.87.183",
+
−
"hostName": "pc-frosini.isti.cnr.it",
+
−
"domainName" : "isti.cnr.it",
+
−
"mask" : "255.255.248.0",
+
−
"broadcastAddress":"146.48.87.255"
+
−
}
+
−
}
+
−
],
+
−
"isRelatedTo":[
+
−
{
+
−
"@class":"Hosts",
+
−
"header":{"uuid":"47494ad0-e606-4630-9def-4c607761ae14", ...},
+
−
"propagationConstraint":{
+
−
"add":"unpropagate",
+
−
"remove": "cascade"
+
−
},
+
−
"target":{
+
−
"@class":"EService",
+
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...}
+
−
}
+
−
}
+
−
]
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
The following request shows how to retrieve all the resource instances.
  
−
<pre>
+
'''Request URL'''
−
public <R extends Resource> R createResource(R resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
<pre>GET /instances/Resource?polymorphic=true</pre>
  
−
<pre>
+
===== List via REST API Example 2 =====
−
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);
+
The following request shows how to retrieve all the EService instances (only the EService).
  
−
HostingNode hostingNode = new HostingNodeImpl();
+
'''Request URL'''
  
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
<pre>GET /instances/EService</pre>
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
−
hostingNode.addFacet(cpuFacet);
+
  
−
isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
=== Create Instance ===
−
hostingNode.attachFacet(isIdentifiedBy);
+
  
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
==== Create via Java Client ====
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.unpropagate);
+
  
−
Hosts<HostingNode, EService> hosts = new HostsImpl<HostingNode, EService>(hostingNode, eService, propagationConstraint);
+
'''Signature'''
−
hostingNode.attachResource(hosts);
+
  
−
hostingNode = resourceRegistryPublisher.createResource(hostingNode);
+
<source lang="java">
−
</pre>
+
public <ERElem extends ERElement> ERElem create(ERElem er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
  
 +
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
 +
</source>
  
−
==== Alternative JAVA API ====
+
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.
  
−
There are also two other equivalent methods with the following signature:
 
  
−
<pre>
+
===== Create via Java Client Example =====
−
public String createResource(String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
<source lang="Java">
 +
EService eService = new EServiceImpl();
 +
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
Header header = new HeaderImpl(uuid);
 +
eService.setHeader(header);
  
−
public String createResource(String resourceType, String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
SoftwareFacet softwareFacet = new SoftwareFacetImpl();
−
</pre>
+
softwareFacet.setGroup("WhnManager");
 +
softwareFacet.setName("VREManagement");
 +
softwareFacet.setVersion("2.0.0-4.15.0-132431");
 +
softwareFacet.setDescription("Web Hosting Node Service");
  
−
The first methods get the Resource to be created as JSON string instead of as Java class.
+
IsIdentifiedBy<Resource, Facet> isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(eService,
−
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.
+
softwareFacet, null);
−
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.
+
eService.addFacet(isIdentifiedBy);
  
−
=== Update Resource Instance ===
+
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);
  
−
==== REST API ====
+
AccessPointFacet accessPointFacet2 = new AccessPointFacetImpl();
−
<pre>
+
accessPointFacet2.setEndpoint(new URI("http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource"));
−
POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
accessPointFacet2.setEntryName("WhnManager-remote-management");
−
</pre>
+
ValueSchema authz2 = new ValueSchemaImpl();
 +
authz2.setValue("gcube-token");
 +
accessPointFacet2.setAuthorization(authz2);
 +
eService.addFacet(accessPointFacet2);
  
−
'''''Request Body'''''
 
−
<pre>
 
−
{
 
−
"@class":"HostingNode",
 
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
 
−
"consistsOf":[
 
−
{
 
−
"@class":"ConsistsOf",
 
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
 
−
"target":{
 
−
"@class":"CPUFacet",
 
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
 
−
"model":"Opteron",
 
−
"vendor":"AMD",
 
−
"clockSpeed":"1 GHz"
 
−
}
 
−
},{
 
−
"@class":"IsIdentifiedBy",
 
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
 
−
"target":{
 
−
"@class":"NetworkingFacet",
 
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
 
−
"ipAddress" : "146.48.87.183",
 
−
"hostName": "pc-frosini.isti.cnr.it",
 
−
"domainName" : "isti.cnr.it",
 
−
"mask" : "255.255.248.0",
 
−
"broadcastAddress":"146.48.87.255",
 
−
"username":"luca.frosini" /* Added this property */
 
−
}
 
−
}
 
−
]
 
−
}
 
−
</pre>
 
  
−
'''''Response'''''
+
EventFacet eventFacet = new EventFacetImpl();
−
<pre>
+
eventFacet.setDate(Calendar.getInstance().getTime());
−
{
+
ValueSchema event = new ValueSchemaImpl();
−
"@class":"HostingNode",
+
event.setSchema(new URI("String"));
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
event.setValue("started");
−
"consistsOf":[
+
eventFacet.setEvent(event);
−
{
+
eService.addFacet(eventFacet);
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
},{
+
−
"@class":"IsIdentifiedBy",
+
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
−
"ipAddress" : "146.48.87.183",
+
−
"hostName": "pc-frosini.isti.cnr.it",
+
−
"domainName" : "isti.cnr.it",
+
−
"mask" : "255.255.248.0",
+
−
"broadcastAddress":"146.48.87.255",
+
−
"username":"luca.frosini"
+
−
}
+
−
}
+
−
]
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
StateFacet stateFacet = new StateFacetImpl();
−
<pre>
+
stateFacet.setValue("started");
−
public <R extends Resource> R updateResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
+
eService.addFacet(stateFacet);
−
</pre>
+
  
−
===== Example =====
 
  
−
<pre>
+
eService = resourceRegistryPublisher.create(eService);
  
−
/* 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*/
+
</source>
−
networkingFacet = (NetworkingFacet) hostingNode.getIdentificationFacets().get(0);
+
−
networkingFacet.setAdditionalProperty("username", "luca.frosini");
+
−
+
−
hostingNode = resourceRegistryPublisher.updateResource(hostingNode);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
==== Create via REST API ====
  
−
There are also two other equivalent methods with the following signature:
+
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
  
−
<pre>
+
===== Create via REST API Resource Example =====
−
public String updateResource(String resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
public String updateResource(UUID uuid, String resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
The first methods get the Resource to be created as JSON string instead of as Java class.
+
The following listing shows an example of EService representation to be created.  
−
The second get also the '''uuid''' as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string.
+
−
The second method is more efficient but you have to be sure that the '''uuid''' is the same specified in the header of the serialized resource.
+
  
−
=== Delete Resource Instance ===
+
'''Request URL'''
  
−
==== REST API ====
+
<pre>PUT PUT /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</pre>
−
<pre>
+
−
DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
−
</pre>
+
  
−
==== Java API ====
+
Please note that '''EService''' and the UUID '''7f37a79d-0c00-4166-8a68-165de0a438bf''' are parts of the request URI
−
<pre>
+
−
public <R extends Resource> boolean deleteResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
'''Request Body'''
  
−
<pre>
+
<source lang="JavaScript">
−
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);
+
{
−
</pre>
+
    "@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": []
 +
}
 +
</source>
  
−
==== Alternative JAVA API ====
+
The following listing contains the response of the service containing the representation of the created EService:
  
−
There is also another equivalent methods with the following signature:
+
'''Response Body'''
  
−
<pre>
+
<source lang="JavaScript">
−
public boolean deleteResource(UUID uuid) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
−
 
+
−
The method just need the UUID of the Resource to be deleted.
+
−
 
+
−
== ConsistsOf ==
+
−
 
+
−
=== Create ConsistsOf Instance ===
+
−
 
+
−
==== REST API ====
+
−
 
+
−
===== Example 1 =====
+
−
<pre>
+
−
PUT /resource-registry/er/consistsOf/IsIdentifiedBy
+
−
</pre>
+
−
 
+
−
In this example the target Facet already exists. The Service set automatically
+
−
the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
to default values (i.e. remove=cascadeWhenOrphan, add=propagate)
+
−
 
+
−
'''''Request Body'''''
+
−
<pre>
+
 
{
 
{
−
"@class":"IsIdentifiedBy",  
+
    "header": {
−
"source" : {
+
        "@class": "Header",
−
"@class":"HostingNode",
+
        "creationTime": "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.
+
        "createdBy": "luca.frosini",
−
}
+
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
−
"target":{  
+
        "lastUpdateBy": "luca.frosini",
−
"@class":"NetworkingFacet",
+
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200"
−
"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 */
+
    "@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"
 +
                ]
 +
            }
 +
        }
 +
    ]
 
}
 
}
−
</pre>
+
</source>
  
−
'''''Response'''''
 
−
<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 =====
+
Reading the response we can observe the following properties:
  
−
<pre>
+
* '''header''': The service generated/managed the ''header'' for each entity and relation instances;
−
PUT /resource-registry/er/consistsOf/ConsistsOf
+
* '''propagationConstraint''': The service generated the ''propagationConstraint'' with default values when not provided by the client;
−
</pre>
+
* '''@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.
  
−
In this example the target Facet is created contestually with ConsistsOf relation.
+
==== Schema Violation ====
−
Moreover the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
are explicitly set (i.e. remove=cascade, add=propagate).
+
  
−
'''''Request Body'''''
+
As example, if you omit to include the EventFacet in the EService the service reply with a Schema Violation Exception.
−
<pre>
+
−
{
+
−
"@class":"ConsistsOf",  
+
−
"propagationConstraint":{
+
−
"add":"propagate",
+
−
"remove": "cascade"
+
−
},
+
−
"source" : {
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"} // The HostingNode must be already created. The header with UUId is enough.
+
−
}
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"3 GHz"
+
−
}
+
−
}
+
−
</pre>
+
  
−
'''''Response'''''
+
<source lang="JavaScript">
−
<pre>
+
 
{
 
{
−
"@class":"ConsistsOf",
+
    "@type": "SchemaViolationException",
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...},
+
    "cause": null,
−
"propagationConstraint":{
+
    "stackTrace": [....],
−
"add":"propagate",
+
    "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.",
−
"remove": "cascade"
+
    "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": []
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
 
}
 
}
−
</pre>
+
</source>
−
 
+
−
==== Java API ====
+
−
 
+
−
<pre>
+
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> C createConsistsOf(C consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
−
 
+
−
===== Example 1 =====
+
−
 
+
−
<pre>
+
−
IsIdentifiedBy isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
−
resourceRegistryPublisher.createConsistsOf(isIdentifiedBy);
+
−
</pre>
+
  
−
===== Example 2 =====
+
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.
  
−
<pre>
+
This exception can also be raised in case of a client request to delete or remove from context a mandatory facet.
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
  
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
=== Read Instance ===
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.propagate);
+
  
−
ConsistsOf consistsOf = new ConsistsOfImpl<Resource, Facet>(hostingNode, cpuFacet, propagationConstraint);
+
The following examples show how to request the service to include Contexts in the Header.
−
consistsOf = resourceRegistryPublisher.createConsistsOf(consistsOf);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
==== Read via Java Client ====
  
−
There are also two other equivalent methods with the following signature:
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem read(ERElem er) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
  
−
<pre>
+
public <ERElem extends ERElement> ERElem read(Class<ERElem> clazz, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
−
public String createConsistsOf(String consistsOfType, String cnsistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
 
 
−
public String createConsistsOf(String consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
public String read(String type, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
−
</pre>
+
</source>
  
−
The first methods get the '''consistsOfType''' to be created as JSON string instead of as Java class.
+
===== Read via Java Client Example =====
−
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 ===
+
<source lang="java">
 +
// This is the way to enable Hierarchical Mode
 +
// ResourceRegistryPublisherFactory.setHierarchicalMode(true);
  
−
==== REST API ====
+
// This is the way to request the service to include the contexts in the header of the isntances
 +
ResourceRegistryPublisherFactory.includeContextsInInstanceHeader(true);
  
−
===== Example 1 =====
+
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
−
<pre>
+
EService eService = resourceRegistryPublisher.read(EService.class, uuid);
−
DELETE /resource-registry/er/consistsOf/02a7072c-4f72-4568-945b-9ddccc881e9f
+
</source>
−
</pre>
+
  
−
===== Example 2 =====
+
==== Read via REST API ====
−
<pre>
+
−
DELETE /resource-registry/er/consistsOf/9bff49c8-c0a7-45de-827c-accb71defbd3
+
−
</pre>
+
  
−
==== Java API ====
+
<pre>GET /instances/{TYPE_NAME}/{UUID}</pre>
−
<pre>
+
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> boolean deleteConsistsOf(C consistsOf) throws ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example 1 =====
+
===== Read via REST Example =====
−
<pre>
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(isIdentifiedBy);
+
−
</pre>
+
  
−
===== Example 2 =====
+
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>
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(consistsOf);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
'''Request URL'''
  
−
There is also another equivalent methods with the following signature:
+
<pre>GET /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf?includeContextsInHeader=true</pre>
  
−
<pre>
+
'''Response Body'''
−
public boolean deleteConsistsOf(UUID uuid) throws ResourceRegistryException;
+
−
</pre>
+
  
−
The method just need the UUID of the ConsistsOf relation to be deleted.
+
<source lang="JavaScript">
 +
{
 +
    "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"
 +
                ]
 +
            }
 +
        }
 +
    ]
 +
}
 +
</source>
  
−
===== Example 1 =====
+
=== Update Instance ===
−
<pre>
+
−
UUID uuid = UUID.fromString("02a7072c-4f72-4568-945b-9ddccc881e9f")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+
  
−
===== Example 2 =====
+
==== Update via Java Client ====
−
<pre>
+
−
UUID uuid = UUID.fromString("9bff49c8-c0a7-45de-827c-accb71defbd3")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+
  
−
== IsRelatedTo ==
+
'''Signature'''
  
−
=== Create IsRelatedTo Instance ===
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem update(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
  
−
==== REST API ====
+
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;
 +
</source>
  
−
===== Example =====
+
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 =====
−
PUT /resource-registry/er/isRelatedTo/Hosts
+
−
</pre>
+
  
−
In this example the target Resource already exists.
+
<source lang="java">
−
The [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
UUID uuid = UUID.fromString("44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9");
−
are explicitly set. Please note that otherwise the service set the
+
StateFacet stateFacet = resourceRegistryPublisher.read(StateFacet.class, uuid);
−
[[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
stateFacet.setValue("ready");
−
to default values (i.e. remove=keep, add=unpropagate)
+
stateFacet = resourceRegistryPublisher.update(stateFacet);
 +
</source>
  
−
'''''Request Body'''''
+
==== Update via REST API ====
−
<pre>
+
−
{
+
−
"@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>
+
  
−
'''''Response'''''
+
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
−
<pre>
+
−
{
+
−
"@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 ====
+
===== Update via REST API Example =====
  
−
<pre>
+
'''Request URL'''
−
public <I extends IsRelatedTo<? extends Resource, ? extends Resource>> I createIsRelatedTo(I isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
<pre>PUT  /instances/CPUFacet/44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9</pre>
  
−
<pre>
+
'''Request Body'''
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.propagate);
+
  
−
Hosts<HostingNode, EService> hosts = new HostsImpl<>(hostingNode, eService, propagationConstraint);
+
<source lang="JavaScript">
−
hosts = resourceRegistryPublisher.createIsRelatedTo(hosts);
+
{
−
</pre>
+
  "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>
  
−
==== Alternative Java API ====
+
'''Response Body'''
−
There are also two other equivalent methods with the following signature:
+
  
−
<pre>
+
<source lang="JavaScript">
−
public String createIsRelatedTo(String isRelatedToType, String isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
{
−
 
+
  "header": {
−
public String createIsRelatedTo(String isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
    "@class": "Header",
−
</pre>
+
    "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>
  
−
The first methods get the '''isRelatedTo''' to be created as JSON string instead of as Java class.
+
=== Delete Instance ===
−
The second get also the '''isRelatedTo''' 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 '''isRelatedToType''' is the same specified in the header of the serialized resource.
+
  
−
=== Delete IsRelatedTo Instance ===
+
==== Delete via Java Client ====
  
−
==== REST API ====
+
<source lang="java">
 +
public <ERElem extends ERElement> boolean delete(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
  
−
===== Example =====
+
public boolean delete(String type, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
<pre>
+
</source>
−
DELETE /resource-registry/er/isRelatedTo/47494ad0-e606-4630-9def-4c607761ae14
+
−
</pre>
+
  
−
==== Java API ====
+
===== Delete via Java Client Example =====
−
<pre>
+
−
public <I extends IsRelatedTo<? extends Resource, ? extends Resource>> boolean deleteIsRelatedTo(I isRelatedTo) throws ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
<source lang="java">
−
<pre>
+
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
−
boolean deleted = resourceRegistryPublisher.deleteIsRelatedTo(hosts);
+
boolean deleted = resourceRegistryPublisher.delete(EService.NAME, uuid);
−
</pre>
+
</source>
  
 +
==== Delete via REST API ====
  
−
==== Alternative Java API ====
+
<pre>DELETE  /instances/{TYPE_NAME}/{UUID}</pre>
−
There is also another equivalent methods with the following signature:
+
  
−
<pre>
+
===== Delete via REST Example =====
−
public boolean deleteIsRelatedTo(UUID uuid) throws ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
'''Request URL'''
−
The method just need the UUID of the ConsistsOf relation to be deleted.
+
  
−
<pre>
+
<pre>DELETE /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</pre>
−
UUID uuid = UUID.fromString("47494ad0-e606-4630-9def-4c607761ae14")
+
−
boolean deleted = resourceRegistryPublisher.deleteIsRelatedTo(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"