Package org.gcube.informationsystem.resourceregistry.rest

Class ContextManager

java.lang.Object
org.gcube.informationsystem.resourceregistry.rest.BaseRest
org.gcube.informationsystem.resourceregistry.rest.ContextManager
@Path("contexts") public class ContextManager extends BaseRest
Author:
Luca Frosini (ISTI - CNR)

  • Field Details

    • CONTEXT_UUID_PATH_PARAMETER

      public static final String CONTEXT_UUID_PATH_PARAMETER
      Constant representing the context UUID path parameter.
      See Also:

  • Constructor Details

    • ContextManager

      public ContextManager()

  • Method Details

    • listContexts

      @GET @Produces("application/json;charset=UTF-8") public String listContexts() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of all contexts in the system. The response can include metadata and provides pagination based on query parameters and user authorization. REST Endpoint: GET /contexts[?limit={limit}&offset={offset}&includeMeta={true|false}] Request Examples:
      • GET /contexts (returns first 10 contexts - default pagination)
      • GET /contexts?limit=20 (returns first 20 contexts)
      • GET /contexts?offset=10 (returns 10 contexts starting from the 11th - default limit with offset)
      • GET /contexts?limit=5&offset=15 (returns 5 contexts starting from the 16th)
      • GET /contexts?includeMeta=true (returns first 10 contexts with metadata - for non-admin users)
      • GET /contexts?limit=20&includeMeta=true (returns first 20 contexts with metadata).
      Query Parameters: limit (optional):
      • Maximum number of contexts to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 contexts).
      offset (optional):
      • Number of contexts to skip from the beginning of the result set
      • Default value: 0 (starts from the first context)
      • Example: ?offset=100 (skips the first 100 contexts)
      • Commonly used with limit for pagination: ?limit=50&offset=100.
      includeMeta (optional):
      • Whether to include metadata in the response (for non-admin users)
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with obfuscated sensitive fields)
      • Note: IS-Manager and Infrastructure-Manager always receive metadata regardless of this parameter.
      Authorization Requirements: IS-Manager:
      • Automatically receive full context information including:
      • Complete metadata (createdBy, lastUpdateBy, creation/modification dates); • Context state information; • All context properties without obfuscation.
      • Metadata is included by default regardless of request parameters.
      Infrastructure-Manager:
      • Automatically receive full context information including:
      • Complete metadata (createdBy, lastUpdateBy, creation/modification dates); • Context state information; • All context properties without obfuscation.
      • Metadata is included by default regardless of request parameters.
      Other Users:
      • Receive basic context information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive metadata with sensitive information filtered:
      • Date fields (creation, modification) are visible; • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden; • Other administrative details may be filtered. Response Codes:
      • 200 OK: Contexts successfully retrieved
      • 403 Forbidden: User lacks authorization to access context information
      • 500 Internal Server Error: Server error during context retrieval.
      Response Format:
      • Content-Type: application/json
      • Body: JSON array containing context objects with role-appropriate detail level
      • Pagination information may be included in response headers.
      Returns:
      JSON array containing context objects with role-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if contexts cannot be retrieved
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for other retrieval errors

    • read

      @GET @Path("{context-uuid}") @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String read(@PathParam("context-uuid") 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. The response includes metadata and detail level based on query parameters and user authorization. REST Endpoint: GET /contexts/{context-uuid}[?includeMeta={true|false}] Request Examples:
      • GET /contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0 (returns basic context information)
      • GET /contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0?includeMeta=true (returns context with metadata - for non-admin users)
      • GET /contexts/CURRENT_CONTEXT (returns the current context - retrieved from client's authorization token).
      Path Parameters: context-uuid (required):
      • The unique identifier of the context to retrieve
      • Must be a valid UUID string format (e.g., "c0f314e7-2807-4241-a792-2a6c79ed4fd0")
      • Special keyword: "CURRENT_CONTEXT" to retrieve the context from client's authorization token
      • When using "CURRENT_CONTEXT", the actual context is extracted from the JWT token sent by the client
      • Example: GET /contexts/CURRENT_CONTEXT returns the context the client is authorized for.
      Query Parameters: includeMeta (optional):
      • Whether to include metadata in the response (for non-admin users)
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with obfuscated sensitive fields)
      • Note: IS-Manager and Infrastructure-Manager always receive metadata regardless of this parameter.
      Authorization Requirements: IS-Manager:
      • Can retrieve context information for any context without restrictions
      • Automatically receive full context information including complete metadata
      • All context properties and state information without obfuscation
      • Metadata is included by default regardless of request parameters.
      Infrastructure-Manager:
      • Can retrieve context information for any context without restrictions
      • Automatically receive full context information including complete metadata
      • All context properties and state information without obfuscation
      • Metadata is included by default regardless of request parameters.
      Context-Manager:
      • When operating in their own context (using a token from that context):
      • Receive full context information like IS-Manager and Infrastructure-Manager; • Complete metadata without obfuscation; • All context properties and state information.
      • When operating outside their context or requesting other contexts:
      • Receive basic context information by default; • Can request metadata via includeMeta=true with obfuscated sensitive fields. Other Users:
      • Receive basic context information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive metadata with sensitive information filtered:
      • Date fields (creation, modification) are visible; • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden; • Other administrative details may be filtered. Response Codes:
      • 200 OK: Context successfully retrieved
      • 404 Not Found: Context with the specified UUID does not exist
      • 403 Forbidden: User lacks authorization to access the specific context
      • 400 Bad Request: Invalid UUID format.
      Response Format:
      • Content-Type: application/json
      • Body: JSON object containing the context with role-appropriate detail level
      • Includes context properties, metadata (if authorized), and state information.
      Parameters:
      uuid - the UUID of the context to retrieve, or "CURRENT_CONTEXT" to get the context from client's authorization token
      Returns:
      JSON object containing the context 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 - for other retrieval errors

    • updateCreate

      @PUT @Path("{context-uuid}") @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String updateCreate(@PathParam("context-uuid") String uuid, String json) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new context or updates an existing context with the provided JSON representation. Only authorized administrative users can perform this operation. REST Endpoint: PUT /contexts/{context-uuid} Request Examples:
      • PUT /contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0 (create/update context).
      Path Parameters: context-uuid (required):
      • The unique identifier of the context to create or update
      • Must be a valid UUID string format (e.g., "c0f314e7-2807-4241-a792-2a6c79ed4fd0").
      Request Body:
      • JSON representation of the context to create or update
      • Must conform to the Context schema definition.
      Authorization Requirements: IS-Manager:
      • Can create/update any context without restrictions
      • Has full administrative privileges across all contexts.
      Infrastructure-Manager:
      • Can create/update any context without restrictions
      • Has full administrative privileges across all contexts.
      Context-Manager:
      • Can create/update 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)
      • Cannot create/update contexts outside their management scope.
      Other Users:
      • Cannot create or update contexts
      • Will receive authorization errors if attempting these operations.
      Operation Behavior: Context Property Changes and Operations: Name Change:
      • Updates the context name while preserving all other properties
      • Changes the full path of the context and all its child contexts
      • No effect on instances belonging to this context (instances remain in the context)
      • No effect on instances in child contexts.
      Parent Change (Move Operation):
      • Moves the context to a different parent in the context hierarchy
      • Changes the full path of the context and all its child contexts
      • No effect on instances belonging to this context (instances remain in the context)
      • No effect on instances in child contexts
      • However, instances in hierarchical queries of the old and new parent contexts will change.
      Combined Name and Parent Change:
      • Both name and parent can be changed in the same update request
      • Results in both a rename and move operation applied simultaneously
      • The full path changes due to both the new name and new parent location
      • All effects described above for both operations apply.
      Additional Properties:
      • While certain roles may receive additional parameters in context definitions, these cannot be modified through update operations
      • Only name and parent can be effectively changed via update.
      Important Design Considerations:
      • The service is designed to work with UUIDs rather than full paths precisely because full paths can change
      • Context UUIDs remain stable regardless of name or parent changes
      • All internal references and relationships use UUIDs for consistency
      • Client applications should store and reference contexts by UUID, not by full path.
      Hierarchical Query Impact:
      • When a context is moved to a new parent, the hierarchical queries (queries that include child contexts) in both the old and new parent contexts will reflect the change
      • Instances belonging to the moved context will no longer appear in hierarchical queries of the old parent context
      • Instances belonging to the moved context will start appearing in hierarchical queries of the new parent context
      • The context hierarchy structure itself changes, but the effect is visible in terms of which instances are returned when querying with hierarchical=true parameter
      • Context Tree Structure: When listing contexts to construct the context tree hierarchy, the tree structure will obviously change to reflect the new parent-child relationships.
      Response Codes:
      • 200 OK: Context successfully updated
      • 201 Created: Context successfully created
      • 400 Bad Request: Invalid JSON representation or malformed request
      • 403 Forbidden: User lacks authorization to create/update contexts
      • 404 Not Found: Parent context not found (when creating new context).
      Response Format:
      • Content-Type: application/json
      • Body: Complete context information including metadata
      • All context properties and state information without obfuscation.
      Parameters:
      uuid - the UUID of the context to create or update
      json - the JSON representation of the context to create or update
      Returns:
      JSON object containing the created/updated context with complete metadata
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for creation/update errors or authorization failures

    • changeState

      @PATCH @Path("{context-uuid}") @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String changeState(@PathParam("context-uuid") String uuid, String json) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Changes the state of an existing context. Only the state property from the JSON body is evaluated and returns the complete updated context. Only authorized administrative users can perform this operation. REST Endpoint: PATCH /contexts/{context-uuid} Request Examples:
      • PATCH /contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0
      Body: {"state": "active"} (changes context state to active). Path Parameters: context-uuid (required):
      • The unique identifier of the context whose state should be changed
      • Must be a valid UUID string format (e.g., "c0f314e7-2807-4241-a792-2a6c79ed4fd0").
      Request Body:
      • JSON representation containing the new state (other properties ignored)
      • Must contain a Context JSON representation
      • Only the "state" property will be processed and applied.
      Body Requirements: JSON Body Structure:
      • Must contain a Context JSON representation
      • Only the "state" property will be processed and applied
      • All other properties in the body are ignored
      • State values must be valid according to ContextState class.
      Valid State Values:
      • Refer to ContextState class for complete list of valid state values
      • Invalid state values will result in an error.
      Authorization Requirements: IS-Manager:
      • Can change state of any context without restrictions
      • Has full administrative privileges across all contexts.
      Infrastructure-Manager:
      • Can change state of any context without restrictions
      • Has full administrative privileges across all contexts.
      Context-Manager:
      • Can change state of 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)
      • Cannot change state of contexts outside their management scope.
      Other Users:
      • Cannot change context states
      • Will receive authorization errors if attempting these operations.
      Response Codes:
      • 200 OK: Context state successfully changed
      • 400 Bad Request: Invalid state value or malformed request
      • 403 Forbidden: User lacks authorization to change context state
      • 404 Not Found: Context with specified UUID does not exist.
      Response Format:
      • Content-Type: application/json
      • Body: Complete updated context (not just the state)
      • Full context information including complete metadata without obfuscation
      • All context properties and updated state information are included
      • Metadata is always included since only administrative users can access this endpoint.
      Parameters:
      uuid - the UUID of the context whose state should be changed
      json - the JSON representation containing the new state (other properties ignored)
      Returns:
      JSON object containing the complete updated context with new state and full metadata
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for state change errors or authorization failures

    • delete

      @DELETE @Consumes({"text/plain","application/json;charset=UTF-8"}) @Path("{context-uuid}") public jakarta.ws.rs.core.Response delete(@PathParam("context-uuid") 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. Only authorized administrative users can perform this irreversible operation. REST Endpoint: DELETE /contexts/{context-uuid} IMPORTANT: This is an irreversible operation that permanently removes the context from the system. Request Examples:
      • DELETE /contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0 (delete the specified context).
      Path Parameters: context-uuid (required):
      • The unique identifier of the context to delete
      • Must be a valid UUID string format (e.g., "c0f314e7-2807-4241-a792-2a6c79ed4fd0").
      Authorization Requirements: IS-Manager:
      • Can delete any context without restrictions
      • Has full administrative privileges across all contexts.
      Infrastructure-Manager:
      • Can delete any context without restrictions
      • Has full administrative privileges across all contexts.
      Context-Manager:
      • Can delete 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)
      • Cannot delete contexts outside their management scope.
      Other Users:
      • Cannot delete contexts
      • Will receive authorization errors if attempting these operations.
      Operation Behavior: Deletion Restrictions and Behavior: Context Hierarchy Restrictions:
      • Cannot delete a context that has child contexts
      • All child contexts must be deleted first (or moved to a different parent) before deleting a parent context
      • This ensures the integrity of the context hierarchy structure.
      Instance Management:
      • Instances belonging to the deleted context will no longer belong to any context
      • Critical: If instances exist only in the deleted context (not shared with other contexts), they will be permanently deleted from the system
      • Instances that also belong to other contexts will remain in those other contexts
      • This instance deletion is irreversible - ensure instances are backed up or moved to other contexts if needed.
      Hierarchical Query Impact:
      • Hierarchical queries performed on the parent context will change
      • Instances that were previously returned in hierarchical queries (due to belonging to the deleted context) will no longer appear
      • The context tree structure will be updated to reflect the removal.
      Context History and Audit Trail:
      • While the context is permanently removed from the active system, a record is maintained in an internal "cemetery" system
      • This allows for audit trails and historical tracking of deleted contexts
      • Future Enhancement: Administrative users will have the ability to list deleted contexts from this cemetery
      • The UUID of the deleted context becomes permanently unavailable for reuse.
      Irreversible Operation:
      • This operation cannot be undone
      • Once deleted, the context cannot be restored through normal operations
      • All relationships, instances, and configuration associated with the context are permanently lost
      • Ensure proper backup and confirmation procedures before performing this operation.
      Response Codes:
      • 204 No Content: Context successfully deleted
      • 400 Bad Request: Context has child contexts and cannot be deleted
      • 403 Forbidden: User lacks authorization to delete contexts
      • 404 Not Found: Context with specified UUID does not exist.
      Response Format:
      • Content-Type: N/A (no response body)
      • Body: Empty (204 No Content response)
      • No response body is returned upon successful deletion
      • The context is permanently removed from the system.
      Parameters:
      uuid - the UUID of the context to delete
      Returns:
      HTTP 204 No Content response upon successful deletion
      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 - for deletion errors or authorization failures