Package org.gcube.informationsystem.resourceregistry.contexts

Class ResourceRegistryContextClientImpl

java.lang.Object

org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

org.gcube.informationsystem.resourceregistry.contexts.ResourceRegistryContextClientImpl

All Implemented Interfaces:

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

public class ResourceRegistryContextClientImpl
extends org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo
implements ResourceRegistryContextClient

Author:

Luca Frosini (ISTI - CNR)

Field Summary

Fields

Modifier and Type	Field	Description
protected final String	address	The base address of the Resource Registry service
protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	contextCache	Cache for context information to improve performance
protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal	contextCacheRenewal	Context cache renewal strategy for refreshing cached context information
protected Map<String,String>	headers	HTTP headers to be included in requests

Fields inherited from class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

allMeta, hierarchicalMode, includeContexts, includeMeta, limit, offset

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

DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

Constructor Summary

Constructors

Constructor	Description
ResourceRegistryContextClientImpl(String address)	This client does not use the shared context cache because it is used by managers to manipulate contexts.

Method Summary

Modifier and Type	Method	Description
void	addHeader(String name, boolean value)	Adds a custom HTTP header to be included in requests.
void	addHeader(String name, String value)	Adds a custom HTTP header to be included in requests.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	all()	Retrieves the list of all contexts in the system.
String	changeState(String context)	Changes the state of an existing context from its JSON representation.
String	changeState(String uuid, String state)	Changes the state of an existing context using its UUID (as string) and the desired state (as string).
org.gcube.informationsystem.contexts.reference.entities.Context	changeState(UUID uuid, org.gcube.informationsystem.contexts.reference.ContextState state)	Changes the state of an existing context using its UUID and the desired state.
org.gcube.informationsystem.contexts.reference.entities.Context	changeState(org.gcube.informationsystem.contexts.reference.entities.Context context)	Changes the state of an existing context by extracting its UUID from the provided context object.
String	create(String context)	Creates a new context in the system from its JSON representation.
org.gcube.informationsystem.contexts.reference.entities.Context	create(org.gcube.informationsystem.contexts.reference.entities.Context context)	Creates a new context in the system.
boolean	delete(String uuid)	Deletes an existing context permanently from the system using its UUID (as string).
boolean	delete(UUID uuid)	Deletes an existing context permanently from the system using its UUID.
boolean	delete(org.gcube.informationsystem.contexts.reference.entities.Context context)	Deletes an existing context permanently from the system by extracting its UUID.
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.
boolean	existFromServer(String uuid)	Checks if a context with the specified UUID exists on the server.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContextFromServer()	It reads all the contexts from server.
protected List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContextFromServer(boolean includeMeta, Integer offset, Integer limit)	Retrieves all contexts from the Resource Registry server with specified parameters.
org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	getContextCache()	Gets the context cache used for context-related operations.
protected org.gcube.common.gxhttp.request.GXHTTPStringRequest	getGXHTTPStringRequest()	Creates and configures a GXHTTPStringRequest with authentication headers.
protected String	internalChangeState(UUID uuid, String context)	Internal method to change the state of an existing context in the Resource Registry.
protected String	internalCreate(org.gcube.informationsystem.contexts.reference.entities.Context context)	Internal method to create a new context in the Resource Registry.
String	internalUpdate(org.gcube.informationsystem.contexts.reference.entities.Context context)	Internal method to update an existing context in the Resource Registry.
String	read(String uuid)	Retrieves a specific context by its UUID (as string) and returns it as JSON.
org.gcube.informationsystem.contexts.reference.entities.Context	read(UUID uuid)	Retrieves a specific context by its UUID.
org.gcube.informationsystem.contexts.reference.entities.Context	read(org.gcube.informationsystem.contexts.reference.entities.Context context)	Retrieves a context by extracting its UUID from the provided context object.
org.gcube.informationsystem.contexts.reference.entities.Context	readCurrentContext()	Retrieves the current context associated with the client's authorization token.
String	readFromServer(String uuid)	Reads a context from the server by its UUID.
String	update(String context)	Updates an existing context in the system from its JSON representation.
org.gcube.informationsystem.contexts.reference.entities.Context	update(org.gcube.informationsystem.contexts.reference.entities.Context context)	Updates an existing context in the system.

Methods inherited from class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

allMeta, getLimit, getOffset, includeContexts, includeMeta, isHierarchicalMode, setAllMeta, setHierarchicalMode, setIncludeContexts, setIncludeMeta, setLimit, setOffset

Methods inherited from class java.lang.Object

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

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

allMeta, getLimit, getOffset, includeContexts, includeMeta, isHierarchicalMode, setAllMeta, setHierarchicalMode, setIncludeContexts, setIncludeMeta, setLimit, setOffset

Field Details

address

protected final String address

The base address of the Resource Registry service

headers

protected Map<String,String> headers

HTTP headers to be included in requests

contextCache

protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache contextCache

Cache for context information to improve performance

contextCacheRenewal

protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal contextCacheRenewal

Context cache renewal strategy for refreshing cached context information

Constructor Details

ResourceRegistryContextClientImpl

public ResourceRegistryContextClientImpl(String address)

This client does not use the shared context cache because it is used by managers to manipulate contexts. The shared cache has only minimal context information available to any users.

Parameters:

address - The base address of the Resource Registry service

Method Details

addHeader

public void addHeader(String name,
 String value)

Adds a custom HTTP header to be included in requests.

Specified by:

addHeader in interface ResourceRegistryContextClient

Parameters:

name - Header name

value - Header value

addHeader

public void addHeader(String name,
 boolean value)

Adds a custom HTTP header to be included in requests.

Specified by:

addHeader in interface ResourceRegistryContextClient

Parameters:

name - Header name

value - boolean value

getGXHTTPStringRequest

protected org.gcube.common.gxhttp.request.GXHTTPStringRequest getGXHTTPStringRequest()

Creates and configures a GXHTTPStringRequest with authentication headers.

Returns:

A configured GXHTTPStringRequest instance ready for making HTTP requests

getAllContextFromServer

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

It reads all the contexts from server. The cache used for contexts is bypassed and not updated.

Returns:

All Contexts read from server

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the operation

getAllContextFromServer

protected List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContextFromServer(boolean includeMeta,
 Integer offset,
 Integer limit)
                                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all contexts from the Resource Registry server with specified parameters.

Parameters:

includeMeta - Whether to include metadata in the response

offset - The offset for pagination

limit - The limit for pagination

Returns:

List of all contexts from the server

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the operation

all

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

Retrieves the list of all contexts in the system. Corresponding REST API: GET /contexts[?limit={limit}&offset={offset}&includeMeta={true|false}] Operation Behavior:

• Returns all contexts that are accessible to the current user
• Results are filtered based on user authorization and context access permissions
• Supports pagination and metadata inclusion based on client configuration
• Returns strongly-typed Context objects with role-appropriate detail level.

HTTP Response Codes:

• 200 OK: Contexts successfully retrieved
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response context
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

limit (configurable via client configuration):

• Maximum number of contexts to return in a single response
• Default value: server configuration dependent
• Usage: client.setLimit(50)
• Example: Set to 50 to get at most 50 contexts per request
• Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
• Query parameter: ContextPath.LIMIT_QUERY_PARAMETER.

offset (configurable via client configuration):

• Number of contexts to skip from the beginning of the result set
• Default value: 0 (starts from the first context)
• Usage: client.setOffset(10)
• Example: Set to 10 to skip the first 10 contexts (useful for pagination)
• Query parameter: ContextPath.OFFSET_QUERY_PARAMETER.

Input Processing:

• No input parameters required for this method
• All contexts accessible to the current user are returned based on authorization level
• Context filtering is automatically applied based on user permissions.

Authorization Requirements:

• IS-Manager: Can retrieve all contexts in the system with complete metadata
• Infrastructure-Manager: Can retrieve all contexts in the system with complete metadata
• Context-Manager: Can retrieve contexts within their management scope
• Other Users: Can retrieve contexts they have explicit access to with filtered metadata.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Basic usage - get all contexts with default settings
 List<Context> contexts = client.all();
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 List<Context> contextsWithMeta = client.all();
 
 // With pagination
 client.setLimit(50);
 client.setOffset(10);
 List<Context> paginatedContexts = client.all();
 

Implementation Details: Cache-Based Approach:

• This implementation uses a local ContextCache instance for optimal performance
• The cache is automatically populated/refreshed via ContextCacheRenewal when needed
• Cache renewal calls getAllContextFromServer(true, 0, UNBOUNDED_LIMIT) to fetch all contexts
• No direct REST API call is made unless the cache needs refreshing

Cache Refresh Strategy:

• Cache refresh is triggered automatically when contextCache.getContexts() detects stale data
• The refresh operation fetches contexts from server with full metadata enabled
• Uses unlimited result set (no pagination) for complete context hierarchy
• Cache refresh failures are logged but don't prevent operation completion

Performance Characteristics:

• First call: Moderate (requires initial server fetch via getAllContextFromServer())
• Subsequent calls: Very fast (served from local cache)
• After cache expiry: Moderate (automatic refresh triggered)

REST API Mapping: When cache refresh is needed, internally calls: GET /contexts?includeMeta=true&offset=0&limit=-1 Authorization Handling:

• Uses current security context from SecretManagerProvider for server requests
• Authorization headers are automatically added to REST requests via getGXHTTPStringRequest()
• Filtered results based on user's role and permissions as per server-side authorization

Specified by:

all in interface ResourceRegistryContextClient

Returns:

list of Context objects with role-appropriate detail level accessible to the current user

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during context retrieval or if there are authorization issues

getContextCache

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

Gets the context cache used for context-related operations.

Specified by:

getContextCache in interface ResourceRegistryContextClient

Returns:

The context cache instance

internalCreate

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

Internal method to create a new context in the Resource Registry. Handles UUID generation if not present and marshals the context to JSON.

Parameters:

context - The context to create

Returns:

The JSON representation of the created context

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException - If a context with the same UUID already exists

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during creation

create

public 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 new context in the system. This method invokes the REST API endpoint PUT /contexts/{context-uuid} from the Resource Registry service. If the context object does not have a UUID, one will be automatically generated. Corresponding REST API: PUT /contexts/{context-uuid} Operation Behavior:

• If the context UUID is null, a new UUID will be automatically generated
• The operation will create a new context or update an existing one with the same UUID
• All context properties and relationships are established based on the provided context object
• Returns the created context object with complete information and assigned UUID.

HTTP Response Codes:

• 201 Created: Context successfully created
• 200 OK: Context successfully updated (if UUID already existed)
• 400 Bad Request: Invalid context data or validation failure
• 409 Conflict: Context with the same name already exists in the parent context
• 403 Forbidden: User lacks authorization to create contexts in the specified location
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• Context object is validated against system constraints
• All context properties and relationships are processed
• UUID assignment is handled automatically if not provided.

Authorization Requirements:

• IS-Manager: Can create any context without restrictions and automatically receive full context information including complete metadata
• Infrastructure-Manager: Can create any context without restrictions and automatically receive full context information including complete metadata
• Context-Manager: Can create contexts only if they are Context-Manager of the parent context (the parent context must be the current context retrieved from client's authorization token)
• Other Users: Cannot create contexts and will receive authorization errors if attempting this operation.

Operation Behavior:

• If the context UUID is null, a new UUID will be automatically generated
• The operation will create a new context or update an existing one with the same UUID
• All context properties and relationships are established based on the provided context object

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Create a new context object
 Context newContext = new ContextImpl();
 newContext.setName("MyNewContext");
 newContext.setParent(parentContext);
 
 // Basic usage - create context
 Context createdContext = client.create(newContext);
 
 // With metadata inclusion for non-admin users
 client.setIncludeMeta(true);
 Context contextWithMeta = client.create(newContext);
 

Implementation Details: UUID Generation:

• If the context object has no UUID (context.getID() == null), generates one via UUIDManager
• Generated UUID is automatically assigned to the context object before creation

REST API Implementation:

• Marshals the context object to JSON using ElementMapper
• Makes HTTP PUT request to: PUT /contexts/{uuid}
• Content-Type: application/json;charset=UTF-8
• Includes additional query parameters via includeAdditionalQueryParameters()

Authorization:

• Uses current security context from SecretManagerProvider
• Authorization headers automatically added via getGXHTTPStringRequest()

Cache Management:

• Forces cache refresh via forceCacheRefresh() after successful creation
• Ensures subsequent operations see the newly created context

Error Handling:

• Propagates ResourceRegistryException from server
• Wraps other exceptions in RuntimeException

Specified by:

create in interface ResourceRegistryContextClient

Parameters:

context - the Context object to create

Returns:

the created Context object with complete information and assigned UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException - if a context with the same UUID already exists and creation fails (HTTP 409)

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

See Also:

• for creating contexts from JSON representation

create

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

Creates a new context in the system from its JSON representation. This method invokes the REST API endpoint PUT /contexts/{context-uuid} from the Resource Registry service. If the context JSON does not contain a UUID, one will be automatically generated. Corresponding REST API: PUT /contexts/{context-uuid} Operation Behavior:

• The JSON is parsed to extract context information including UUID, name, parent, and other properties
• If the context UUID is null or missing, a new UUID will be automatically generated
• The operation will create a new context or update an existing one with the same UUID
• All context properties and relationships are established based on the provided JSON
• Returns the created context as JSON string with complete information and assigned UUID.

HTTP Response Codes:

• 201 Created: Context successfully created
• 200 OK: Context successfully updated (if UUID already existed)
• 400 Bad Request: Invalid context data, JSON format, or validation failure
• 409 Conflict: Context with the same name already exists in the parent context
• 403 Forbidden: User lacks authorization to create contexts in the specified location
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• JSON must be a valid Context representation
• JSON is parsed to extract context information including UUID, name, parent, and other properties
• All context properties are validated against system constraints.

Authorization Requirements:

• IS-Manager: Can create any context without restrictions and automatically receive full context information including complete metadata
• Infrastructure-Manager: Can create any context without restrictions and automatically receive full context information including complete metadata
• Context-Manager: Can create contexts only if they are Context-Manager of the parent context (the parent context must be the current context retrieved from client's authorization token)
• Other Users: Cannot create contexts and will receive authorization errors if attempting this operation.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Create context from JSON string
 String contextJson = "{\"@class\":\"Context\",\"name\":\"MyNewContext\",\"parent\":{\"id\":\"parent-uuid\"}}";
 
 // Basic usage - create context from JSON
 String createdContextJson = client.create(contextJson);
 
 // With metadata inclusion for non-admin users
 client.setIncludeMeta(true);
 String contextWithMeta = client.create(contextJson);
 

Implementation Details: JSON Processing:

• Unmarshals the JSON string to a Context object using ElementMapper
• Delegates to internalCreate(Context) for the actual creation logic
• Returns the raw JSON response from the server

UUID Handling:

• If the JSON contains no UUID, one is automatically generated (via internalCreate())
• UUID generation follows the same logic as create(Context)

REST API Implementation:

• Same REST implementation as create(Context): PUT /contexts/{uuid}
• JSON validation occurs during unmarshaling phase

Cache Management:

• Forces cache refresh after successful creation (same as create(Context))

Error Handling:

• Validates JSON format during unmarshaling
• Propagates ResourceRegistryException from server
• Wraps JSON processing and other exceptions in RuntimeException

Specified by:

create in interface ResourceRegistryContextClient

Parameters:

context - the JSON string representation of the context to create

Returns:

the created context as JSON string with complete information and assigned UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException - if a context with the same UUID already exists and creation fails

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

See Also:

• for creating contexts from Context objects

existFromServer

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

Checks if a context with the specified UUID exists on the server.

Parameters:

uuid - The UUID of the context to check

Returns:

true if the context exists, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the operation

exist

public 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. Corresponding REST API: Internally uses GET /contexts/{context-uuid} Operation Behavior:

• Converts the string UUID to a UUID object and delegates to exist(UUID)
• Returns true if the context exists and is accessible to the current user
• Returns false if the context does not exist or is not accessible
• Does not return the context data, only confirms existence.

HTTP Response Codes:

• 200 OK: Context exists and is accessible
• 404 Not Found: Context does not exist or is not accessible
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• String must be a valid UUID format
• Context accessibility is verified based on user authorization level
• Contexts that exist but are not accessible to the user will return false.

Authorization Requirements:

• IS-Manager: Can check existence of any context
• Infrastructure-Manager: Can check existence of any context
• Context-Manager: Can check contexts within their management scope
• Other Users: Can only check contexts they have access to read.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 String contextUuidString = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 
 // Check if context exists
 if (client.exist(contextUuidString)) {
     System.out.println("Context exists and is accessible");
     Context context = client.read(contextUuidString);
     // Process context...
 } else {
     System.out.println("Context does not exist or is not accessible");
 }
 
 // Alternative: UUID validation
 try {
     boolean exists = client.exist(contextUuidString);
     // Process result...
 } catch (IllegalArgumentException e) {
     System.err.println("Invalid UUID format: " + contextUuidString);
 }
 

Implementation Details: UUID Conversion:

• Converts the string UUID to UUID object using UUID.fromString()
• Delegates to exist(UUID) for the actual existence check

Error Handling:

• Will throw IllegalArgumentException if the string is not a valid UUID format
• Other exceptions are handled by the delegated exist(UUID) method

Specified by:

exist in interface ResourceRegistryContextClient

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

exist

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

Checks if a context with the specified UUID exists in the system. Corresponding REST API: Internally uses GET /contexts/{context-uuid} Operation Behavior:

• Verifies if a context with the given UUID exists in the system
• Returns true if the context exists and is accessible to the current user
• Returns false if the context does not exist or is not accessible
• Does not return the context data, only confirms existence.

HTTP Response Codes:

• 200 OK: Context exists and is accessible
• 404 Not Found: Context does not exist or is not accessible
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• UUID must be a valid UUID format
• Context accessibility is verified based on user authorization level
• Contexts that exist but are not accessible to the user will return false.

Authorization Requirements:

• IS-Manager: Can check existence of any context
• Infrastructure-Manager: Can check existence of any context
• Context-Manager: Can check contexts within their management scope
• Other Users: Can only check contexts they have access to read.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Check if context exists
 if (client.exist(contextUuid)) {
     System.out.println("Context exists and is accessible");
     Context context = client.read(contextUuid);
     // Process context...
 } else {
     System.out.println("Context does not exist or is not accessible");
 }
 

Implementation Details: Cache-First Strategy:

• Uses read(UUID) method to check existence
• Leverages the cache-first approach of the read operation for performance
• If context exists in cache, no server call is made (very fast)
• If not in cache, makes REST API call via readFromServer()

Existence Logic:

• Returns true if read(UUID) succeeds
• Returns false if read(UUID) throws ContextNotFoundException
• Propagates other ResourceRegistryException types

Performance Characteristics:

• Very Fast: When context is in cache (no server call)
• Moderate: When cache miss occurs (requires server round-trip via read)

Authorization Behavior:

• Returns false for contexts that exist but are not accessible to the current user
• This is because the underlying read() operation will fail with authorization errors
• Effectively combines existence and accessibility checking

Specified by:

exist in interface ResourceRegistryContextClient

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

read

public 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 extracting its UUID from the provided context object. This is a convenience method that delegates to read(UUID) using the context's ID. Corresponding REST API: GET /contexts/{context-uuid}[?includeMeta={true|false}] Operation Behavior:

• Extracts the UUID from the provided context object
• Delegates to read(UUID) for the actual retrieval operation
• Returns the full context object with all accessible properties
• Response detail level varies based on user authorization.

HTTP Response Codes:

• 200 OK: Context successfully retrieved
• 404 Not Found: Context with the specified UUID is not found
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response (for non-admin users)
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• Context object must contain a valid UUID
• Only the UUID is used from the provided context object, all other properties are ignored.

Authorization Requirements:

• IS-Manager: Can retrieve any context with complete metadata
• Infrastructure-Manager: Can retrieve any context with complete metadata
• Context-Manager: Can retrieve contexts within their management scope
• Other Users: Can retrieve contexts they have access to with filtered metadata.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 Context contextStub = new ContextImpl();
 contextStub.setID(UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0"));
 
 // Read the full context using the stub
 Context fullContext = client.read(contextStub);
 

Implementation Details: UUID Extraction:

• Extracts UUID from the context object via context.getID()
• Delegates to read(UUID) for the actual retrieval operation

Convenience Method:

• Provides a convenient way to refresh/reload a context object
• Useful when you have a context reference but want the latest server data

Specified by:

read in interface ResourceRegistryContextClient

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

public 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 specific context by its UUID. Corresponding REST API: GET /contexts/{context-uuid}[?includeMeta={true|false}] Operation Behavior:

• Retrieves the context with the specified UUID from the system
• Returns the complete context object with all accessible properties
• Response detail level varies based on user authorization
• Metadata inclusion is controlled by client configuration and user authorization.

HTTP Response Codes:

• 200 OK: Context successfully retrieved
• 404 Not Found: Context with the specified UUID is not found
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response (for non-admin users)
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• UUID must be a valid UUID format
• Context accessibility is verified based on user authorization level.

Authorization Requirements:

• IS-Manager: Can retrieve any context with complete metadata
• Infrastructure-Manager: Can retrieve any context with complete metadata
• Context-Manager: Can retrieve contexts within their management scope with full information when operating in their own context
• Other Users: Can retrieve contexts they have access to with filtered metadata.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Basic usage - read context
 Context context = client.read(contextUuid);
 System.out.println("Context name: " + context.getName());
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 Context contextWithMeta = client.read(contextUuid);
 

Implementation Details: Cache-First Strategy:

• First checks the local ContextCache via contextCache.getContextByUUID(uuid)
• If found in cache, returns immediately (very fast path)
• If not found in cache, calls readFromServer(uuid.toString()) to fetch from server

Server Fetch Process:

• Makes REST GET request: GET /contexts/{uuid} with query parameters
• Unmarshals the JSON response to Context object using ElementMapper
• Forces cache refresh via forceCacheRefresh() after successful fetch
• Attempts to get the refreshed context from cache for consistency

Cache Synchronization:

• After server fetch, tries to get the context from refreshed cache
• If cache refresh succeeds, uses the cached version for consistency
• If cache refresh fails, logs error but continues with server-fetched context
• This ensures cache consistency and handles potential cache refresh issues gracefully

REST API Implementation:

• Uses readFromServer() which calls: GET /contexts/{uuid}
• Includes additional query parameters via includeAdditionalQueryParameters()
• Authorization headers automatically added via getGXHTTPStringRequest()

Error Handling:

• IOException during JSON unmarshaling wrapped in RuntimeException
• Server-side errors propagated as ResourceRegistryException
• Cache refresh failures logged but don't affect operation success

Specified by:

read in interface ResourceRegistryContextClient

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

readCurrentContext

public 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 current context associated with the client's authorization token. This method extracts the context information from the security context and retrieves the full context object. Corresponding REST API: Equivalent to GET /contexts/CURRENT_CONTEXT but implemented client-side Operation Behavior:

• Extracts the context full name from the current authorization token via SecretManagerProvider
• Resolves the context full name to its UUID
• Delegates to read(UUID) for the actual context retrieval
• Returns the complete context object associated with the current authorization token.

HTTP Response Codes:

• 200 OK: Current context successfully retrieved
• 404 Not Found: Current context cannot be found or resolved
• 403 Forbidden: User lacks authorization to access their current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response (for non-admin users)
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• Context information is automatically extracted from the JWT token
• No explicit input parameters required.

Authorization Requirements:

• IS-Manager: Can retrieve current context with complete metadata
• Infrastructure-Manager: Can retrieve current context with complete metadata
• Context-Manager: Can retrieve their current context with full information
• Other Users: Can retrieve their current context (this is typically always granted).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Get current context
 Context currentContext = client.readCurrentContext();
 System.out.println("Current context: " + currentContext.getName());
 System.out.println("Current context UUID: " + currentContext.getID());
 
 // With metadata
 client.setIncludeMeta(true);
 Context currentContextWithMeta = client.readCurrentContext();
 
 // Use current context for relative operations
 if (currentContext.getParent() != null) {
     Context parentContext = client.read(currentContext.getParent().getID());
     System.out.println("Parent context: " + parentContext.getName());
 }
 

Implementation Details: Current Context Resolution:

• Gets current context full name from SecretManagerProvider security context
• Resolves the full name to UUID using contextCache.getUUIDByFullName()
• Delegates to read(UUID) for the actual context retrieval

Security Context Integration:

• Automatically extracts context from JWT token in the current thread
• No need to manually specify context UUID or name
• Works with the current authorization scope

Cache Dependency:

• Requires the context cache to have full name to UUID mapping
• If mapping is not available, may trigger cache refresh
• Uses the same cache-first strategy as read(UUID)

Specified by:

readCurrentContext in interface ResourceRegistryContextClient

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

read

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

Retrieves a specific context by its UUID (as string) and returns it as JSON. This method delegates to read(UUID) and marshals the result to JSON format. Corresponding REST API: GET /contexts/{context-uuid}[?includeMeta={true|false}] Operation Behavior:

• Converts the string UUID to a UUID object
• Delegates to read(UUID) for the actual retrieval operation
• Marshals the resulting Context object to JSON format
• Returns the complete context as JSON string with all accessible properties.

HTTP Response Codes:

• 200 OK: Context successfully retrieved
• 404 Not Found: Context with the specified UUID is not found
• 403 Forbidden: User lacks authorization to access context information
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response (for non-admin users)
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• String must be a valid UUID format
• Context accessibility is verified based on user authorization level.

Authorization Requirements:

• IS-Manager: Can retrieve any context with complete metadata
• Infrastructure-Manager: Can retrieve any context with complete metadata
• Context-Manager: Can retrieve contexts within their management scope
• Other Users: Can retrieve contexts they have access to with filtered metadata.

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 String contextUuidString = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 
 // Basic usage - read context as JSON
 String contextJson = client.read(contextUuidString);
 System.out.println("Context JSON: " + contextJson);
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 String contextWithMetaJson = client.read(contextUuidString);
 
 // Error handling for invalid UUID
 try {
     String result = client.read("invalid-uuid-format");
 } catch (IllegalArgumentException e) {
     System.err.println("Invalid UUID format");
 }
 

Implementation Details: UUID Conversion and Delegation:

• Converts string UUID to UUID object via UUID.fromString()
• Delegates to read(UUID) for the actual retrieval
• Marshals the resulting Context object to JSON using ElementMapper

JSON Marshaling:

• Uses ElementMapper for consistent JSON representation
• Same format as returned by server REST API
• Marshaling errors wrapped in RuntimeException

Error Handling:

• IllegalArgumentException for invalid UUID format (from UUID.fromString())
• ContextNotFoundException propagated from underlying read operation
• JsonProcessingException during marshaling wrapped in RuntimeException
• Other ResourceRegistryException types propagated unchanged

Specified by:

read in interface ResourceRegistryContextClient

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

readFromServer

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

Reads a context from the server by its UUID.

Parameters:

uuid - The UUID of the context to read

Returns:

The JSON representation of the context

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 an error occurs during the operation

internalUpdate

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

Internal method to update an existing context in the Resource Registry.

Parameters:

context - The context to update

Returns:

The JSON representation of the updated context

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 an error occurs during the update

update

public 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

Updates an existing context in the system. Corresponding REST API: PUT /contexts/{context-uuid} Operation Behavior:

• Updates the context with the specified UUID using the provided context object
• Name Change: Updates the context name while preserving all other properties
• Parent Change (Move Operation): Moves the context to a different parent in the context hierarchy
• Combined Changes: Both name and parent can be changed in the same update request
• Context UUIDs remain stable regardless of name or parent changes.

HTTP Response Codes:

• 200 OK: Context successfully updated
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid context data or validation failure
• 403 Forbidden: User lacks authorization to update the context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• Context object must contain a valid UUID
• All context properties are validated against system constraints
• Name and parent changes are validated for conflicts and authorization.

Authorization Requirements:

• IS-Manager: Can update any context without restrictions
• Infrastructure-Manager: Can update any context without restrictions
• Context-Manager: Can update contexts only if they are Context-Manager of the parent context
• Other Users: Cannot update contexts (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Get context to update
 Context context = client.read(contextUuid);
 
 // Update context name
 context.setName("NewContextName");
 Context updatedContext = client.update(context);
 
 // Update with metadata for non-admin users
 client.setIncludeMeta(true);
 Context contextWithMeta = client.update(context);
 

Implementation Details: Context Validation:

• Requires a valid UUID in the context object (cannot be null)
• Marshals the context object to JSON using ElementMapper
• Delegates to internalUpdate(Context) for the actual update operation

REST API Implementation:

• Makes HTTP PUT request to: PUT /contexts/{uuid}
• Content-Type: application/json;charset=UTF-8
• Includes additional query parameters via includeAdditionalQueryParameters()
• Uses the context's UUID for the URL path

Authorization:

• Uses current security context from SecretManagerProvider
• Authorization headers automatically added via getGXHTTPStringRequest()

Cache Management:

• Forces cache refresh via forceCacheRefresh() after successful update
• Ensures subsequent operations see the updated context
• Cache refresh failures are logged but don't prevent operation completion

Response Processing:

• Unmarshals the JSON response back to a Context object
• Returns the updated context with any server-side modifications

Error Handling:

• Propagates ResourceRegistryException from server
• Wraps JSON processing and other exceptions in RuntimeException

Specified by:

update in interface ResourceRegistryContextClient

Parameters:

context - the Context object with updated properties

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 context cannot be updated due to authorization issues or other errors

update

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

Updates an existing context in the system from its JSON representation. Corresponding REST API: PUT /contexts/{context-uuid} Operation Behavior:

• Updates the context using the provided JSON representation
• Name Change: Updates the context name while preserving all other properties
• Parent Change (Move Operation): Moves the context to a different parent in the context hierarchy
• Combined Changes: Both name and parent can be changed in the same update request
• Returns the updated context as JSON string with complete information.

HTTP Response Codes:

• 200 OK: Context successfully updated
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid context data, JSON format, or validation failure
• 403 Forbidden: User lacks authorization to update the context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response
• Default value: false (basic context information only)
• Usage: client.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: ContextPath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

Input Processing:

• JSON must be a valid Context representation
• JSON must contain a valid UUID field to identify the target context
• All context properties are validated against system constraints
• Name and parent changes are validated for conflicts and authorization.

Authorization Requirements:

• IS-Manager: Can update any context without restrictions
• Infrastructure-Manager: Can update any context without restrictions
• Context-Manager: Can update contexts only if they are Context-Manager of the parent context
• Other Users: Cannot update contexts (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Update context from JSON string
 String contextJson = "{\"@class\":\"Context\",\"id\":\"uuid\",\"name\":\"UpdatedName\"}";
 
 // Basic usage - update context from JSON
 String updatedContextJson = client.update(contextJson);
 
 // With metadata inclusion for non-admin users
 client.setIncludeMeta(true);
 String contextWithMeta = client.update(contextJson);
 

Implementation Details: JSON Processing:

• Unmarshals the JSON string to a Context object using ElementMapper
• Delegates to internalUpdate(Context) for the actual update logic
• Returns the raw JSON response from the server

UUID Extraction:

• Extracts UUID from the JSON representation
• UUID must be present in the JSON (cannot update without specifying which context)
• JSON validation occurs during unmarshaling phase

REST API Implementation:

• Same REST implementation as update(Context): PUT /contexts/{uuid}
• UUID extracted from JSON is used for the URL path

Cache Management:

• Forces cache refresh after successful update (same as update(Context))

Error Handling:

• Validates JSON format during unmarshaling
• Propagates ResourceRegistryException from server
• Wraps JSON processing and other exceptions in RuntimeException
• Missing or invalid UUID in JSON will cause unmarshaling to fail

Specified by:

update in interface ResourceRegistryContextClient

Parameters:

context - the JSON string representation of the context with updated properties

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 context cannot be updated due to authorization issues, invalid JSON, or other errors

delete

public 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

Deletes an existing context permanently from the system by extracting its UUID. This is a convenience method that delegates to delete(UUID) using the context's ID. Corresponding REST API: DELETE /contexts/{context-uuid} Operation Behavior:

• Extracts the UUID from the provided context object
• Delegates to delete(UUID) for the actual deletion operation
• Context is permanently deleted from the system and moved to a "cemetery" for audit trails and historical tracking
• The UUID becomes permanently unavailable for reuse
• Once deleted, the context cannot be restored through normal operations.

HTTP Response Codes:

• 200 OK: Context successfully deleted
• 404 Not Found: Context with the specified UUID is not found
• 409 Conflict: Context has child contexts or other dependencies preventing deletion
• 403 Forbidden: User lacks authorization to delete the context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• Context object must contain a valid UUID
• Only the UUID is used from the provided context object, all other properties are ignored
• Child Contexts: Cannot delete a context that has child contexts (all child contexts must be deleted first or moved to a different parent)
• Instance Impact: Instances belonging to the deleted context will no longer belong to any context (if instances exist only in the deleted context, they will be permanently deleted from the system).

Authorization Requirements:

• IS-Manager: Can delete any context without restrictions
• Infrastructure-Manager: Can delete any context without restrictions
• Context-Manager: Can delete contexts only if they are Context-Manager of the parent context
• Other Users: Cannot delete contexts (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 Context contextToDelete = client.read(contextUuid);
 
 // Delete the context using the context object
 boolean deleted = client.delete(contextToDelete);
 if (deleted) {
     System.out.println("Context successfully deleted");
 }
 

Implementation Details: UUID Extraction:

• Extracts UUID from the context object via context.getID()
• Delegates to delete(UUID) for the actual deletion operation

Convenience Method:

• Provides a convenient way to delete a context when you have the context object
• Useful when deleting contexts obtained from other operations like read() or all()

Specified by:

delete in interface ResourceRegistryContextClient

Parameters:

context - the context object to delete

Returns:

true if the context was successfully deleted, false otherwise

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 context cannot be deleted due to authorization issues, child contexts, or other errors

delete

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

Deletes an existing context permanently from the system using its UUID. Corresponding REST API: DELETE /contexts/{context-uuid} Operation Behavior:

• Permanently deletes the context with the specified UUID from the system
• Context is moved to a "cemetery" for audit trails and historical tracking
• The UUID becomes permanently unavailable for reuse
• Once deleted, the context cannot be restored through normal operations.

HTTP Response Codes:

• 200 OK: Context successfully deleted
• 404 Not Found: Context with the specified UUID is not found
• 409 Conflict: Context has child contexts or other dependencies preventing deletion
• 403 Forbidden: User lacks authorization to delete the context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• UUID must be a valid UUID format
• Context must exist and be accessible to the user
• Child Contexts: Cannot delete a context that has child contexts (all child contexts must be deleted first or moved to a different parent)
• Instance Impact: Instances belonging to the deleted context will no longer belong to any context (if instances exist only in the deleted context, they will be permanently deleted from the system).

Authorization Requirements:

• IS-Manager: Can delete any context without restrictions
• Infrastructure-Manager: Can delete any context without restrictions
• Context-Manager: Can delete contexts only if they are Context-Manager of the parent context
• Other Users: Cannot delete contexts (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Delete the context using UUID
 boolean deleted = client.delete(contextUuid);
 if (deleted) {
     System.out.println("Context successfully deleted");
 }
 

Implementation Details: UUID Conversion:

• Converts the UUID object to string via uuid.toString()
• Delegates to delete(String) for the actual deletion operation

Type Safety:

• Provides type-safe UUID handling
• Eliminates the possibility of invalid UUID format errors

Specified by:

delete in interface ResourceRegistryContextClient

Parameters:

uuid - the UUID of the context to delete

Returns:

true if the context was successfully deleted, false otherwise

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 context cannot be deleted due to authorization issues, child contexts, or other errors

delete

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

Deletes an existing context permanently from the system using its UUID (as string). Corresponding REST API: DELETE /contexts/{context-uuid} Operation Behavior:

• Converts the string UUID to a UUID object and delegates to delete(UUID)
• Permanently deletes the context with the specified UUID from the system
• Context is moved to a "cemetery" for audit trails and historical tracking
• The UUID becomes permanently unavailable for reuse.

HTTP Response Codes:

• 200 OK: Context successfully deleted
• 404 Not Found: Context with the specified UUID is not found
• 409 Conflict: Context has child contexts or other dependencies preventing deletion
• 403 Forbidden: User lacks authorization to delete the context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• String must be a valid UUID format
• Context must exist and be accessible to the user
• Child Contexts: Cannot delete a context that has child contexts (all child contexts must be deleted first or moved to a different parent)
• Instance Impact: Instances belonging to the deleted context will no longer belong to any context (if instances exist only in the deleted context, they will be permanently deleted from the system).

Authorization Requirements:

• IS-Manager: Can delete any context without restrictions
• Infrastructure-Manager: Can delete any context without restrictions
• Context-Manager: Can delete contexts only if they are Context-Manager of the parent context
• Other Users: Cannot delete contexts (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 String contextUuidString = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 
 // Delete the context using string UUID
 try {
     boolean deleted = client.delete(contextUuidString);
     if (deleted) {
         System.out.println("Context successfully deleted");
     }
 } catch (IllegalArgumentException e) {
     System.err.println("Invalid UUID format: " + contextUuidString);
 }
 

Implementation Details: REST API Implementation:

• Makes HTTP DELETE request to: DELETE /contexts/{uuid}
• Accept header set to: application/json;charset=UTF-8
• No request body is sent (DELETE operation)
• Uses the UUID string directly in the URL path

Authorization:

• Uses current security context from SecretManagerProvider
• Authorization headers automatically added via getGXHTTPStringRequest()

Response Processing:

• Server response is processed via HTTPUtility.getResponse()
• Currently always returns true if no exception is thrown
• Server-side validation ensures deletion constraints are respected

Cache Management:

• Forces cache refresh via forceCacheRefresh() after deletion attempt (in finally block)
• Cache refresh is attempted even if deletion fails to ensure consistency
• Cache refresh failures are silently ignored to not interfere with deletion result

Error Handling:

• ResourceRegistryException propagated from server (e.g., authorization errors, child context constraints)
• Other exceptions wrapped in RuntimeException
• Cache refresh errors are caught and ignored

Logging:

• Trace-level logging for deletion initiation
• Info-level logging for deletion completion with success/failure status

Specified by:

delete in interface ResourceRegistryContextClient

Parameters:

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

Returns:

true if the context was successfully deleted, false otherwise

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 context cannot be deleted due to authorization issues, child contexts, or other errors

internalChangeState

protected String internalChangeState(UUID uuid,
 String context)
                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Internal method to change the state of an existing context in the Resource Registry.

Parameters:

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

context - the new context state as a JSON string

Returns:

the updated context as a JSON string

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the specified context UUID does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the state change operation

changeState

public 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 the state of an existing context by extracting its UUID from the provided context object. This is a convenience method that delegates to the internal change state operation using the context's ID. Corresponding REST API: PATCH /contexts/{context-uuid} Operation Behavior:

• State-Only Operation: Only the state property from the context object is evaluated and applied
• Property Isolation: All other properties in the context object are ignored during state change
• Complete Response: Returns the complete updated context with the new state and all other properties
• Extracts the UUID from the provided context object for identification.

HTTP Response Codes:

• 200 OK: Context state successfully changed
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid state value or validation failure
• 403 Forbidden: User lacks authorization to change the context state
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• Context object must contain a valid UUID for identification
• Context object must contain a valid state value
• State values must be valid according to the ContextState class
• All other properties in the context object are ignored and will not be modified.

Authorization Requirements:

• IS-Manager: Can change state of any context without restrictions
• Infrastructure-Manager: Can change state of any context without restrictions
• Context-Manager: Can change state of contexts only if they are Context-Manager of the parent context
• Other Users: Cannot change context states (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // Get context and change its state
 Context context = client.read(contextUuid);
 context.setState(ContextState.ACTIVE); // Set new state
 
 // Change the context state
 Context updatedContext = client.changeState(context);
 System.out.println("New state: " + updatedContext.getState());
 
 // All other properties are preserved
 System.out.println("Context name unchanged: " + updatedContext.getName());
 

Implementation Details: UUID Extraction:

• Extracts UUID from the context object via context.getID()
• Delegates to internal change state operation for the actual REST API call

JSON Marshalling:

• Marshals the context object to JSON using ElementMapper.marshal()
• Only the state property from the JSON is processed by the server
• Response JSON is unmarshalled back to a Context object

Cache Management:

• Forces cache refresh via forceCacheRefresh() after state change (in finally block)
• Cache refresh is attempted even if state change fails to ensure consistency
• Cache refresh failures are silently ignored to not interfere with state change result

Convenience Method:

• Provides object-oriented approach to state changes
• Useful when working with Context objects rather than raw JSON

Specified by:

changeState in interface ResourceRegistryContextClient

Parameters:

context - the context object containing the UUID and 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

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

Changes the state of an existing context from its JSON representation. Corresponding REST API: PATCH /contexts/{context-uuid} Operation Behavior:

• State-Only Operation: Only the state property from the JSON is evaluated and applied
• Property Isolation: All other properties in the JSON are ignored during state change
• Complete Response: Returns the complete updated context as JSON with the new state and all other properties
• Parses the JSON to extract UUID and state information.

HTTP Response Codes:

• 200 OK: Context state successfully changed
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid JSON format, state value, or validation failure
• 403 Forbidden: User lacks authorization to change the context state
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• JSON must contain a valid Context representation
• JSON must include a valid UUID field to identify the target context
• JSON must include a valid state field with the new state value
• State values must be valid according to the ContextState class
• All other JSON properties are ignored and will not be modified.

Authorization Requirements:

• IS-Manager: Can change state of any context without restrictions
• Infrastructure-Manager: Can change state of any context without restrictions
• Context-Manager: Can change state of contexts only if they are Context-Manager of the parent context
• Other Users: Cannot change context states (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 // JSON with UUID and new state (other properties ignored)
 String contextJson = """
     {
         "@class": "Context",
         "id": "c0f314e7-2807-4241-a792-2a6c79ed4fd0",
         "state": "ACTIVE",
         "name": "This will be ignored"
     }
     """;
 
 // Change the context state from JSON
 String updatedContextJson = client.changeState(contextJson);
 
 // Parse response to verify state change
 Context updatedContext = ElementMapper.unmarshal(Context.class, updatedContextJson);
 System.out.println("New state: " + updatedContext.getState());
 

Implementation Details: REST API Implementation:

• Makes HTTP PATCH request to: PATCH /contexts/{uuid}
• Content-Type header set to: application/json;charset=UTF-8
• Accept header set to: application/json;charset=UTF-8
• JSON body contains the context with new state (other properties ignored)

UUID Extraction:

• Parses the input JSON to extract the context UUID
• Uses the UUID for the REST API path parameter
• Validates that the UUID is present and valid

Authorization:

• Uses current security context from SecretManagerProvider
• Authorization headers automatically added via getGXHTTPStringRequest()

Response Processing:

• Server response processed via HTTPUtility.getResponse()
• Returns complete updated context as JSON string
• Response includes all context properties with the updated state

Cache Management:

• Forces cache refresh via forceCacheRefresh() after state change (in finally block)
• Cache refresh is attempted even if state change fails to ensure consistency
• Cache refresh failures are silently ignored to not interfere with state change result

Error Handling:

• ResourceRegistryException propagated from server (e.g., authorization errors, invalid state)
• JSON parsing exceptions wrapped in RuntimeException
• Cache refresh errors are caught and ignored

Logging:

• Trace-level logging for state change initiation with context details
• Trace-level logging for successful state change completion

Specified by:

changeState in interface ResourceRegistryContextClient

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

public 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 the state of an existing context using its UUID and the desired state. Corresponding REST API: PATCH /contexts/{context-uuid} Operation Behavior:

• State-Only Operation: Only the state property is evaluated and applied by the server
• Complete Response: Returns the complete updated context with the new state and all other properties
• Type Safety: Uses ContextState enum instead of string, preventing invalid state values at compile time
• Simplicity: No need to construct a full context object or JSON string.

HTTP Response Codes:

• 200 OK: Context state successfully changed
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid state value or validation failure
• 403 Forbidden: User lacks authorization to change the context state
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• UUID must be a valid UUID format
• State values must be valid according to the ContextState enum
• Context must exist and be accessible to the user.

Authorization Requirements:

• IS-Manager: Can change state of any context without restrictions
• Infrastructure-Manager: Can change state of any context without restrictions
• Context-Manager: Can change state of contexts only if they are Context-Manager of the parent context
• Other Users: Cannot change context states (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Change context state directly
 Context updatedContext = client.changeState(contextUuid, ContextState.ACTIVE);
 System.out.println("New state: " + updatedContext.getState());
 
 // All other properties are preserved
 System.out.println("Context name unchanged: " + updatedContext.getName());
 
 // Example with different states
 client.changeState(contextUuid, ContextState.INACTIVE);
 client.changeState(contextUuid, ContextState.READY);
 

Implementation Details: Minimal Context Construction:

• Creates a new Context instance with only UUID and state properties set
• Uses ContextImpl with temporary name for minimal object creation
• All other context properties remain null/default values

Type Safety:

• Uses ContextState enum for compile-time validation
• Automatically converts enum to its string representation via getState()
• Eliminates runtime errors from invalid state strings

Delegation:

• Delegates to existing changeState(Context) method for consistency
• Inherits all caching, error handling, and REST API interaction behavior

Cache Management:

• Cache refresh is handled by the delegated changeState(Context) method
• Ensures consistency with other changeState method implementations

Specified by:

changeState in interface ResourceRegistryContextClient

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

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

Changes the state of an existing context using its UUID (as string) and the desired state (as string). This method provides string-based parameters for scenarios where enum types are not available or preferred. Corresponding REST API: PATCH /contexts/{context-uuid} Operation Behavior:

• State-Only Operation: Only the state property is evaluated and applied by the server
• Complete Response: Returns the complete updated context as JSON with the new state and all other properties
• Converts string parameters to appropriate types and delegates to internal change state operation.

HTTP Response Codes:

• 200 OK: Context state successfully changed
• 404 Not Found: Context with the specified UUID is not found
• 400 Bad Request: Invalid UUID format, state value, or validation failure
• 403 Forbidden: User lacks authorization to change the context state
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• UUID string must be a valid UUID format
• State strings must correspond to valid ContextState enum values
• Context must exist and be accessible to the user.

Authorization Requirements:

• IS-Manager: Can change state of any context without restrictions
• Infrastructure-Manager: Can change state of any context without restrictions
• Context-Manager: Can change state of contexts only if they are Context-Manager of the parent context
• Other Users: Cannot change context states (will receive authorization errors).

Example Usage:

 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
 
 String contextUuidString = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 
 // Change context state using strings
 String updatedContextJson = client.changeState(contextUuidString, "ACTIVE");
 
 // Parse response to verify state change
 Context updatedContext = ElementMapper.unmarshal(Context.class, updatedContextJson);
 System.out.println("New state: " + updatedContext.getState());
 
 // Example with different states
 client.changeState(contextUuidString, "INACTIVE");
 client.changeState(contextUuidString, "READY");
 
 // Error handling for invalid inputs
 try {
     client.changeState("invalid-uuid", "ACTIVE");
 } catch (IllegalArgumentException e) {
     System.err.println("Invalid UUID format");
 }
 
 try {
     client.changeState(contextUuidString, "INVALID_STATE");
 } catch (ResourceRegistryException e) {
     System.err.println("Invalid state value");
 }
 

Implementation Details: String to Enum Conversion:

• Converts the state string to ContextState enum using ContextState.fromString()
• Handles case-insensitive matching via the enum's fromString method
• Provides detailed error messages for invalid state strings with valid options listed

UUID Validation:

• Converts the UUID string to UUID object using UUID.fromString()
• Validates UUID format and throws IllegalArgumentException for invalid formats
• Provides clear error messages for malformed UUIDs

Delegation:

• Delegates to changeState(UUID, ContextState) for type-safe processing
• Marshals the resulting Context object back to JSON string using ElementMapper.marshal()
• Returns complete updated context as JSON with new state and all other properties

Cache Management:

• Cache refresh is handled by the delegated method chain
• Ensures consistency with other changeState method implementations

Error Handling:

• IllegalArgumentException for invalid UUID format or state string
• ResourceRegistryException propagated from underlying operations
• Other exceptions wrapped in RuntimeException

Specified by:

changeState in interface ResourceRegistryContextClient

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