Package org.gcube.informationsystem.resourceregistry.rest.core

Class InstancesManager

java.lang.Object

org.gcube.informationsystem.resourceregistry.rest.base.BaseRest

org.gcube.informationsystem.resourceregistry.rest.core.InstancesManager

@Path("instances")
public class InstancesManager
extends BaseRest

Author:

Luca Frosini (ISTI - CNR)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	GET_INSTANCE_CONTEXTS_METHOD	Name of the list-instance-contexts operation.
static final String	INSTANCE	Metric accounting type label.
static final String	INSTANCE_UUID_PATH_PARAMETER	Path parameter name for instance UUIDs.

Fields inherited from class org.gcube.informationsystem.resourceregistry.rest.base.BaseRest

logger, uriInfo

Constructor Summary

Constructors

Constructor	Description
InstancesManager()	Creates a new InstancesManager REST resource.

Method Summary

Modifier and Type	Method	Description
jakarta.ws.rs.core.Response	addToContext(String type, String instanceId, String newContextId)	Adds an existing instance to a target Context and returns the affected-instance envelope.
jakarta.ws.rs.core.Response	create(String type, String json)	Creates a new instance, non-idempotently.
jakarta.ws.rs.core.Response	delete(String type, String instanceId)	Removes an instance from the current Context and returns the affected-instance envelope.
String	getInstanceContexts(String type, String instanceId)	Returns the token-subtree-filtered Context membership map for an exact instance.
String	mergeUpdate(String type, String instanceId, String json)	Applies an RFC 7396 merge update and returns the read-shaped target instance.
jakarta.ws.rs.core.Response	query(String jsonQuery)	Executes a role-filtered, paginated JSON Query-By-Example over Instances.
String	read(String type, String instanceId)	Reads one visible instance using its exact concrete Type and UUID.
jakarta.ws.rs.core.Response	readAll(String type)	Returns a role-filtered, paginated list for a concrete or abstract instance Type.
jakarta.ws.rs.core.Response	updateOrCreate(String type, String instanceId, String json)	Creates or fully replaces the exact instance addressed by the path.

Methods inherited from class org.gcube.informationsystem.resourceregistry.rest.base.BaseRest

buildResponse, buildResponse, setAccountingMethod, setAccountingMethod

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

INSTANCE_UUID_PATH_PARAMETER

public static final String INSTANCE_UUID_PATH_PARAMETER

Path parameter name for instance UUIDs.

See Also:

• Constant Field Values

INSTANCE

public static final String INSTANCE

Metric accounting type label.

See Also:

• Constant Field Values

GET_INSTANCE_CONTEXTS_METHOD

public static final String GET_INSTANCE_CONTEXTS_METHOD

Name of the list-instance-contexts operation.

See Also:

• Constant Field Values

Constructor Details

InstancesManager

public InstancesManager()

Creates a new InstancesManager REST resource.

Method Details

readAll

@GET
@Path("/{type-name}")
@Produces("application/json")
public jakarta.ws.rs.core.Response readAll(@PathParam("type-name")
 String type)
                                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Returns a role-filtered, paginated list for a concrete or abstract instance Type.

Parameters:

type - the case-sensitive name of a Resource, Facet, IsRelatedTo, or ConsistsOf Type

Returns:

a JAX-RS response containing the JSON array of instances

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the type is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

query

@Consumes("application/json")
@Produces("application/json")
public jakarta.ws.rs.core.Response query(String jsonQuery)
                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a role-filtered, paginated JSON Query-By-Example over Instances.

Parameters:

jsonQuery - the JSON query specification

Returns:

a JAX-RS response containing the JSON array of matching instances

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query syntax or structure is invalid

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

read

@GET
@Path("/{type-name}/{instance-uuid}")
@Produces("application/json")
public String read(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads one visible instance using its exact concrete Type and UUID.

Parameters:

type - the exact concrete Information System Type of the instance

instanceId - the UUID of the instance to retrieve

Returns:

the JSON representation of the retrieved instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the type or instance is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

create

@POST
@Path("/{type-name}")
@Consumes("application/json")
@Produces("application/json")
public jakarta.ws.rs.core.Response create(@PathParam("type-name")
 String type,
 String json)
                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance, non-idempotently.

Parameters:

type - the exact concrete Entity or Relation type name of the instance to create

json - the complete JSON representation of the new instance

Returns:

a JAX-RS response with the created instance in the body

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

updateOrCreate

@PUT
@Path("/{type-name}/{instance-uuid}")
@Consumes("application/json")
@Produces("application/json")
public jakarta.ws.rs.core.Response updateOrCreate(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId,
 String json)
                                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates or fully replaces the exact instance addressed by the path.

Parameters:

type - the exact concrete Entity or Relation type name of the target instance

instanceId - the UUID of the instance to create or update

json - the complete JSON representation of the instance

Returns:

a JAX-RS response indicating success, with the updated/created instance in the body

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

mergeUpdate

@PATCH
@Path("/{type-name}/{instance-uuid}")
@Consumes("application/merge-patch+json")
@Produces("application/json")
public String mergeUpdate(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId,
 String json)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Applies an RFC 7396 merge update and returns the read-shaped target instance.

Parameters:

type - the exact concrete Entity or Relation type name of the target instance

instanceId - the UUID of the instance to update

json - the JSON merge patch payload

Returns:

the JSON representation of the merged instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

delete

@DELETE
@Path("/{type-name}/{instance-uuid}")
@Produces("application/json")
public jakarta.ws.rs.core.Response delete(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId)
                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an instance from the current Context and returns the affected-instance envelope.

Parameters:

type - the exact concrete Entity or Relation type name of the instance

instanceId - the UUID of the instance to remove

Returns:

a JAX-RS response containing the affected-instance envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

addToContext

@PUT
@Path("{type-name}/{instance-uuid}/contexts/{context-uuid}")
@Produces("application/json")
public jakarta.ws.rs.core.Response addToContext(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId,
 @PathParam("context-uuid")
 String newContextId)
                                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an existing instance to a target Context and returns the affected-instance envelope.

Parameters:

type - the exact concrete Entity or Relation type name of the target instance

instanceId - the UUID of the instance to add to the target Context

newContextId - the UUID of the target Context

Returns:

a JAX-RS response containing the affected-instance envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs

getInstanceContexts

@GET
@Path("{type-name}/{instance-uuid}/contexts")
@Produces("application/json")
public String getInstanceContexts(@PathParam("type-name")
 String type,
 @PathParam("instance-uuid")
 String instanceId)
                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Returns the token-subtree-filtered Context membership map for an exact instance.

Parameters:

type - the exact concrete Entity or Relation type name of the instance

instanceId - the UUID of the instance whose Context memberships are requested

Returns:

JSON object mapping Context UUIDs to current paths

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a registry database error occurs