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

From Gcube Wiki
Jump to: navigation, search
(→‎List via Java Client)
(→‎Read Instance)
 
(54 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
|}
 
|}
  
−
These sections provide information regarding how to interact with [[Resource_Registry Service | Resource Registry Service]] for Entities and Relations instances Management.
+
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.
 
REST and JAVA API are presented for each functionality.
  
Line 12: Line 12:
 
== Instances Management ==
 
== Instances Management ==
  
−
The Instances Management port type is responsible for the management of entities and relation instances. It offers the following APIs:
+
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;
+
* '''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;
+
* '''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;
+
* '''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;
+
* '''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;
+
* '''Update''': it allows to update an instance in a certain context;
−
* Delete: it allows to delete an instance.
+
* '''Delete''': it allows to delete an instance.
  
 
The Instances Management implements the following policies:
 
The Instances Management implements the following policies:
Line 31: Line 31:
 
== Instances Collection ==
 
== Instances Collection ==
  
−
The following table shows the exposed APIs as REST Collection  
+
The following table shows the exposed APIs as REST Collection.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 40: Line 40:
 
| Create || PUT || <code>/instances/{TYPE_NAME}/{UUID}</code>
 
| Create || PUT || <code>/instances/{TYPE_NAME}/{UUID}</code>
 
|-
 
|-
−
| Exists || GET || <code>/instances/{TYPE_NAME}/{UUID}</code>
+
| Exists || HEAD || <code>/instances/{TYPE_NAME}/{UUID}</code>
 
|-
 
|-
 
| Read || GET || <code>/instances/{TYPE_NAME}/{UUID}</code>
 
| Read || GET || <code>/instances/{TYPE_NAME}/{UUID}</code>
Line 54: Line 54:
 
==== Instances Collection Administrative capabilities ====
 
==== Instances Collection Administrative capabilities ====
  
−
Administrators are entitled to specify the following two query parameter in case of read operation:
+
{| 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>
 +
|}
 +
 
 +
Administrators are entitled to specify the following two query parameter in case of read and list operation:
  
 
* hierarchical (default=false): enable [[#Hierarchical Mode]]
 
* hierarchical (default=false): enable [[#Hierarchical Mode]]
 
* includeContextsInHeader (default=false): include [[#Contexts in Header]]
 
* includeContextsInHeader (default=false): include [[#Contexts in Header]]
 +
 +
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 =====
 
===== Hierarchical Mode =====
Line 63: Line 76:
 
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.
 
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 enables an administrator to have a complete overview of the instances at any level of the contexts tree.
+
'''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:
 
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;
+
* 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;
 
* the administrator is capable of observing the instance at any higher level in the context hierarchy;
−
* any "normal" client read only the context instance. It is not needed to implement a strategy to chose to correct instance because we don't need to add the instances at VO level just for administrator overview.
+
* any "normal" client read only the context instance.
  
 
===== Contexts in Header =====
 
===== Contexts in Header =====
Line 74: Line 89:
 
This functionality allows listing all the contexts an instance belongs to.
 
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.
 
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 a resource can be described by different facets in different contexts.
+
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 ======
 +
 
 +
<source lang="java">
 +
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;
 +
</source>
 +
 
 +
====== Get Instance Contexts via REST API ======
 +
 
 +
<pre>GET /instances/{TYPE_NAME}/{UUID}/contexts</pre>
 +
 
 +
{|class="wikitable"
 +
! Code
 +
! Type
 +
! Description
 +
|-
 +
| 200
 +
| String
 +
| A JSON Array containing the list of instances added to the context
 +
|}
  
 
== Resource Registry Publisher ==
 
== Resource Registry Publisher ==
Line 102: Line 143:
 
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
 
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
 
</source>
 
</source>
 +
 +
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 https://code-repo.d4science.org/gCubeSystem/resource-registry-publisher]
  
 
== APIs ==
 
== APIs ==
Line 109: Line 154:
 
==== List via Java Client ====
 
==== List via Java Client ====
  
−
Even the listing method is available in instances collection, this API has been made available only through the resource registry client.
+
'''Signature'''
  
−
<source lang="xml">
+
<source lang="java">
−
<dependency>
+
public <ERElem extends ERElement> List<ERElem> list(Class<ERElem> clazz, Boolean polymorphic) throws ResourceRegistryException;
−
<groupId>org.gcube.information-system</groupId>
+
−
<artifactId>resource-registry-client</artifactId>
+
public String list(String type, Boolean polymorphic) throws ResourceRegistryException;
−
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
+
−
<dependency>
+
 
</source>
 
</source>
  
 +
===== List via Java Client Example 1 =====
  
−
<source lang="java">
+
The following snippet of code shows how to retrieve all the resource instances.
−
import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClient;
+
−
import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClientFactory;
+
−
 
+
−
...
+
  
−
ResourceRegistryClient resourceRegistryClient = ResourceRegistryClientFactory.create();
+
<source lang="java">
 +
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
 +
List<Resource> allResources = resourceRegistryPublisher.list(Resource.class, true);
 
</source>
 
</source>
  
−
'''Signature''
+
===== List via Java Client Example 2 =====
 +
 
 +
The following snippet of code shows how to retrieve all the EService instances (only the EService).
  
 
<source lang="java">
 
<source lang="java">
−
public <IE extends IdentifiableElement, R extends Resource> List<R> getInstances(Class<IE> clazz, Boolean polymorphic) throws ResourceRegistryException;
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
−
+
List<EService> allResources = resourceRegistryPublisher.list(EService.class, false);
−
public String getInstances(String type, Boolean polymorphic) throws ResourceRegistryException;
+
 
</source>
 
</source>
  
 
==== List via REST API ====
 
==== List via REST API ====
 +
 +
===== List via REST API Example 1 =====
 +
 +
The following request shows how to retrieve all the resource instances.
 +
 +
'''Request URL'''
 +
 +
<pre>GET /instances/Resource?polymorphic=true</pre>
 +
 +
===== List via REST API Example 2 =====
 +
 +
The following request shows how to retrieve all the EService instances (only the EService).
 +
 +
'''Request URL'''
 +
 +
<pre>GET /instances/EService</pre>
  
 
=== Create Instance ===
 
=== Create Instance ===
Line 143: Line 202:
 
==== Create via Java Client ====
 
==== Create via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public <IE extends IdentifiableElement> IE create(IE er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
+
 
 +
<source lang="java">
 +
public <ERElem extends ERElement> ERElem create(ERElem er) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
  
 
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
 
public String create(String json) throws SchemaViolationException, AlreadyPresentException, ResourceRegistryException;
−
</pre>
+
</source>
  
 
The first method gets any instance of IdentifiableElement (i.e. Resources, Facets, ConsistsOf, IsRelatedTo)
 
The first method gets any instance of IdentifiableElement (i.e. Resources, Facets, ConsistsOf, IsRelatedTo)
Line 613: Line 674:
 
}
 
}
 
</source>
 
</source>
−
 
−
 
  
 
The error message contains information regarding:
 
The error message contains information regarding:
Line 620: Line 679:
 
* 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.
 
* 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.
  
−
=== Update Facet Instance ===
+
This exception can also be raised in case of a client request to delete or remove from context a mandatory facet.
  
−
==== REST API ====
+
=== Read Instance ===
  
−
<pre>POST /resource-registry/er/facet/{Facet Instance UUID}</pre>
+
The following examples show how to request the service to include Contexts in the Header.
  
−
===== Example =====
+
==== Read via Java Client ====
  
−
<pre>POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82</pre>
+
<source lang="java">
 +
public <ERElem extends ERElement> ERElem read(ERElem er) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
  
−
'''''Request Body'''''
+
public <ERElem extends ERElement> ERElem read(Class<ERElem> clazz, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
−
<pre>
+
 +
public String read(String type, UUID uuid) throws NotFoundException, AvailableInAnotherContextException, ResourceRegistryException;
 +
</source>
 +
 
 +
===== Read via Java Client Example =====
 +
 
 +
<source lang="java">
 +
// 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);
 +
</source>
 +
 
 +
==== Read via REST API ====
 +
 
 +
<pre>GET /instances/{TYPE_NAME}/{UUID}</pre>
 +
 
 +
===== 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'''
 +
 
 +
<pre>GET /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf?includeContextsInHeader=true</pre>
 +
 
 +
'''Response Body'''
 +
 
 +
<source lang="JavaScript">
 
{
 
{
−
"@class":"CPUFacet",
+
    "header": {
−
"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*/
+
        "@class": "Header",
−
"model":"Opteron",
+
        "creationTime": "2021-07-01 08:51:02.353 +0200",
−
"vendor":"AMD",
+
        "createdBy": "luca.frosini",
−
"clockSpeed":"2 GHz"
+
        "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"
 +
                ]
 +
            }
 +
        }
 +
    ]
 
}
 
}
−
</pre>
+
</source>
  
−
'''''Response Body'''''
+
=== Update Instance ===
−
<pre>
+
−
{
+
−
"@class":"CPUFacet",
+
−
"header": {
+
−
"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82",
+
−
"creator":"luca.frosini",
+
−
"lastUpdater":"luca.frosini",
+
−
"creationTime":"2016-10-05 11:16:24",
+
−
"lastUpdateTime":"2016-10-05 11:17:32"
+
−
},
+
−
"model":"Opteron",
+
−
"vendor":"AMD",
+
−
"clockSpeed":"2 GHz"
+
−
}
+
−
</pre>
+
  
−
==== Java API ====
+
==== Update via Java Client ====
  
−
<pre>
+
'''Signature'''
−
public <F extends Facet> F updateFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
−
</pre>
+
  
−
===== Example =====
+
<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;
−
createdCpuFacet.setClockSpeed("2 GHz");
+
−
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(createdCpuFacet);
+
public String update(String type, String json) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
</pre>
+
 +
public String update(String type, String json, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 +
</source>
  
−
==== Alternative JAVA API ====
+
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.
  
−
There are also two other equivalent methods with the following signature:
+
===== Update via Java Client Example =====
  
−
<pre>
+
<source lang="java">
−
public String updateFacet(String facet) throws FacetNotFoundException, ResourceRegistryException;
+
UUID uuid = UUID.fromString("44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9");
−
public String updateFacet(UUID uuid, String facet) throws FacetNotFoundException, ResourceRegistryException;
+
StateFacet stateFacet = resourceRegistryPublisher.read(StateFacet.class, uuid);
−
</pre>
+
stateFacet.setValue("ready");
 +
stateFacet = resourceRegistryPublisher.update(stateFacet);
 +
</source>
  
−
The first methods get the Facet to be created as JSON string instead of as Java class.
+
==== Update via REST API ====
−
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 ===
+
<pre>PUT  /instances/{TYPE_NAME}/{UUID}</pre>
  
−
==== REST API ====
+
===== Update via REST API Example =====
  
−
<pre>DELETE /resource-registry/er/facet/{Facet Instance UUID}</pre>
+
'''Request URL'''
  
−
===== Example =====
+
<pre>PUT  /instances/CPUFacet/44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9</pre>
−
<pre>DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82</pre>
+
  
−
==== Java API ====
+
'''Request Body'''
  
−
<pre>
+
<source lang="JavaScript">
−
public <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;
+
{
−
</pre>
+
  "header": {
 +
    "@class": "Header",
 +
    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
    "createdBy": "luca.frosini",
 +
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
    "lastUpdateBy": "luca.frosini",
 +
    "lastUpdateTime": "2021-07-01 08:51:02.336 +0200"
 +
  },
 +
  "value": "ready",
 +
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 +
}
 +
</source>
  
−
===== Example =====
+
'''Response Body'''
  
−
<pre>
+
<source lang="JavaScript">
−
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);
+
{
−
</pre>
+
  "header": {
 +
    "@class": "Header",
 +
    "creationTime": "2021-07-01 08:51:02.336 +0200",
 +
    "createdBy": "luca.frosini",
 +
    "uuid": "44abfa06-a78b-4e5a-a0c5-aa8fe7bcbcf9",
 +
    "lastUpdateBy": "luca.frosini",
 +
    "lastUpdateTime": "2021-07-01 08:51:08.536 +0200"
 +
  },
 +
  "value": "ready",
 +
  "@class": "StateFacet",
 +
  "@superClasses": [
 +
    "Facet"
 +
  ]
 +
}
 +
</source>
  
−
==== Alternative JAVA API ====
+
=== Delete Instance ===
  
−
There is also another equivalent methods with the following signature:
+
==== Delete via Java Client ====
  
−
<pre>
+
<source lang="java">
−
public boolean deleteFacet(UUID uuid) throws FacetNotFoundException, ResourceRegistryException;
+
public <ERElem extends ERElement> boolean delete(ERElem er) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
−
</pre>
+
 
 +
public boolean delete(String type, UUID uuid) throws SchemaViolationException, NotFoundException, ResourceRegistryException;
 +
</source>
 +
 
 +
===== Delete via Java Client Example =====
 +
 
 +
<source lang="java">
 +
UUID uuid = UUID.fromString("7f37a79d-0c00-4166-8a68-165de0a438bf");
 +
boolean deleted = resourceRegistryPublisher.delete(EService.NAME, uuid);
 +
</source>
 +
 
 +
==== Delete via REST API ====
 +
 
 +
<pre>DELETE  /instances/{TYPE_NAME}/{UUID}</pre>
 +
 
 +
===== Delete via REST Example =====
 +
 
 +
'''Request URL'''
  
−
The method just need the UUID of the Facet to be deleted.
+
<pre>DELETE /instances/EService/7f37a79d-0c00-4166-8a68-165de0a438bf</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"