Resource Registry Service - Instances Management

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

The Instances Management port type 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	GET	/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.

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();

Instances APIs

Create Facet Instance

REST API

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

Example

PUT /resource-registry/er/facet/CPUFacet

Request Body

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

Response Body

{ 
	"@class":"CPUFacet",
	"header": {
		"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2016-10-05 11:16:24",
		"lastUpdateTime":"2016-10-05 11:16:24
	},
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"1 GHz"
}

Java API

public <F extends Facet> F createFacet(F facet) throws FacetAlreadyPresentException, ResourceRegistryException;

Example

CPUFacet cpuFacet = new CPUFacetImpl();
cpuFacet.setClockSpeed("1 GHz");
cpuFacet.setModel("Opteron");
cpuFacet.setVendor("AMD");

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

Alternative JAVA API

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

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

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

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

Update Facet Instance

REST API

POST /resource-registry/er/facet/{Facet Instance UUID}

Example

POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Request Body

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

Response Body

{ 
	"@class":"CPUFacet",
	"header": {
		"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82",
		"creator":"luca.frosini", 
		"lastUpdater":"luca.frosini", 
		"creationTime":"2016-10-05 11:16:24",
		"lastUpdateTime":"2016-10-05 11:17:32"
	},
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"2 GHz"
}

Java API

public <F extends Facet> F updateFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;

Example

createdCpuFacet.setClockSpeed("2 GHz");
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(createdCpuFacet);

Alternative JAVA API

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

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

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

Delete Facet Instance

REST API

DELETE /resource-registry/er/facet/{Facet Instance UUID}

Example

DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Java API

public <F extends Facet> boolean deleteFacet(F facet) throws FacetNotFoundException, ResourceRegistryException;

Example

boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);

Alternative JAVA API

There is also another equivalent methods with the following signature:

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

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