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. Purpose: This interface provides methods for creating, reading, updating, deleting, and managing the state of contexts within the Resource Registry. Contexts represent organizational units that contain and organize Information System resources, facets, and relations. Instantiation: Clients should be created using the factory pattern for proper configuration: 
 // Recommended way to create a client
 ResourceRegistryContextClient client = ResourceRegistryContextClientFactory.create();
Supported Operations:
  • CRUD Operations: Create, Read, Update, Delete contexts with full lifecycle management
  • State Management: Change context states (ACTIVE, READY, DOWN) with proper validation
  • Query Operations: List all contexts with filtering and pagination support
  • Current Context: Access the context associated with the current authorization token
Query Parameter Configuration: Most methods support optional query parameters that can be configured via the client's header mechanism:
  • includeMeta: Include metadata in responses (role-based filtering applied)
  • limit: Maximum number of results per request
  • offset: Number of results to skip for pagination
Authorization: All operations respect strict authorization rules based on user roles:
  • IS-Manager: Full access to all contexts and operations
  • Infrastructure-Manager: Full access to all contexts and operations
  • Context-Manager: Full access only within their managed contexts
  • Other Users: Limited read access based on context membership
Context States: Contexts can be in different states managed through state change operations:
  • ACTIVE: Context is fully operational and accessible
  • READY: Context is prepared but not yet active
  • DOWN: Context is temporarily unavailable
Context Support: The client automatically operates within the context determined by the authorization token.
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)
    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.
    org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache
    getContextCache()
    Gets the context cache used for context-related operations.
    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
    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 interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

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

  • Method Details

    • addHeader

      void addHeader(String name, String value)
      Adds a custom HTTP header to be included in requests.
      Parameters:
      name - Header name
      value - Header value

    • addHeader

      void addHeader(String name, boolean value)
      Adds a custom HTTP header to be included in requests.
      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.
      Returns:
      The context cache instance

    • all

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

    • 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 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);
      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:

    • create

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

    • 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. 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");
 }
      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. 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);
 }
      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 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);
      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(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);
      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

      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");
 }
      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

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

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

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

      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");
 }
      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

      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");
 }
      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

      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);
 }
      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
      IllegalArgumentException - if the provided string is not a valid UUID format

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

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