Package org.gcube.informationsystem.resourceregistry.contexts

Interface ResourceRegistryContextClient

All Superinterfaces:

org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

All Known Implementing Classes:

ResourceRegistryContextClientImpl

public interface ResourceRegistryContextClient
extends org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

Client interface for managing contexts in the Resource Registry system.

The interface is the authoritative caller-facing contract. Stable invocation options are represented by immutable request options, while HTTP metadata is available through the opt-in response executor without changing ordinary domain-oriented return values. Standard Context representations always include previousPaths, including an empty list, immediately after path in their JSON form.

Author:

Luca Frosini (ISTI - CNR)

Field Summary

Fields inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

Method Summary

Modifier and Type	Method	Description
void	addHeader(String name, boolean value)	Deprecated. use per-request custom headers from ResourceRegistryRequestOptions
void	addHeader(String name, String value)	Deprecated. use per-request custom headers from ResourceRegistryRequestOptions
List<org.gcube.informationsystem.contexts.reference.entities.Context>	all()	Retrieves all live Contexts through the local cache.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	all(org.gcube.informationsystem.resourceregistry.api.rest.ContextLifecycle lifecycle)	Retrieves a page of Contexts from the server for the requested lifecycle slice, bypassing the local Context cache.
String	changeState(String context)	JSON-string counterpart of changeState(Context).
String	changeState(String uuid, String state)	String-based counterpart of changeState(UUID, ContextState).
org.gcube.informationsystem.contexts.reference.entities.Context	changeState(UUID uuid, org.gcube.informationsystem.contexts.reference.ContextState state)	Changes only the state of an existing context, identified by UUID, sending a minimal merge-patch body ({"state": ...}) that cannot affect name or parent.
org.gcube.informationsystem.contexts.reference.entities.Context	changeState(org.gcube.informationsystem.contexts.reference.entities.Context context)	Changes only the state of an existing Context, extracting its UUID and state from the supplied object.
String	create(String context)	Creates a Context from a JSON document supplied through the Java API as a String.
org.gcube.informationsystem.contexts.reference.entities.Context	create(org.gcube.informationsystem.contexts.reference.entities.Context context)	Creates a Context through PUT /contexts/{context-uuid}.
boolean	delete(String uuid)	Parses uuid and delegates to delete(UUID) without changing its logical-deletion, authorization, cache, retry, or response-metadata semantics.
boolean	delete(UUID uuid)	Logically deletes a live Context, removing it from the active topology while retaining its state and history in the cemetery.
boolean	delete(org.gcube.informationsystem.contexts.reference.entities.Context context)	Extracts the Context identifier and delegates to delete(UUID) without changing its logical-deletion, authorization, cache, or response-metadata semantics.
boolean	exist(String uuid)	Checks if a context with the specified UUID (as string) exists in the system.
boolean	exist(UUID uuid)	Checks if a context with the specified UUID exists in the system.
org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	getContextCache()	Gets the context cache used for context-related operations.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	query(String jsonQuery)	Executes a JSON Query-By-Example against live Contexts.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	query(String jsonQuery, org.gcube.informationsystem.resourceregistry.api.rest.ContextLifecycle lifecycle)	Executes a JSON Query-By-Example against Contexts, restricted to the given lifecycle slice.
String	read(String uuid)	Parses the UUID, delegates to read(UUID), and serializes the resulting Context hierarchy.
String	read(String uuid, int depth)	Parses the UUID, delegates to read(UUID, int), and serializes the resulting Context hierarchy.
org.gcube.informationsystem.contexts.reference.entities.Context	read(UUID uuid)	Retrieves a Context by UUID with root-only depth.
org.gcube.informationsystem.contexts.reference.entities.Context	read(UUID uuid, int depth)	Retrieves a Context by UUID and expands descendants to the requested depth.
org.gcube.informationsystem.contexts.reference.entities.Context	read(org.gcube.informationsystem.contexts.reference.entities.Context context)	Retrieves a Context by delegating its identifier to read(UUID).
org.gcube.informationsystem.contexts.reference.entities.Context	read(org.gcube.informationsystem.contexts.reference.entities.Context context, int depth)	Retrieves a Context by delegating its identifier and depth to read(UUID, int).
org.gcube.informationsystem.contexts.reference.entities.Context	readCurrentContext()	Retrieves the Context associated with the authorization token using root-only depth.
org.gcube.informationsystem.contexts.reference.entities.Context	readCurrentContext(int depth)	Retrieves the Context resolved by the server from the authorization token and expands descendants to the requested depth.
List<org.gcube.informationsystem.model.reference.properties.Event>	readHistory(String uuid)	Parses uuid and delegates to readHistory(UUID) without changing its history, authorization, or response-metadata semantics.
List<org.gcube.informationsystem.model.reference.properties.Event>	readHistory(UUID uuid)	Retrieves the complete audit trail of a Context in reverse-chronological order, with the newest Event first.
String	update(String context)	Full-Context JSON counterpart of update(Context).
String	update(UUID uuid, String mergePatchJson)	Applies an RFC 7396 merge patch to the Context identified by uuid.
org.gcube.informationsystem.contexts.reference.entities.Context	update(org.gcube.informationsystem.contexts.reference.entities.Context context)	Performs a Tracked Update of an existing context: state, name, and parent (as carried by the given object's getters) are sent to the server and applied atomically.

Methods inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

allMeta, getContextsPolicy, getLimit, getMembershipScope, getOffset, includeMeta, isHierarchicalMode, serverResponses, setAllMeta, setContextsPolicy, setHierarchicalMode, setIncludeMeta, setLimit, setMembershipScope, setOffset

Method Detail

addHeader

@Deprecated
void addHeader(String name,
               String value)

Deprecated.

use per-request custom headers from ResourceRegistryRequestOptions

Adds a custom HTTP header to be included in requests.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

name - Header name

value - Header value

addHeader

@Deprecated
void addHeader(String name,
               boolean value)

Deprecated.

use per-request custom headers from ResourceRegistryRequestOptions

Adds a custom HTTP header to be included in requests.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

name - Header name

value - boolean value

getContextCache

org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache getContextCache()

Gets the context cache used for context-related operations.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Returns:

The context cache instance

all

List<org.gcube.informationsystem.contexts.reference.entities.Context> all()
                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all live Contexts through the local cache.

Invocation-specific List options force a server-backed request so that pagination, metadata policy, lifecycle selection, and response metadata remain observable. Use all(ContextLifecycle) for an explicit lifecycle selection.

Returns:

all cached live Contexts, or the effective server page when request options are active

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if retrieval fails or the caller is not authorized

all

List<org.gcube.informationsystem.contexts.reference.entities.Context> all(org.gcube.informationsystem.resourceregistry.api.rest.ContextLifecycle lifecycle)
                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a page of Contexts from the server for the requested lifecycle slice, bypassing the local Context cache.

A null lifecycle omits the wire-level lifecycle query parameter and uses the server default (live). Values deleted and all require an IS-Manager or Infrastructure-Manager role and otherwise produce an authorization error. Pagination and metadata settings come from this client, while invocation-specific options supplied through RequestInfo.serverResponses() take precedence.

Parameters:

lifecycle - lifecycle slice to retrieve, or null for the server default

Returns:

Contexts in the requested lifecycle slice for the effective page

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if retrieval fails or the caller cannot request the lifecycle

query

List<org.gcube.informationsystem.contexts.reference.entities.Context> query(String jsonQuery)
                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
                                                                            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a JSON Query-By-Example against live Contexts. Equivalent to query(String, ContextLifecycle) with a null lifecycle (server default: live contexts only).

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

jsonQuery - the JSON Query-By-Example payload

Returns:

the matching Context objects

Throws:

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

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the query cannot be executed due to authorization issues or other errors

query

List<org.gcube.informationsystem.contexts.reference.entities.Context> query(String jsonQuery,
                                                                            org.gcube.informationsystem.resourceregistry.api.rest.ContextLifecycle lifecycle)
                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
                                                                            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a JSON Query-By-Example against Contexts, restricted to the given lifecycle slice.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

jsonQuery - the JSON Query-By-Example payload

lifecycle - the Context lifecycle slice to search (null for the server default, live); deleted and all are restricted to IS-Manager / Infrastructure-Manager

Returns:

the matching Context objects

Throws:

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

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the query cannot be executed due to authorization issues or other errors

create

org.gcube.informationsystem.contexts.reference.entities.Context create(org.gcube.informationsystem.contexts.reference.entities.Context context)
                                                                throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException,
                                                                       org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a Context through PUT /contexts/{context-uuid}. A UUID is generated and assigned to the supplied object when absent. Repeating a congruent representation is an idempotent success; an incongruent representation for an existing UUID is rejected.

The caller must use an administrative token for the immediate parent Context. Root creation requires an IS-Manager or Infrastructure-Manager token for the exact Root path. Request options, including metadataPolicy, and immutable response status, headers, and body are available through the invocation context and RequestInfo.serverResponses(). Supplied state and previousPaths values are ignored with a warning; historical paths are administered by update(UUID, String).

The token is resolved first: a token of a deleted Context is rejected; a parent that does not exist raises ContextNotFoundException; a parent in the cemetery is a conflict.

Parameters:

context - the Context to create

Returns:

the server representation of the created or congruent existing Context

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException - if the UUID exists with an incongruent representation

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the parent Context does not exist, live or in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization, transport, validation, or authorization fails

See Also:

create(String)

create

String create(String context)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException,
              org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a Context from a JSON document supplied through the Java API as a String. The document is decoded locally, assigned a UUID when absent, and sent as an object-valued JSON body through PUT /contexts/{context-uuid}.

Authorization, idempotency, request-option, and response-metadata behavior is identical to create(Context).

Parameters:

context - the object-valued JSON document represented as a Java string

Returns:

the server JSON representation of the created or congruent existing Context

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException - if the UUID exists with an incongruent representation

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the parent Context does not exist, live or in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if decoding, serialization, transport, validation, or authorization fails

See Also:

create(Context)

exist

boolean exist(UUID uuid)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Checks if a context with the specified UUID exists in the system.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

uuid - the UUID of the context to check for existence

Returns:

true if the context exists and is accessible to the current user, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors with the Resource Registry service

exist

boolean exist(String uuid)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Checks if a context with the specified UUID (as string) exists in the system.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

uuid - the UUID of the context (as string) to check for existence

Returns:

true if the context exists and is accessible to the current user, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors with the Resource Registry service

IllegalArgumentException - if the provided string is not a valid UUID format

read

org.gcube.informationsystem.contexts.reference.entities.Context read(org.gcube.informationsystem.contexts.reference.entities.Context context)
                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                     org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a Context by delegating its identifier to read(UUID).

Parameters:

context - the context object containing the UUID to retrieve

Returns:

the complete Context object with role-appropriate detail level

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

read

org.gcube.informationsystem.contexts.reference.entities.Context read(org.gcube.informationsystem.contexts.reference.entities.Context context,
                                                                     int depth)
                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                     org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a Context by delegating its identifier and depth to read(UUID, int).

Parameters:

context - the context object containing the UUID to retrieve

depth - ContextPath.DEPTH_ROOT_ONLY for the context alone, a positive integer for that many levels of descendants, or ContextPath.DEPTH_UNLIMITED for the full subtree

Returns:

the Context object, with children populated according to depth

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

read

org.gcube.informationsystem.contexts.reference.entities.Context read(UUID uuid)
                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                     org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a Context by UUID with root-only depth. This is equivalent to read(UUID, int) with ContextPath.DEPTH_ROOT_ONLY.

When no invocation options are active, a matching local cache entry may satisfy the call. An explicit metadata policy, depth, or custom request setting forces a server request so the option and response metadata remain observable through RequestInfo.serverResponses().

Parameters:

uuid - the UUID of the context to retrieve

Returns:

the Context object with role-appropriate detail level

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

read

org.gcube.informationsystem.contexts.reference.entities.Context read(UUID uuid,
                                                                     int depth)
                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                     org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a Context by UUID and expands descendants to the requested depth. The server's flat result is returned as one rooted Context hierarchy; child summaries beyond the requested depth remain summaries.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses(). The metadataPolicy and depth request options map to the corresponding query parameters and take precedence for that invocation.

Parameters:

uuid - the UUID of the context to retrieve

depth - ContextPath.DEPTH_ROOT_ONLY for the context alone, a positive integer for that many levels of descendants, or ContextPath.DEPTH_UNLIMITED for the full subtree

Returns:

the Context object, with children populated according to depth

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if communication, deserialization, or authorization fails; every role reads every live Context with any token; a Context in the cemetery is readable only by IS-Manager and Infrastructure-Manager

read

String read(String uuid)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Parses the UUID, delegates to read(UUID), and serializes the resulting Context hierarchy.

Parameters:

uuid - the UUID of the context (as string) to retrieve

Returns:

the Context as JSON string with role-appropriate detail level

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

IllegalArgumentException - if the provided string is not a valid UUID format

read

String read(String uuid,
            int depth)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Parses the UUID, delegates to read(UUID, int), and serializes the resulting Context hierarchy.

Parameters:

uuid - the UUID of the context (as string) to retrieve

depth - ContextPath.DEPTH_ROOT_ONLY for the context alone, a positive integer for that many levels of descendants, or ContextPath.DEPTH_UNLIMITED for the full subtree

Returns:

the Context as JSON string, with children populated according to depth

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

IllegalArgumentException - if the provided string is not a valid UUID format

readCurrentContext

org.gcube.informationsystem.contexts.reference.entities.Context readCurrentContext()
                                                                            throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                                   org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the Context associated with the authorization token using root-only depth. This is equivalent to readCurrentContext(int) with ContextPath.DEPTH_ROOT_ONLY.

Returns:

the Context object associated with the current authorization token

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the current context cannot be found or resolved

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there are communication errors or authorization issues

readCurrentContext

org.gcube.informationsystem.contexts.reference.entities.Context readCurrentContext(int depth)
                                                                            throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                                   org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the Context resolved by the server from the authorization token and expands descendants to the requested depth. This operation always uses the server so token-resolution outcomes and response metadata remain authoritative.

The depth and metadataPolicy request options map to the corresponding query parameters and take precedence for that invocation. Response warnings, links, and canonical content location are available through RequestInfo.serverResponses(). When the token path matches a retained previous path, the response metadata contains X-Result-Scope: previous-path and X-Resolved-Context-Path with the current path.

Parameters:

depth - ContextPath.DEPTH_ROOT_ONLY for the context alone, a positive integer for that many levels of descendants, or ContextPath.DEPTH_UNLIMITED for the full subtree

Returns:

the Context object, with children populated according to depth

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the token path matches no live Context (current or previous path) and no Context in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if communication, deserialization, or authorization fails; a token whose path matches only a deleted Context is rejected for every role, IS-Manager and Infrastructure-Manager included

update

org.gcube.informationsystem.contexts.reference.entities.Context update(org.gcube.informationsystem.contexts.reference.entities.Context context)
                                                                throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                       org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Performs a Tracked Update of an existing context: state, name, and parent (as carried by the given object's getters) are sent to the server and applied atomically. The object's previousPaths are deliberately omitted so a stale full representation cannot replace the server's retained set; use update(UUID, String) for an explicit replacement.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses(), including previous-path resolution headers when applicable.

A reparenting requires a token for the closest common ancestor of the current and the new parent. A Context in the cemetery cannot be updated (409).

Parameters:

context - a Context object (typically obtained via read()) carrying the UUID to update and the desired state/name/parent

Returns:

the updated Context object with complete information

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the update is rejected (e.g. rename/reparent while ACTIVE) or fails due to authorization issues or other errors

update

String update(UUID uuid,
              String mergePatchJson)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
              org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Applies an RFC 7396 merge patch to the Context identified by uuid. The Java API accepts the object-valued JSON document as a String; it is transmitted unchanged with Content-Type: application/merge-patch+json.

The patch may contain state, name, parent, and previousPaths. The latter is null or an array of absolute path strings and replaces the complete retained set. metadata, path, effectiveState, and children are dropped without warning; type and id, when present, must identify the addressed Context (400 otherwise); any other field is ignored with a warning. Invocation-specific options and immutable response metadata, including warnings, links, content location, and previous-path resolution headers, are available through RequestInfo.serverResponses().

Reasserting a previous path already retained by the same Context is a no-op; adding a path owned by another live Context, as its current path or one of its previous paths, is a conflict (409).

A reparenting requires a token for the closest common ancestor of the current and the new parent. A Context in the cemetery cannot be updated (409).

Parameters:

uuid - the UUID of the Context to update

mergePatchJson - the object-valued merge-patch document represented as a Java string

Returns:

the complete updated Context representation as JSON

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the Context or the requested new parent does not exist, live or in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if decoding, transport, validation, authorization, or update fails

update

String update(String context)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
              org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Full-Context JSON counterpart of update(Context). The Java string is decoded as a Context; only state, name, and parent are sent. Use update(UUID, String) to replace previousPaths or preserve another arbitrary partial merge-patch document unchanged.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

A reparenting requires a token for the closest common ancestor of the current and the new parent. A Context in the cemetery cannot be updated (409).

Parameters:

context - the JSON string representation of the context carrying the UUID and the desired state/name/parent

Returns:

the updated context as JSON string with complete information

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the update is rejected (e.g. rename/reparent while ACTIVE) or fails due to authorization issues, invalid JSON, or other errors

delete

boolean delete(org.gcube.informationsystem.contexts.reference.entities.Context context)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
               org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Extracts the Context identifier and delegates to delete(UUID) without changing its logical-deletion, authorization, cache, or response-metadata semantics.

Parameters:

context - the non-null Context whose non-null identifier selects the deletion target

Returns:

true when the server confirms logical deletion

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the UUID is unknown, neither live nor in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if deletion is rejected or fails

IllegalArgumentException - if context or its identifier is null

delete

boolean delete(UUID uuid)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
               org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Logically deletes a live Context, removing it from the active topology while retaining its state and history in the cemetery. A successful bodyless response returns true; this method never uses false to represent a server error.

The caller must hold an administrative role with a token for the target's immediate parent, or for the target itself when deleting a Root Context; only IS-Manager and Infrastructure-Manager delete a Root Context. Deletion is rejected while the Context has children or graph instances. The operation supports no query options; unsupported raw query parameters are ignored with X-Warning. The local cache is invalidated without issuing a follow-up request. Immutable status, warning, and request metadata are available through RequestInfo.serverResponses(); this includes the two previous-path resolution headers when parent scope was established through a retained path.

Deletion is idempotent: deleting a Context that is already in the cemetery is a successful no-op (204) for IS-Manager and Infrastructure-Manager, and is rejected (403) for other roles.

Parameters:

uuid - the non-null UUID of the Context to delete

Returns:

true when the server confirms logical deletion

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the UUID is unknown, neither live nor in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, a non-empty Context, transport, or another registry operation prevents deletion

IllegalArgumentException - if uuid is null

delete

boolean delete(String uuid)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
               org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Parses uuid and delegates to delete(UUID) without changing its logical-deletion, authorization, cache, retry, or response-metadata semantics.

Parameters:

uuid - the non-null textual UUID of the Context to delete

Returns:

true when the server confirms logical deletion

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the UUID is unknown, neither live nor in the cemetery

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if deletion is rejected or fails

IllegalArgumentException - if uuid is null or is not a valid UUID

readHistory

List<org.gcube.informationsystem.model.reference.properties.Event> readHistory(UUID uuid)
                                                                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                               org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the complete audit trail of a Context in reverse-chronological order, with the newest Event first. A Context without recorded events produces an empty list.

IS-Manager and Infrastructure-Manager read the history of any Context, live or deleted, with any token; IS-Admin reads the history of any live Context with any token; Context-Manager needs a token for the target Context or one of its ancestors. Event.who is returned in full to IS-Manager, Infrastructure-Manager and IS-Admin, and as "[REDACTED]" to Context-Manager. This operation has no query options; unsupported query parameters sent outside this typed API are ignored by the service with an X-Warning. Immutable response metadata, including that warning and the rel=up link, is available through RequestInfo.serverResponses(). The history includes independent additions, removals, cascades, and path-reuse collision events for previousPaths; previous-path token resolution is exposed through response headers only for Context-Manager calls.

Parameters:

uuid - the non-null UUID of the Context whose history to read

Returns:

the complete reverse-chronological history, possibly empty

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, transport, response decoding, or another registry operation fails

IllegalArgumentException - if uuid is null

readHistory

List<org.gcube.informationsystem.model.reference.properties.Event> readHistory(String uuid)
                                                                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                               org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Parses uuid and delegates to readHistory(UUID) without changing its history, authorization, or response-metadata semantics.

Parameters:

uuid - the non-null textual UUID of the Context whose history to read

Returns:

the complete reverse-chronological history, possibly empty

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, transport, response decoding, or another registry operation fails

IllegalArgumentException - if uuid is null or is not a valid UUID

changeState

org.gcube.informationsystem.contexts.reference.entities.Context changeState(org.gcube.informationsystem.contexts.reference.entities.Context context)
                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Changes only the state of an existing Context, extracting its UUID and state from the supplied object. The client sends a minimal merge patch, so the object's name and parent cannot be modified by this method.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

context - the context object containing the UUID and the new state to apply

Returns:

the complete Context object with the updated state and full metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the state cannot be changed due to authorization issues, invalid state, or other errors

changeState

String changeState(String context)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                   org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

JSON-string counterpart of changeState(Context). The Java string is decoded locally to obtain the UUID and state; the client sends only the resulting minimal state merge patch.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

context - the JSON string representation containing the context UUID and new state

Returns:

the complete updated context as JSON string with the new state and full metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the state cannot be changed due to authorization issues, invalid state, invalid JSON, or other errors

changeState

org.gcube.informationsystem.contexts.reference.entities.Context changeState(UUID uuid,
                                                                            org.gcube.informationsystem.contexts.reference.ContextState state)
                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                                                                            org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Changes only the state of an existing context, identified by UUID, sending a minimal merge-patch body ({"state": ...}) that cannot affect name or parent.

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

uuid - the UUID of the context whose state should be changed

state - the new state to apply to the context

Returns:

the complete Context object with the updated state and full metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the state cannot be changed due to authorization issues, invalid state, or other errors

changeState

String changeState(String uuid,
                   String state)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
                   org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

String-based counterpart of changeState(UUID, ContextState).

Invocation-specific options and immutable response metadata are available through RequestInfo.serverResponses().

Parameters:

uuid - the UUID of the context (as string) whose state should be changed

state - the new state (as string) to apply to the context

Returns:

the complete updated context as JSON string with the new state and full metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the state cannot be changed due to authorization issues, invalid state, or other errors

IllegalArgumentException - if the provided UUID string is not a valid UUID format or if the state string is not a valid ContextState value