Package org.gcube.informationsystem.resourceregistry.rest

Class SharingManager

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

  • Constructor Details

    • SharingManager

      public SharingManager()

  • Method Details

    • serializeAffectedInstaces

      protected String serializeAffectedInstaces(org.gcube.com.fasterxml.jackson.databind.ObjectMapper objectMapper, Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> affectedInstances) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

    • addRemoveNoPropagationConstraint

      public String addRemoveNoPropagationConstraint(@PathParam("context-uuid") String contextId, @QueryParam("operation") org.gcube.informationsystem.resourceregistry.api.rest.SharingPath.SharingOperation operation, @QueryParam("dryRun") @DefaultValue("false") Boolean dryRun, @QueryParam("forceAddToContext") @DefaultValue("false") Boolean forceAddToContext, String body) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Add/Remove to/from the context identified by context-uuid path parameter the list of instances contained in the body of the request. The the body is the following [ {"type" : "HostingNode", "id" : "16032d09-3823-444e-a1ff-a67de4f350a8" }, {"type" : "Hosts", "id" : "97ab8a6b-6b1b-4868-b8fc-ba48d0439ba9"}, {"type" : "EService", "id" : "d3b1a29b-aa70-4a5a-be83-361a4209dd3e"} ] Each instance is managed without considering the propagation constraint of relations. POST /sharing/contexts/{context-uuid}?operation=ADD|REMOVE&[dryRun=true] e.g POST /resource-registry/contexts/67062c11-9c3a-4906-870d-7df6a43408b0?operation=ADD&dryRun=true; POST /resource-registry/contexts/67062c11-9c3a-4906-870d-7df6a43408b0?operation=REMOVE. where 67062c11-9c3a-4906-870d-7df6a43408b0/ is the Context UUID The body contains the list of instances to add/remove to/from the context identified by context-uuid
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException
      org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

    • addRemove

      @POST @Path("/contexts/{context-uuid}/{type-name}/{instance-uuid}") @Produces("application/json;charset=UTF-8") public String addRemove(@PathParam("context-uuid") String contextId, @PathParam("type-name") String type, @PathParam("instance-uuid") String instanceId, @QueryParam("operation") org.gcube.informationsystem.resourceregistry.api.rest.SharingPath.SharingOperation operation, @QueryParam("dryRun") @DefaultValue("false") Boolean dryRun, @QueryParam("forceAddToContext") @DefaultValue("false") Boolean forceAddToContext) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Add or remove an instance from a context. The operation can have a cascade effect due to propagation constraints. Returns the list of instances affected by the add/remove operation on the target instance identified by UUID path parameter. REST Endpoint: POST /sharing/contexts/{context-uuid}/{type-name}/{instance-uuid}?operation={ADD|REMOVE}[&dryRun={true|false}][&forceAddToContext={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Request Examples:
      • POST /sharing/contexts/67062c11-9c3a-4906-870d-7df6a43408b0/HostingNode/16032d09-3823-444e-a1ff-a67de4f350a8?operation=ADD (add HostingNode to context)
      • POST /sharing/contexts/67062c11-9c3a-4906-870d-7df6a43408b0/HostingNode/16032d09-3823-444e-a1ff-a67de4f350a8?operation=REMOVE (remove HostingNode from context)
      • POST /sharing/contexts/67062c11-9c3a-4906-870d-7df6a43408b0/HostingNode/16032d09-3823-444e-a1ff-a67de4f350a8?operation=ADD&dryRun=true (preview what would be affected by adding HostingNode)
      • POST /sharing/contexts/67062c11-9c3a-4906-870d-7df6a43408b0/HostingNode/16032d09-3823-444e-a1ff-a67de4f350a8?operation=ADD&forceAddToContext=true (force add even if instance is not in current context)
      • POST /sharing/contexts/67062c11-9c3a-4906-870d-7df6a43408b0/HostingNode/16032d09-3823-444e-a1ff-a67de4f350a8?operation=ADD&includeMeta=true&includeContexts=true (add with metadata and context information in response).
      Where:
      • 67062c11-9c3a-4906-870d-7df6a43408b0 is the Context UUID
      • 16032d09-3823-444e-a1ff-a67de4f350a8 is the HostingNode UUID.
      Path Parameters:
      • context-uuid: The UUID of the target context where the instance should be added or removed
      • type-name: The name of the Information System type (e.g., "EService", "ContactFacet")
      • instance-uuid: The unique identifier of the instance to add or remove.
      Query Parameters: operation (required):
      • Specifies the operation to perform on the instance
      • Values: ADD (add instance to context) | REMOVE (remove instance from context)
      • ADD: Adds the specified instance to the target context, respecting propagation constraints
      • REMOVE: Removes the specified instance from the target context, respecting propagation constraints.
      dryRun (optional):
      • Whether to perform a preview of the operation without actually executing it
      • Default value: false (execute the operation)
      • Values: true | false
      • When true: Returns the list of instances that would be affected by the operation, but does not perform any actual changes
      • When false: Performs the actual add/remove operation and returns the list of instances that were affected
      • Useful for previewing the cascade effects before committing to the operation.
      forceAddToContext (optional):
      • Forces the addition of an instance to a context even if the instance is not present in the current context
      • Default value: false (standard validation applies)
      • Values: true | false
      • Authorization Required: Only available to IS-Manager and Infrastructure-Manager
      • When true: Allows adding an instance to a context even if the instance exists only in other contexts
      • When false: Standard validation applies - instance must be accessible in the current context for ADD operations
      • Only applies to ADD operations; ignored for REMOVE operations.
      includeMeta (optional):
      • Whether to include metadata in the response for affected instances
      • Default value: false (basic information only)
      • Values: true | false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Metadata includes the created/updated instance and nested elements based on polymorphic setting
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (optional):
      • Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Values: true | false
      • Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Available to all users (not restricted to administrators).
      includeContexts (optional):
      • Whether to include the list of contexts where the instance and its nested elements are available in the response
      • Default value: false (context information not included)
      • Values: true | false
      • Example: ?includeContexts=true (shows context availability for the instance and nested elements)
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: Unlike read operations, this parameter does not require hierarchical=true.
      Authorization Requirements: IS-Manager:
      • Can perform ADD/REMOVE operations on any instance in any context
      • Can use forceAddToContext=true to add instances from other contexts
      • Full administrative privileges across all contexts
      • See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.
      Infrastructure-Manager:
      • Can perform ADD/REMOVE operations on any instance in any context
      • Can use forceAddToContext=true to add instances from other contexts
      • Full administrative privileges across all contexts
      • See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.
      Other Users:
      • Can perform ADD/REMOVE operations only on instances accessible in their current context
      • Cannot use forceAddToContext=true (parameter is ignored if provided)
      • Operations are limited to instances they have access to in their authorized context
      • See filtered metadata with sensitive fields obfuscated when includeMeta=true.
      Operation Behavior: Propagation Constraints and Cascade Effects: ADD Operation Cascading:
      • When an instance is added to a context, related instances may also be automatically added due to propagation constraints
      • The response includes all instances that were added as part of the cascade effect
      • Propagation follows the schema-defined relationships and their constraints.
      REMOVE Operation Cascading:
      • When an instance is removed from a context, related instances may also be automatically removed due to propagation constraints
      • The response includes all instances that were removed as part of the cascade effect
      • Propagation follows the schema-defined relationships and their constraints.
      Schema Validation for ConsistsOf Relations and Facets:
      • When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
      • If the Resource is no longer compliant with its schema after the add/remove operation, a SchemaViolationException is thrown
      • This results in an HTTP 400 Bad Request response with details about the schema violation
      • Example scenarios that violate schema constraints:
      • Removing a required/mandatory Facet or ConsistsOf relation from a Resource; • Adding/removing instances that violate cardinality constraints (min/max occurrences) defined in the schema.
      • All these scenarios make the Resource incomplete or invalid according to its schema definition
      • Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
      • Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.
      Response Codes:
      • 200 OK: Operation completed successfully (instances added/removed)
      • 400 Bad Request: Schema validation failed (SchemaViolationException) - occurs when operation would violate schema constraints
      • 404 Not Found: Instance, type, or context not found
      • 403 Forbidden: Insufficient permissions to perform the operation.
      Response Format: Success Response:
      • Returns a JSON array containing all instances affected by the operation
      • Each instance object includes its UUID, type, and relevant metadata
      • For dryRun=true: Shows what would be affected without making changes
      • For dryRun=false: Shows what was actually affected by the completed operation.
      Example Response: ``json [ { "id": "16032d09-3823-444e-a1ff-a67de4f350a8", "type": "HostingNode", // ... additional instance properties }, { "id": "97ab8a6b-6b1b-4868-b8fc-ba48d0439ba9", "type": "Hosts", // ... additional instance properties } ] ``
      Parameters:
      contextId - the UUID of the target context for the add/remove operation
      type - the type name of the instance to add/remove (e.g., "HostingNode", "EService")
      instanceId - the UUID of the instance to add/remove
      operation - the operation to perform: ADD (add to context) or REMOVE (remove from context)
      dryRun - whether to preview the operation without executing it (default: false)
      forceAddToContext - whether to force addition even if instance is not in current context - admin only (default: false)
      Returns:
      JSON array containing all instances affected by the operation (or that would be affected if dryRun=true)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if the operation violates schema constraints
      org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - if the specified instance is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the specified context is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for other operation errors or authorization failures