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

From Gcube Wiki
Jump to: navigation, search
m (→‎Example 2)
(→‎Read Instance)
 
(93 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
|}
 
|}
  
−
This section provides 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 ==
  
−
[[Information System Resource Registry#Resource_Registry_Publisher | Resource Registry Publisher]] has the following maven coordinates
+
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.
  
−
<pre>
+
The Instances Management implements the following policies:
−
<dependency>
+
−
<groupId>org.gcube.information-system</groupId>
+
−
<artifactId>resource-registry-publisher</artifactId>
+
−
<version>[1.0.0-SNAPSHOT, 2.0.0-SNAPSHOT)</version>
+
−
</dependency>
+
−
</pre>
+
  
−
To use the client, you need first get a ''ResourceRegistryPublisher'' instance.  
+
* 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.
  
−
By using ''ResourceRegistryPublisherFactory.create()'' method the library discovers the correct endpoint to interact with the Resource Registry for the current context.
+
== Instances Collection ==
  
−
<pre>
+
The following table shows the exposed APIs as REST Collection.  
−
SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set
+
−
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
+
−
</pre>
+
  
−
== Facet Instances APIs ==
+
{| class="wikitable"
 +
! Operation || HTTP Method || URL
 +
|-
 +
| 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>
 +
|}
  
−
=== Create Facet Instance ===
+
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]].
  
−
==== REST API ====
+
==== Instances Collection Administrative capabilities ====
  
−
<pre>PUT /resource-registry/er/facet/{FacetType}</pre>
+
{| 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>
 +
|}
  
−
===== Example =====
+
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>
+
* hierarchical (default=false): enable [[#Hierarchical Mode]]
 +
* includeContextsInHeader (default=false): include [[#Contexts in Header]]
  
−
'''''Request 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":null,
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
</pre>
+
  
−
'''''Response Body'''''
+
===== Hierarchical Mode =====
−
<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:16:24
+
−
},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
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.
  
−
<pre>
+
'''This functionality is only available for the list and the read operations.'''
−
public <F extends Facet> F createFacet(F facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
This functionality enables an administrator to have a complete overview of the instances at any context tree level.
−
<pre>
+
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
  
−
CPUFacet createdCpuFacet = resourceRegistryPublisher.createFacet(cpuFacet);
+
Thanks to this functionality:
−
UUID uuid = createdCpuFacet.getHeader().getUUID(); // 69f0b376-38d2-4a85-bc63-37f9fa323f82
+
* 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;
−
</pre>
+
* the administrator is capable of observing the instance at any higher level in the context hierarchy;
 +
* any "normal" client read only the context instance.
  
−
==== Alternative JAVA API ====
+
===== Contexts in Header =====
  
−
There are also two other equivalent methods with the following signature:
+
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.
  
−
<pre>
+
The list of contexts is included in the header as an array of strings containing the UUID of contexts.
−
public String createFacet(String facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
  
−
public String createFacet(String facetType, String facet) throws FacetAlreadyPresentException, ResourceRegistryException;
+
===== Get Instance Contexts =====
−
</pre>
+
  
−
The first methods get the Facet to be created as JSON string instead of as Java class.
+
====== Get Instance Contexts via Java Client ======
−
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 ===
+
<source lang="java">
 +
public Set<UUID> getElementContexts(String type, UUID instanceUUID) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
  
−
==== REST API ====
+
public <ERElem extends ERElement> Set<UUID> getElementContexts(ERElem er) throws ResourceNotFoundException, ContextNotFoundException, ResourceRegistryException;
 +
</source>
  
−
<pre>POST /resource-registry/er/facet/{Facet Instance UUID}</pre>
+
====== Get Instance Contexts via REST API ======
  
−
===== Example =====
+
<pre>GET /instances/{TYPE_NAME}/{UUID}/contexts</pre>
  
−
<pre>POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82</pre>
+
{|class="wikitable"
 +
! Code
 +
! Type
 +
! Description
 +
|-
 +
| 200
 +
| String
 +
| A JSON Array containing the list of instances added to the context
 +
|}
  
−
'''''Request Body'''''
+
== Resource Registry Publisher ==
−
<pre>
+
−
{
+
−
"@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'''''
+
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]].
−
<pre>
+
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.
−
"@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 ====
+
To use the Java library to interact with Instances Collection declare the following dependency in your pom.xml file.
  
−
<pre>
+
<source lang="xml">
−
public <F extends Facet> F updateFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
<dependency>
−
</pre>
+
<groupId>org.gcube.information-system</groupId>
 +
<artifactId>resource-registry-publisher</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
−
===== Example =====
+
To use the client you just need to instantiate the client via the provided factory.
  
−
<pre>
+
<source lang="java">
−
createdCpuFacet.setClockSpeed("2 GHz");
+
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisher;
−
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(createdCpuFacet);
+
import org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisherFactory;
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
...
  
−
There are also two other equivalent methods with the following signature:
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
 +
</source>
  
−
<pre>
+
The provided client exposes the available methods and options as explained below.
−
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.
+
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]
−
The second get also the '''uuid''' as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string.  
+
−
The second method is more efficient but you have to be sure that the provided '''uuid''' is the same specified in the header of the serialized facet.
+
  
−
=== Delete Facet Instance ===
+
== APIs ==
  
−
==== REST API ====
+
=== List Instances ===
  
−
<pre>DELETE /resource-registry/er/facet/{Facet Instance UUID}</pre>
+
==== List via Java Client ====
  
−
===== Example =====
+
'''Signature'''
−
<pre>DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82</pre>
+
  
−
==== Java API ====
+
<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 <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
The following snippet of code shows how to retrieve all the resource instances.
  
−
<pre>
+
<source lang="java">
−
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
</pre>
+
List<Resource> allResources = resourceRegistryPublisher.list(Resource.class, true);
 +
</source>
  
−
==== Alternative JAVA API ====
+
===== List via Java Client Example 2 =====
  
−
There is also another equivalent methods with the following signature:
+
The following snippet of code shows how to retrieve all the EService instances (only the EService).
  
−
<pre>
+
<source lang="java">
−
public boolean deleteFacet(UUID uuid) throws FacetNotFoundException, ResourceRegistryException;
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
</pre>
+
List<EService> allResources = resourceRegistryPublisher.list(EService.class, false);
 +
</source>
  
−
The method just need the UUID of the Facet to be deleted.
+
==== List via REST API ====
  
−
== Resource Instances APIs ==
+
===== List via REST API Example 1 =====
  
−
=== Create Resource Instance ===
+
The following request shows how to retrieve all the resource instances.
  
−
==== REST API ====
+
'''Request URL'''
  
−
<pre>PUT /resource-registry/er/resource/{ResourceType}</pre>
+
<pre>GET /instances/Resource?polymorphic=true</pre>
  
−
===== Example =====
+
===== List via REST API Example 2 =====
  
−
<pre>
+
The following request shows how to retrieve all the EService instances (only the EService).
−
PUT /resource-registry/er/resource/HostingNode
+
−
</pre>
+
  
−
'''''Request Body'''''
+
'''Request URL'''
−
<pre>
+
−
{
+
−
"@class":"HostingNode",
+
−
"consistsOf":[
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"3 GHz"
+
−
}
+
−
},{
+
−
"@class":"IsIdentifiedBy",
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933"},
+
−
/* In this example we suppose that the NetworkingFacet was already created, so the UUID is enough to attach it by using IsIdentifiedBy relation */
+
−
}
+
−
}
+
−
],
+
−
"isRelatedTo":[
+
−
{
+
−
"@class":"Hosts",
+
−
"propagationConstraint":{
+
−
"add":"unpropagate",
+
−
"remove": "cascade"
+
−
},
+
−
"target":{
+
−
"@class":"EService",
+
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3"}
+
−
/* The EService was already created, so the UUID is enough to attach it by using Hosts relation */
+
−
}
+
−
}
+
−
]
+
−
}
+
  
−
</pre>
+
<pre>GET /instances/EService</pre>
  
−
'''''Response'''''
+
=== Create Instance ===
−
<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 ====
+
==== Create via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public <R extends Resource> R createResource(R resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem create(ERElem er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
  
−
<pre>
+
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
−
NetworkingFacet networkingFacet = new NetworkingFacetImpl();
+
</source>
−
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 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.
  
−
HostingNode hostingNode = new HostingNodeImpl();
 
  
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
===== Create via Java Client Example =====
−
cpuFacet.setClockSpeed("1 GHz");
+
<source lang="Java">
−
cpuFacet.setModel("Opteron");
+
EService eService = new EServiceImpl();
−
cpuFacet.setVendor("AMD");
+
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
−
hostingNode.addFacet(cpuFacet);
+
Header header = new HeaderImpl(uuid);
 +
eService.setHeader(header);
  
−
isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
SoftwareFacet softwareFacet = new SoftwareFacetImpl();
−
hostingNode.attachFacet(isIdentifiedBy);
+
softwareFacet.setGroup("WhnManager");
 +
softwareFacet.setName("VREManagement");
 +
softwareFacet.setVersion("2.0.0-4.15.0-132431");
 +
softwareFacet.setDescription("Web Hosting Node Service");
  
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
IsIdentifiedBy<Resource, Facet> isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(eService,
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
softwareFacet, null);
−
propagationConstraint.setAddConstraint(AddConstraint.unpropagate);
+
eService.addFacet(isIdentifiedBy);
  
−
Hosts<HostingNode, EService> hosts = new HostsImpl<HostingNode, EService>(hostingNode, eService, propagationConstraint);
+
AccessPointFacet accessPointFacet = new AccessPointFacetImpl();
−
hostingNode.attachResource(hosts);
+
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);
  
−
hostingNode = resourceRegistryPublisher.createResource(hostingNode);
+
AccessPointFacet accessPointFacet2 = new AccessPointFacetImpl();
−
</pre>
+
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);
  
  
−
==== Alternative JAVA API ====
+
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);
  
−
There are also two other equivalent methods with the following signature:
+
StateFacet stateFacet = new StateFacetImpl();
 +
stateFacet.setValue("started");
 +
eService.addFacet(stateFacet);
  
−
<pre>
 
−
public String createResource(String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
 
  
−
public String createResource(String resourceType, String resource) throws ResourceAlreadyPresentException, ResourceRegistryException;
+
eService = resourceRegistryPublisher.create(eService);
−
</pre>
+
  
−
The first methods get the Resource to be created as JSON string instead of as Java class.
+
</source>
−
The second get also the '''resourceType''' as parameter (which as to be specified as PATH PARAMETER in the request) avoiding to force client to retrieve it from the string.
+
−
The second method is more efficient but you have to be sure that the '''resourceType''' is the same specified in the header of the serialized resource.
+
  
−
=== Update Resource Instance ===
+
==== Create via REST API ====
  
−
==== REST API ====
+
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
  
−
<pre>POST /resource-registry/er/resource/{Resource Instance UUID}</pre>
+
===== Create via REST API Resource Example =====
  
−
=====  Example =====
+
The following listing shows an example of EService representation to be created.
−
<pre>POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84</pre>
+
  
−
'''''Request Body'''''
+
'''Request URL'''
−
<pre>
+
−
{
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
−
"consistsOf":[
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
},{
+
−
"@class":"IsIdentifiedBy",
+
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
−
"ipAddress" : "146.48.87.183",
+
−
"hostName": "pc-frosini.isti.cnr.it",
+
−
"domainName" : "isti.cnr.it",
+
−
"mask" : "255.255.248.0",
+
−
"broadcastAddress":"146.48.87.255",
+
−
"username":"luca.frosini" /* Added this property */
+
−
}
+
−
}
+
−
]
+
−
}
+
−
</pre>
+
  
−
'''''Response'''''
+
<pre>PUT PUT /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</pre>
−
<pre>
+
−
{
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
−
"consistsOf":[
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
},{
+
−
"@class":"IsIdentifiedBy",
+
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
−
"ipAddress" : "146.48.87.183",
+
−
"hostName": "pc-frosini.isti.cnr.it",
+
−
"domainName" : "isti.cnr.it",
+
−
"mask" : "255.255.248.0",
+
−
"broadcastAddress":"146.48.87.255",
+
−
"username":"luca.frosini"
+
−
}
+
−
}
+
−
]
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
Please note that '''EService''' and the UUID '''7f37a79d-0c00-4166-8a68-165de0a438bf''' are parts of the request URI
−
<pre>
+
−
public <R extends Resource> R updateResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
'''Request Body'''
  
−
<pre>
+
<source lang="JavaScript">
 +
{
 +
    "@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>
  
−
/* 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*/
+
The following listing contains the response of the service containing the representation of the created EService:
−
networkingFacet = (NetworkingFacet) hostingNode.getIdentificationFacets().get(0);
+
−
networkingFacet.setAdditionalProperty("username", "luca.frosini");
+
−
+
−
hostingNode = resourceRegistryPublisher.updateResource(hostingNode);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
'''Response Body'''
  
−
There are also two other equivalent methods with the following signature:
+
<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"
 +
    },
 +
    "@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"
 +
                ]
 +
            }
 +
        }
 +
    ]
 +
}
 +
</source>
  
−
<pre>
 
−
public String updateResource(String resource) throws ResourceNotFoundException, ResourceRegistryException;
 
−
public String updateResource(UUID uuid, String resource) throws ResourceNotFoundException, ResourceRegistryException;
 
−
</pre>
 
  
−
The first methods get the Resource to be created as JSON string instead of as Java class.
+
Reading the response we can observe the following properties:
−
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 ===
+
* '''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.
  
−
==== REST API ====
+
==== Schema Violation ====
  
−
<pre>DELETE /resource-registry/er/resource/{Resource Instance UUID}</pre>
+
As example, if you omit to include the EventFacet in the EService the service reply with a Schema Violation Exception.
  
−
=====  Example =====
+
<source lang="JavaScript">
 +
{
 +
    "@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": []
 +
}
 +
</source>
  
−
<pre>DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84</pre>
+
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.
  
−
==== Java API ====
+
This exception can also be raised in case of a client request to delete or remove from context a mandatory facet.
−
<pre>
+
−
public <R extends Resource> boolean deleteResource(R resource) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
=== Read Instance ===
  
−
<pre>
+
The following examples show how to request the service to include Contexts in the Header.
−
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
==== Read via Java Client ====
  
−
There is also another 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 boolean deleteResource(UUID uuid) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
public String read(String type, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 +
</source>
  
−
The method just need the UUID of the Resource to be deleted.
+
===== Read via Java Client Example =====
  
−
== ConsistsOf ==
+
<source lang="java">
 +
// This is the way to enable Hierarchical Mode
 +
// ResourceRegistryPublisherFactory.setHierarchicalMode(true);
  
−
=== Create ConsistsOf Instance ===
+
// This is the way to request the service to include the contexts in the header of the isntances
 +
ResourceRegistryPublisherFactory.includeContextsInInstanceHeader(true);
  
−
==== REST API ====
+
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
EService eService = resourceRegistryPublisher.read(EService.class, uuid);
 +
</source>
  
−
<pre>PUT /resource-registry/er/consistsOf/{ConsistOfType}</pre>
+
==== Read via REST API ====
  
−
===== Example 1 =====
+
<pre>GET /instances/{TYPE_NAME}/{UUID}</pre>
−
<pre>PUT /resource-registry/er/consistsOf/IsIdentifiedBy</pre>
+
  
−
In this example the target Facet already exists. The Service set automatically
+
===== Read via REST Example =====
−
the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
to default values (i.e. remove=cascadeWhenOrphan, add=propagate)
+
  
−
'''''Request Body'''''
+
In the example, the EService with UUID 7f37a79d-0c00-4166-8a68-165de0a438bf and all its facets belong only to the context with UUID ca50eb95-b76c-44fd-9182-229d39c3c9e2 (the UUID of /gcube).
−
<pre>
+
−
{
+
−
"@class":"IsIdentifiedBy",  
+
−
"source" : {
+
−
"@class":"HostingNode",
+
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"} // The HostingNode must be already created. The header with UUId is enough.
+
−
}
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933"},
+
−
/* In this example we suppose that the NetworkingFacet already exists, so the UUID is enough to attach it by using IsIdentifiedBy relation */
+
−
}
+
−
}
+
−
</pre>
+
  
−
'''''Response'''''
+
'''Request URL'''
−
<pre>
+
−
{
+
−
"@class":"IsIdentifiedBy",
+
−
"propagationConstraint":{
+
−
"add":"propagate",
+
−
"remove": "cascadeWhenOrphan"
+
−
},
+
−
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
−
"target":{
+
−
"@class":"NetworkingFacet",
+
−
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
−
"ipAddress" : "146.48.87.183",
+
−
"hostName": "pc-frosini.isti.cnr.it",
+
−
"domainName" : "isti.cnr.it",
+
−
"mask" : "255.255.248.0",
+
−
"broadcastAddress":"146.48.87.255"
+
−
}
+
−
}
+
−
</pre>
+
  
−
===== Example 2 =====
+
<pre>GET /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf?includeContextsInHeader=true</pre>
  
−
<pre>
+
'''Response Body'''
−
PUT /resource-registry/er/consistsOf/ConsistsOf
+
−
</pre>
+
  
−
In this example the target Facet is created contestually with ConsistsOf relation.
+
<source lang="JavaScript">
−
Moreover the [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
are explicitly set (i.e. remove=cascade, add=propagate).
+
−
 
+
−
'''''Request Body'''''
+
−
<pre>
+
 
{
 
{
−
"@class":"ConsistsOf",  
+
    "header": {
−
"propagationConstraint":{
+
        "@class": "Header",
−
"add":"propagate",
+
        "creationTime": "2021-07-01 08:51:02.353 +0200",
−
"remove": "cascade"
+
        "createdBy": "luca.frosini",
−
},
+
        "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
−
"source" : {
+
        "lastUpdateBy": "luca.frosini",
−
"@class":"HostingNode",
+
        "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
−
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"} // The HostingNode must be already created. The header with UUID is enough.
+
        "contexts": [
−
}
+
            "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
−
"target":{  
+
        ]
−
"@class":"CPUFacet",
+
    },
−
"model":"Opteron",
+
    "@class": "EService",
−
"vendor":"AMD",
+
    "@superClasses": [
−
"clockSpeed":"3 GHz"
+
        "Service",
−
}
+
        "GCubeResource",
 +
        "Resource"
 +
    ],
 +
    "consistsOf": [
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.312 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "3b653a72-b182-41d6-bcc5-97e0141f0ceb",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.312 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "IsIdentifiedBy",
 +
            "@superClasses": [
 +
                "ConsistsOf"
 +
            ],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "name": "WhnManager",
 +
                "description": "Web Hosting Node Service",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.298 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "97984812-90e6-4eb7-b804-50a9ad3fe4fb",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.298 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "optional": "false",
 +
                "version": "2.0.0-4.15.0-132431",
 +
                "group": "VREManagement",
 +
                "@class": "SoftwareFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.322 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "5c78bec3-2fa6-46b3-892d-d41bed93e136",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.322 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "type": null,
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/vremanagement/ws/whnmanager",
 +
                "entryName": "whnmanager",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.318 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "f66a9fdf-3d5c-45fd-8437-6fecec463c4c",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.318 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.332 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d4aec29c-3f18-4464-94ae-5fb77306eb82",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.332 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "authorization": {
 +
                    "@class": "ValueSchema",
 +
                    "type": null,
 +
                    "value": "gcube-token"
 +
                },
 +
                "endpoint": "http://pc-frosini.isti.cnr.it:8080/whn-manager/gcube/resource",
 +
                "entryName": "WhnManager-remote-management",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.327 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "a18eb180-398e-4302-942e-c3d7e55ad496",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.327 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "AccessPointFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.341 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "d5e73a7f-d85b-437b-ab2e-64c94061c5ff",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.341 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "value": "started",
 +
                "@class": "StateFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        },
 +
        {
 +
            "header": {
 +
                "@class": "Header",
 +
                "creationTime": "2021-07-01 08:51:02.350 +0200",
 +
                "createdBy": "luca.frosini",
 +
                "uuid": "f1a41f5c-42a3-47ec-b289-6811e62a1c94",
 +
                "lastUpdateBy": "luca.frosini",
 +
                "lastUpdateTime": "2021-07-01 08:51:02.350 +0200",
 +
                "contexts": [
 +
                    "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                ]
 +
            },
 +
            "propagationConstraint": {
 +
                "@class": "PropagationConstraint",
 +
                "add": "propagate",
 +
                "remove": "cascade"
 +
            },
 +
            "@class": "ConsistsOf",
 +
            "@superClasses": [],
 +
            "source": {
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "7f37a79d-0c00-4166-8a68-165de0a438bf",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.353 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "@class": "EService",
 +
                "@superClasses": [
 +
                    "Service",
 +
                    "GCubeResource",
 +
                    "Resource"
 +
                ]
 +
            },
 +
            "target": {
 +
                "date": "2021-06-30 16:38:26.464 +0200",
 +
                "header": {
 +
                    "@class": "Header",
 +
                    "creationTime": "2021-07-01 08:51:02.346 +0200",
 +
                    "createdBy": "luca.frosini",
 +
                    "uuid": "6142d408-f43c-4db7-851f-1dfeb4d98b99",
 +
                    "lastUpdateBy": "luca.frosini",
 +
                    "lastUpdateTime": "2021-07-01 08:51:02.346 +0200",
 +
                    "contexts": [
 +
                        "ca50eb95-b76c-44fd-9182-229d39c3c9e2"
 +
                    ]
 +
                },
 +
                "event": {
 +
                    "@class": "ValueSchema",
 +
                    "schema": "String",
 +
                    "value": "started"
 +
                },
 +
                "@class": "EventFacet",
 +
                "@superClasses": [
 +
                    "Facet"
 +
                ]
 +
            }
 +
        }
 +
    ]
 
}
 
}
−
</pre>
+
</source>
  
−
'''''Response'''''
+
=== Update Instance ===
−
<pre>
+
−
{
+
−
"@class":"ConsistsOf",
+
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...},
+
−
"propagationConstraint":{
+
−
"add":"propagate",
+
−
"remove": "cascade"
+
−
},
+
−
"target":{
+
−
"@class":"CPUFacet",
+
−
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"1 GHz"
+
−
}
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
==== Update via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> C createConsistsOf(C consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example 1 =====
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem update(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
  
−
<pre>
+
public String update(String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
IsIdentifiedBy isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
−
resourceRegistryPublisher.createConsistsOf(isIdentifiedBy);
+
public String update(String type, String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
</pre>
+
−
 
+
−
===== Example 2 =====
+
−
 
+
−
<pre>
+
−
CPUFacet cpuFacet = new CPUFacetImpl();
+
−
cpuFacet.setClockSpeed("1 GHz");
+
−
cpuFacet.setModel("Opteron");
+
−
cpuFacet.setVendor("AMD");
+
−
 
+
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.propagate);
+
−
 
+
−
ConsistsOf consistsOf = new ConsistsOfImpl<Resource, Facet>(hostingNode, cpuFacet, propagationConstraint);
+
−
consistsOf = resourceRegistryPublisher.createConsistsOf(consistsOf);
+
−
</pre>
+
−
 
+
−
==== Alternative JAVA API ====
+
−
 
+
−
There are also two other equivalent methods with the following signature:
+
−
 
+
−
<pre>
+
−
public String createConsistsOf(String consistsOfType, String cnsistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
 
 
−
public String createConsistsOf(String consistsOf) throws FacetNotFoundException, ResourceNotFoundException, ResourceRegistryException;
+
public String update(String type, String json, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
</pre>
+
</source>
  
−
The first methods get the '''consistsOfType''' to be created as JSON string instead of as Java class.
+
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.
−
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 ===
+
===== Update via Java Client Example =====
  
−
==== REST API ====
+
<source lang="java">
−
<pre>DELETE /resource-registry/er/consistsOf/{ConsistsOf Instance UUID}</pre>
+
UUID uuid = UUID.fromString("44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9");
 +
StateFacet stateFacet = resourceRegistryPublisher.read(StateFacet.class, uuid);
 +
stateFacet.setValue("ready");
 +
stateFacet = resourceRegistryPublisher.update(stateFacet);
 +
</source>
  
−
===== Example 1 =====
+
==== Update via REST API ====
−
<pre>DELETE /resource-registry/er/consistsOf/02a7072c-4f72-4568-945b-9ddccc881e9f</pre>
+
  
−
===== Example 2 =====
+
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
−
<pre>DELETE /resource-registry/er/consistsOf/9bff49c8-c0a7-45de-827c-accb71defbd3</pre>
+
  
−
==== Java API ====
+
===== Update via REST API Example =====
−
<pre>
+
−
public <C extends ConsistsOf<? extends Resource, ? extends Facet>> boolean deleteConsistsOf(C consistsOf) throws ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example 1 =====
+
'''Request URL'''
−
<pre>
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(isIdentifiedBy);
+
−
</pre>
+
  
−
===== Example 2 =====
+
<pre>PUT  /instances/CPUFacet/44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9</pre>
−
<pre>
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(consistsOf);
+
−
</pre>
+
  
−
==== Alternative JAVA API ====
+
'''Request Body'''
  
−
There is also another equivalent methods with the following signature:
+
<source lang="JavaScript">
 +
{
 +
  "header": {
 +
    "@class": "Header",
 +
    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
    "createdBy": "luca.frosini",
 +
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
    "lastUpdateBy": "luca.frosini",
 +
    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
 +
  },
 +
  "value": "ready",
 +
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 +
}
 +
</source>
  
−
<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">
−
 
+
−
===== Example 1 =====
+
−
<pre>
+
−
UUID uuid = UUID.fromString("02a7072c-4f72-4568-945b-9ddccc881e9f")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+
−
 
+
−
===== Example 2 =====
+
−
<pre>
+
−
UUID uuid = UUID.fromString("9bff49c8-c0a7-45de-827c-accb71defbd3")
+
−
boolean deleted = resourceRegistryPublisher.deleteConsistsOf(uuid);
+
−
</pre>
+
−
 
+
−
== IsRelatedTo ==
+
−
 
+
−
=== Create IsRelatedTo Instance ===
+
−
 
+
−
==== REST API ====
+
−
 
+
−
<pre>PUT /resource-registry/er/isRelatedTo/{IsRelatedTo Type}</pre>
+
−
 
+
−
===== Example =====
+
−
 
+
−
<pre>PUT /resource-registry/er/isRelatedTo/Hosts</pre>
+
−
 
+
−
In this example the target Resource already exists.
+
−
The [[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
are explicitly set. Please note that otherwise the service set the
+
−
[[Facet_Based_Resource_Model#PropagationConstraint Propagation Constraint]]
+
−
to default values (i.e. remove=keep, add=unpropagate)
+
−
 
+
−
'''''Request Body'''''
+
−
<pre>
+
 
{
 
{
−
"@class":"Hosts",
+
  "header": {
−
"propagationConstraint":{
+
    "@class": "Header",
−
"add":"unpropagate",
+
    "creationTime": "2021-07-01 08:51:02.336 +0200",
−
"remove": "cascade"
+
    "createdBy": "luca.frosini",
−
},
+
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
−
"target":{
+
    "lastUpdateBy": "luca.frosini",
−
"@class":"EService",
+
    "lastUpdateTime": "2021-07-01 08:51:08.536 +0200"
−
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3"}
+
  },
−
/* The EService was already created, so the UUID is enought to attach it by using Hosts relation */
+
  "value": "ready",
−
}
+
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 
}
 
}
−
</pre>
+
</source>
−
 
+
−
'''''Response'''''
+
−
<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 ====
+
−
 
+
−
<pre>
+
−
public <I extends IsRelatedTo<? extends Resource, ? extends Resource>> I createIsRelatedTo(I isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
−
 
+
−
===== Example =====
+
−
 
+
−
<pre>
+
−
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
−
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
−
propagationConstraint.setAddConstraint(AddConstraint.propagate);
+
−
 
+
−
Hosts<HostingNode, EService> hosts = new HostsImpl<>(hostingNode, eService, propagationConstraint);
+
−
hosts = resourceRegistryPublisher.createIsRelatedTo(hosts);
+
−
</pre>
+
−
 
+
−
==== Alternative Java API ====
+
−
There are also two other equivalent methods with the following signature:
+
−
 
+
−
<pre>
+
−
public String createIsRelatedTo(String isRelatedToType, String isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
−
 
+
−
public String createIsRelatedTo(String isRelatedTo) throws ResourceNotFoundException, ResourceRegistryException;
+
−
</pre>
+
−
 
+
−
The first methods get the '''isRelatedTo''' to be created as JSON string instead of as Java class.
+
−
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 ===
+
  
−
==== REST API ====
+
=== Delete Instance ===
  
−
<pre>DELETE /resource-registry/er/isRelatedTo/{IsRelatedTo Instance UUID}</pre>
+
==== Delete via Java Client ====
  
−
===== Example =====
+
<source lang="java">
 +
public <ERElem extends ERElement> boolean delete(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
  
−
<pre>DELETE /resource-registry/er/isRelatedTo/47494ad0-e606-4630-9def-4c607761ae14</pre>
+
public boolean delete(String type, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 +
</source>
  
−
==== 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"