Package org.gcube.informationsystem.resourceregistry.persistence.orientdb.instances

Class ERManagementUtility

java.lang.Object
org.gcube.informationsystem.resourceregistry.persistence.orientdb.instances.ERManagementUtility
public class ERManagementUtility extends Object
Author:
Luca Frosini (ISTI - CNR)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    ERManagementUtility.HierarchyScope
    The descendant Contexts a hierarchy synchronization aligns to the submitted Resource.
    static final record 
    ERManagementUtility.HierarchySyncResult
    The outcome of a hierarchy synchronization.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ERManagementUtility()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode>
    addToContextNoPropagationConstraint(Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> expectedInstances, UUID contextUUID, boolean dryRun)
    Adds a map of expected instances to the specified context without evaluating propagation constraints.
    static ElementManagement<?,?>
    getERManagement(String type)
    Resolves and returns the corresponding ElementManagement instance for the specified class type name.
    static ElementManagement<?,?>
    getERManagement(String type, UUID uuid)
    Returns the management of the instance addressed by the given Type and UUID.
    static ElementManagement<?,?>
    getERManagement(Environment workingContext, com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph, com.orientechnologies.orient.core.record.OElement element)
    Resolves and returns the corresponding ElementManagement instance for the specified database element.
    static ElementManagement<?,?>
    getERManagementFromUUID(Environment workingContext, com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph, UUID uuid)
    Resolves and returns the corresponding ElementManagement instance for the specified element UUID.
    static Environment
    getWorkingEnvironment(UUID contextUUID, boolean hierarchical, boolean activeOnlyHierarchical)
    Returns the environment an Entity or a Relation is looked up in: the given Context, or the token Context when none is given, refused when the Context is not effectively ACTIVE and the caller lacks the administrative state override.
    static boolean
    isDeletedInTransaction(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Tells whether an element has been deleted by the open transaction of the given session.
    static boolean
    isInContext(com.orientechnologies.orient.core.record.OElement element, InstanceEnvironment instanceEnvironment, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Tells whether an element is present in a Context as the open transaction of the given session sees it: an element the transaction has already removed from the Context, or deleted, is absent, although the committed state still lists it.
    static boolean
    isInNoContext(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Tells whether an element belongs to no Context at all as the open transaction of the given session sees it, the condition under which an instance is deleted.
    static Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode>
    removeFromContextNoPropagationConstraint(Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> expectedInstances, UUID contextUUID, boolean dryRun)
    Removes a map of expected instances from the specified context without evaluating propagation constraints.
    static boolean
    replacementOmitsSharedConsistsOf(String type, UUID uuid, String json)
    Tells whether the full replacement of a Resource takes out of the token Context a ConsistsOf relation, or its Facet, that is present in another Context too: the replacement that the connection of the token Context cannot perform (see ERManagementUtility.HierarchyScope.TOKEN_CONTEXT).
    static ERManagementUtility.HierarchySyncResult
    syncHierarchy(String type, UUID uuid, String json, ERManagementUtility.HierarchyScope scope, boolean administrative)
    Creates or updates a Resource in the current Context and aligns the selected descendant Contexts to the submitted representation, atomically: every aligned Context ends up with the Resource and exactly the ConsistsOf/Facet instances the payload describes.
    static void
    touchResource(com.orientechnologies.orient.core.record.OVertex resource, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Records on a Resource the modification of one of its ConsistsOf or Facet instances: its lastUpdateBy and lastUpdateTime are those of the latest modification made to the Resource itself or to any of them, in any Context.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ERManagementUtility

      public ERManagementUtility()

  • Method Details

    • getWorkingEnvironment

      public static Environment getWorkingEnvironment(UUID contextUUID, boolean hierarchical, boolean activeOnlyHierarchical) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the environment an Entity or a Relation is looked up in: the given Context, or the token Context when none is given, refused when the Context is not effectively ACTIVE and the caller lacks the administrative state override.
      Parameters:
      contextUUID - the UUID of the Context, or null for the token Context
      hierarchical - whether the lookup also covers the descendant Contexts
      activeOnlyHierarchical - whether a hierarchical lookup skips the non-ACTIVE descendants
      Returns:
      the environment of the Context
      Throws:
      jakarta.ws.rs.ForbiddenException - if the Context is not ACTIVE and the caller cannot operate there
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the Context cannot be read

    • isDeletedInTransaction

      public static boolean isDeletedInTransaction(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Tells whether an element has been deleted by the open transaction of the given session.
      Parameters:
      element - the element to check
      oDatabaseDocument - the session whose transaction is evaluated
      Returns:
      true if the transaction deletes the element

    • isInContext

      public static boolean isInContext(com.orientechnologies.orient.core.record.OElement element, InstanceEnvironment instanceEnvironment, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Tells whether an element is present in a Context as the open transaction of the given session sees it: an element the transaction has already removed from the Context, or deleted, is absent, although the committed state still lists it.
      Parameters:
      element - the element to check
      instanceEnvironment - the Context
      oDatabaseDocument - the session whose transaction is evaluated
      Returns:
      true if the element is present in the Context

    • isInNoContext

      public static boolean isInNoContext(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Tells whether an element belongs to no Context at all as the open transaction of the given session sees it, the condition under which an instance is deleted.
      Parameters:
      element - the element to check
      oDatabaseDocument - the session whose transaction is evaluated
      Returns:
      true if the element belongs to no Context

    • touchResource

      public static void touchResource(com.orientechnologies.orient.core.record.OVertex resource, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Records on a Resource the modification of one of its ConsistsOf or Facet instances: its lastUpdateBy and lastUpdateTime are those of the latest modification made to the Resource itself or to any of them, in any Context. It is the only place where the modification of another instance is recorded on a Resource; an IsRelatedTo never reaches it. A Resource the open transaction has deleted, or is creating and has not given its metadata yet, is left as it is.
      Parameters:
      resource - the Resource the modified ConsistsOf or Facet belongs to
      oDatabaseDocument - the session whose open transaction makes the modification
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the metadata cannot be updated

    • getERManagement

      public static ElementManagement<?,?> getERManagement(String type) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Resolves and returns the corresponding ElementManagement instance for the specified class type name.
      Parameters:
      type - the class type name
      Returns:
      the mapped ElementManagement instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the class type is not queryable or cannot be mapped

    • getERManagement

      public static ElementManagement<?,?> getERManagement(String type, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the management of the instance addressed by the given Type and UUID. A Type that exists but is not a Resource, Facet, IsRelatedTo or ConsistsOf Type has no instances: the key does not exist, exactly as with an unknown Type name or a Type that is not the concrete Type of the instance.
      Parameters:
      type - the concrete Type name of the instance
      uuid - the UUID of the instance
      Returns:
      the management, with its Type and UUID set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the Type is not an instance Type
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the Type does not exist

    • replacementOmitsSharedConsistsOf

      public static boolean replacementOmitsSharedConsistsOf(String type, UUID uuid, String json) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Tells whether the full replacement of a Resource takes out of the token Context a ConsistsOf relation, or its Facet, that is present in another Context too: the replacement that the connection of the token Context cannot perform (see ERManagementUtility.HierarchyScope.TOKEN_CONTEXT). It compares, before any transaction is opened, the ConsistsOf relations the Resource has in the token Context with the ones the payload carries. A Resource that does not exist in the token Context with the given Type, and a payload the write rejects, omit nothing: the ordinary write reports them.
      Parameters:
      type - the concrete Resource type name
      uuid - the Resource UUID
      json - the submitted Resource representation
      Returns:
      true if an omitted ConsistsOf, or its Facet, is present in another Context
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the stored Resource cannot be read

    • syncHierarchy

      public static ERManagementUtility.HierarchySyncResult syncHierarchy(String type, UUID uuid, String json, ERManagementUtility.HierarchyScope scope, boolean administrative) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates or updates a Resource in the current Context and aligns the selected descendant Contexts to the submitted representation, atomically: every aligned Context ends up with the Resource and exactly the ConsistsOf/Facet instances the payload describes. It is a synchronization of the payload, not an Add to Context: propagation constraints are not consulted, and no IsRelatedTo instance nor related Resource moves.

      A non-administrative caller skips the non-ACTIVE descendant Contexts, as its hierarchical reads do; administrative callers align them too.

      It writes through the administrative connection, which bypasses the record-level security of the database, so it keeps the write inside the token Context by itself: the Resource is resolved through the connection of the token Context, an existing ConsistsOf or Facet named in the payload must be present there (checkSubmittedConsistsOfInContext(org.gcube.com.fasterxml.jackson.databind.JsonNode, org.gcube.informationsystem.resourceregistry.environments.instances.InstanceEnvironment, com.orientechnologies.orient.core.db.document.ODatabaseDocument)), and each Context is validated on the ConsistsOf the Resource has in it. With ERManagementUtility.HierarchyScope.TOKEN_CONTEXT it is the plain full replacement of a Resource, with the outcome of the same write on the connection of the token Context.

      Parameters:
      type - the concrete Resource type name
      uuid - the Resource UUID, or null to let a creation generate it
      json - the submitted Resource representation
      scope - the descendant Contexts to align
      administrative - whether the caller may write in non-ACTIVE Contexts
      Returns:
      the outcome of the synchronization
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if synchronization fails

    • getERManagementFromUUID

      public static ElementManagement<?,?> getERManagementFromUUID(Environment workingContext, com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Resolves and returns the corresponding ElementManagement instance for the specified element UUID.
      Parameters:
      workingContext - the working environment
      orientGraph - the database document connection
      uuid - the UUID of the element to resolve
      Returns:
      the resolved ElementManagement instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the element does not exist or has an unmanageable type

    • getERManagement

      public static ElementManagement<?,?> getERManagement(Environment workingContext, com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph, com.orientechnologies.orient.core.record.OElement element) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Resolves and returns the corresponding ElementManagement instance for the specified database element.
      Parameters:
      workingContext - the working environment
      orientGraph - the database document connection
      element - the OrientDB element to resolve
      Returns:
      the resolved ElementManagement instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the element type is not manageable

    • addToContextNoPropagationConstraint

      public static Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> addToContextNoPropagationConstraint(Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> expectedInstances, UUID contextUUID, boolean dryRun) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Adds a map of expected instances to the specified context without evaluating propagation constraints.
      Parameters:
      expectedInstances - map of expected instances, from UUID to JSON node
      contextUUID - the UUID of the target context
      dryRun - true to simulate the operation without committing
      Returns:
      the map of successfully added instances
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the context does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context rules are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system failure

    • removeFromContextNoPropagationConstraint

      public static Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> removeFromContextNoPropagationConstraint(Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> expectedInstances, UUID contextUUID, boolean dryRun) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Removes a map of expected instances from the specified context without evaluating propagation constraints.
      Parameters:
      expectedInstances - map of expected instances, from UUID to JSON node
      contextUUID - the UUID of the target context
      dryRun - true to simulate the operation without committing
      Returns:
      the map of successfully removed instances
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the context does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if removal rules are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system failure