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

Class EntityManagement<E extends org.gcube.informationsystem.model.reference.entities.Entity,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema>

java.lang.Object
org.gcube.informationsystem.resourceregistry.persistence.orientdb.base.ElementManagement<com.orientechnologies.orient.core.record.OVertex,ET>
org.gcube.informationsystem.resourceregistry.persistence.orientdb.base.EntityElementManagement<E,ET>
org.gcube.informationsystem.resourceregistry.persistence.orientdb.instances.entities.EntityManagement<E,ET>
Type Parameters:
E - the specific Entity model interface managed by a concrete subclass
ET - the corresponding EntitySchema type-definition interface
All Implemented Interfaces:
ERManagement
Direct Known Subclasses:
FacetManagement, ResourceManagement
public abstract class EntityManagement<E extends org.gcube.informationsystem.model.reference.entities.Entity,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema> extends EntityElementManagement<E,ET> implements ERManagement
Base OrientDB persistence class for the two Entity categories, Resource and Facet (see the concrete ResourceManagement and FacetManagement subclasses). Implements the ERManagement contract shared with relations (RelationManagement) — context membership, Avalanche Effect propagation, and hierarchical reads — by leaving the selection of the listed memberships to a MembershipView, and implements the vertex-specific parts: creation, deletion, and traversal of ConsistsOf edges to embedded Facets. As of this evolution, this class carries no security-role logic of its own: it behaves deterministically from its explicit method arguments (e.g. PropagationMode and the flags inherited from ElementManagement), authorization being the exclusive responsibility of the Instances Policy Enforcement Point.
Author:
Luca Frosini (ISTI - CNR)

  • Field Details

    • sourceInstanceEnvironment

      protected InstanceEnvironment sourceInstanceEnvironment
      The source context of an addToContext

    • targetInstanceEnvironment

      protected InstanceEnvironment targetInstanceEnvironment
      The target context of an addToContext/removeFromContext

    • propagationMode

      protected org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode propagationMode
      By default the system honours the propagation constraints so this variable is initialised as true. To revert a previous operation or for a particular maintenance we could ask the service not to honour the propagation constraints, but only under certain conditions and with some limitations. These limitations are required to keep the system in a consistent state. In fact, this directive is only valid for Resources and IsRelatedTo relations. We need to take into account that when adding an IsRelatedTo to a context, the source and target Resources must always be in such a Context. Please also take into account that adding a Resource to a context always implies honouring the propagation constraints of ConsistsOf relations. In fact, a resource must be characterised by at least one facet in any context it belongs to. Given that we cannot make assumptions on which facets must be used, a way could be to consider only the facets that are mandatory for such a Resource Type, but the type could not have mandatory facets (even though every Resource Type in the gCube Model has one mandatory facet). Conversely, when a Resource is removed from a Context all the facets characterising it must be removed. This option can also be used in conjunction with ElementManagement.dryRun=true. This allows simulating a sharing operation without honouring the propagation constraints.

    • visited

      protected Set<UUID> visited
      Shared, mutable set of UUIDs (entities and relations alike) already visited during the current addToContext(UUID) cascade. Guarantees termination on a graph cycle (e.g. a cyclic IsRelatedTo chain) independently of PropagationMode — populated and checked unconditionally, even in modes (SHALLOW) whose own already-present check would already prevent a re-visit, so the guard stays uniform and orthogonal to mode semantics.

      Not the same bookkeeping as ElementManagement.affectedInstances: this set is marked on entry, before recursing into children (pre-order) - a node re-entered mid-cycle is caught here even though its own processing hasn't finished yet. ElementManagement.affectedInstances is only populated when processing completes successfully (post-order), so it cannot double as a cycle guard - a node being re-entered mid-recursion has not been added to it yet.

    • hierarchical

      protected boolean hierarchical
      Whether hierarchical lookup is enabled.

    • activeOnlyHierarchical

      protected boolean activeOnlyHierarchical
      Whether the active-only hierarchical reader channel must be used.

    • contextsPolicy

      protected org.gcube.informationsystem.resourceregistry.api.rest.ContextsPolicy contextsPolicy
      The contexts inclusion policy for responses.

    • forceAddToContext

      protected boolean forceAddToContext
      The instance is added to the context even if not in source context.

    • skipped

      protected boolean skipped
      Indicates that AddToContext skipped the instance because it was not in the source context.

  • Constructor Details

    • EntityManagement

      protected EntityManagement(org.gcube.informationsystem.base.reference.AccessType accessType)
      Creates a new EntityManagement instance for the specified access type.
      Parameters:
      accessType - the access type category of the entity

  • Method Details

    • setMembershipView

      public void setMembershipView(MembershipView membershipView)
      Description copied from interface: ERManagement
      Sets the view that selects the memberships listed by the contexts maps.
      Specified by:
      setMembershipView in interface ERManagement
      Parameters:
      membershipView - the membership view to apply

    • getMembershipView

      public MembershipView getMembershipView()
      Description copied from interface: ERManagement
      Gets the view that selects the memberships listed by the contexts maps.
      Specified by:
      getMembershipView in interface ERManagement
      Returns:
      the membership view

    • isHierarchical

      public boolean isHierarchical()
      Description copied from interface: ERManagement
      Gets whether hierarchical lookup is enabled.
      Specified by:
      isHierarchical in interface ERManagement
      Returns:
      true if hierarchical, false otherwise

    • setHierarchical

      public void setHierarchical(boolean hierarchical)
      Description copied from interface: ERManagement
      Sets whether hierarchical lookup is enabled.
      Specified by:
      setHierarchical in interface ERManagement
      Parameters:
      hierarchical - true to enable hierarchical, false otherwise

    • isActiveOnlyHierarchical

      public boolean isActiveOnlyHierarchical()
      Description copied from interface: ERManagement
      Gets whether the active-only hierarchical reader channel must be used instead of the unrestricted one - meaningless unless ERManagement.isHierarchical() is also true.
      Specified by:
      isActiveOnlyHierarchical in interface ERManagement
      Returns:
      true if the active-only channel must be used, false otherwise

    • setActiveOnlyHierarchical

      public void setActiveOnlyHierarchical(boolean activeOnlyHierarchical)
      Description copied from interface: ERManagement
      Sets whether the active-only hierarchical reader channel must be used instead of the unrestricted one. The PEP layer sets this to false for ALL_ADMIN_ROLES holders (unchanged, unrestricted behavior) and true for everyone else.
      Specified by:
      setActiveOnlyHierarchical in interface ERManagement
      Parameters:
      activeOnlyHierarchical - true to use the active-only channel

    • getContextsPolicy

      public org.gcube.informationsystem.resourceregistry.api.rest.ContextsPolicy getContextsPolicy()
      Description copied from interface: ERManagement
      Returns the contexts inclusion policy for responses.
      Specified by:
      getContextsPolicy in interface ERManagement
      Returns:
      the contexts policy, or null if not explicitly set (falls back to ContextsPolicy.DEFAULT)

    • setContextsPolicy

      public void setContextsPolicy(org.gcube.informationsystem.resourceregistry.api.rest.ContextsPolicy contextsPolicy)
      Description copied from interface: ERManagement
      Sets the contexts inclusion policy for responses.
      Specified by:
      setContextsPolicy in interface ERManagement
      Parameters:
      contextsPolicy - the contexts policy to set

    • setSourceInstanceEnvironment

      public void setSourceInstanceEnvironment(InstanceEnvironment source)
      Description copied from interface: ERManagement
      Sets the source InstanceEnvironment used to evaluate addToContext
      Specified by:
      setSourceInstanceEnvironment in interface ERManagement
      Parameters:
      source - the source security context

    • getContextsSet

      public Set<String> getContextsSet() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Returns the Context UUID strings of the memberships listed by ERManagement.getMembershipView().
      Specified by:
      getContextsSet in interface ERManagement
      Returns:
      the set of Context UUID strings
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context mapping fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getContexts

      public String getContexts() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns all contexts where this element is visible as a formatted JSON string.

      Warning: Any changes made to this implementation must also be applied to the corresponding method in RelationManagement to keep both ER hierarchies synchronized.

      Specified by:
      getContexts in interface ERManagement
      Returns:
      the JSON string of contexts mapping
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context mapping fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getContextsAsObjectNode

      public org.gcube.com.fasterxml.jackson.databind.node.ObjectNode getContextsAsObjectNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Returns all contexts where this element is visible as an ObjectNode mapping Context UUIDs to paths.
      Specified by:
      getContextsAsObjectNode in interface ERManagement
      Returns:
      the JSON ObjectNode of contexts mapping
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context mapping fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getSourceInstanceEnvironment

      public InstanceEnvironment getSourceInstanceEnvironment()
      Returns the source instance environment of an addToContext operation.
      Specified by:
      getSourceInstanceEnvironment in interface ERManagement
      Returns:
      the source instance environment

    • setTargetInstanceEnvironment

      public void setTargetInstanceEnvironment(InstanceEnvironment target)
      Sets the target instance environment of an addToContext/removeFromContext operation.
      Specified by:
      setTargetInstanceEnvironment in interface ERManagement
      Parameters:
      target - the target instance environment to set

    • getTargetInstanceEnvironment

      public InstanceEnvironment getTargetInstanceEnvironment()
      Returns the target instance environment of an addToContext/removeFromContext operation.
      Specified by:
      getTargetInstanceEnvironment in interface ERManagement
      Returns:
      the target instance environment

    • getPropagationMode

      public org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode getPropagationMode()
      Returns the propagation mode configured for this operation.
      Specified by:
      getPropagationMode in interface ERManagement
      Returns:
      the propagation mode

    • setPropagationMode

      public void setPropagationMode(org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode propagationMode)
      Sets the propagation mode configured for this operation.
      Specified by:
      setPropagationMode in interface ERManagement
      Parameters:
      propagationMode - the propagation mode to set

    • setVisited

      public void setVisited(Set<UUID> visited)
      Description copied from interface: ERManagement
      Sets the shared, mutable set of UUIDs (entities and relations alike) already visited during the current ERManagement.addToContext(UUID) cascade. Checked and populated unconditionally by every ERManagement instance in the cascade, regardless of PropagationMode — cycle-safety is kept orthogonal to whatever each mode otherwise decides about re-visiting an already-present instance, so it does not need to be re-derived if propagation semantics change later.
      Specified by:
      setVisited in interface ERManagement
      Parameters:
      visited - the shared visited-UUID set; the same instance must be threaded through the whole cascade of a single ERManagement.addToContext(UUID) call

    • getVisited

      public Set<UUID> getVisited()
      Description copied from interface: ERManagement
      Returns the shared, mutable set of UUIDs already visited during the current ERManagement.addToContext(UUID) cascade.
      Specified by:
      getVisited in interface ERManagement
      Returns:
      the shared visited-UUID set, or null if not yet initialised

    • isForceAddToContext

      public boolean isForceAddToContext()
      Description copied from interface: ERManagement
      Gets whether the operation should force add to context even if the instance is not in source context.
      Specified by:
      isForceAddToContext in interface ERManagement
      Returns:
      true if force add, false otherwise

    • setForceAddToContext

      public void setForceAddToContext(boolean forceAddToContext)
      Description copied from interface: ERManagement
      Sets whether the operation should force add to context even if the instance is not in source context.
      Specified by:
      setForceAddToContext in interface ERManagement
      Parameters:
      forceAddToContext - true to force add, false otherwise

    • getWorkingEnvironment

      protected Environment getWorkingEnvironment() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Returns the active database working environment.
      Specified by:
      getWorkingEnvironment in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      the working environment
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the environment cannot be resolved

    • getElement

      public com.orientechnologies.orient.core.record.OVertex getElement() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Returns the OrientDB element instance, retrieving and caching it if not already present.
      Overrides:
      getElement in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      the OrientDB element instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getRelationManagement

      protected RelationManagement<?,?> getRelationManagement(com.orientechnologies.orient.core.record.OEdge edge) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves or instantiates the RelationManagement helper for a given OEdge.
      Parameters:
      edge - the OrientDB edge
      Returns:
      the bound RelationManagement instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if lookup or initialization fails

    • addToRelationManagements

      public void addToRelationManagements(RelationManagement<?,?> relationManagement) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Cache-registers an existing RelationManagement helper.
      Parameters:
      relationManagement - the relation management helper to register
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a different instance is already registered for the same edge

    • addRelation

      protected static org.gcube.com.fasterxml.jackson.databind.JsonNode addRelation(org.gcube.com.fasterxml.jackson.databind.JsonNode sourceResource, org.gcube.com.fasterxml.jackson.databind.JsonNode relation, String arrayKey) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Appends a relation JSON representation to an existing source resource JSON node.
      Parameters:
      sourceResource - the parent/source resource JSON node
      relation - the relation JSON node to append
      arrayKey - the JSON property key of the relation array
      Returns:
      the updated source resource JSON node
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on mapping or serialization error

    • createVertex

      protected com.orientechnologies.orient.core.record.OVertex createVertex() throws org.gcube.informationsystem.resourceregistry.api.exceptions.instances.entities.EntityAlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: EntityElementManagement
      Instantiates, validates, and persists a new OrientDB Vertex element.
      Overrides:
      createVertex in class EntityElementManagement<E extends org.gcube.informationsystem.model.reference.entities.Entity,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      the created OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - if a vertex with the specified UUID already exists
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the schema class is abstract or if database creation fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.entities.EntityAlreadyPresentException

    • reallyAddToContext

      protected void reallyAddToContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Abstract method implementation that performs the database-level operations to add the entity and its propagated components to the target context.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context rules or scoping constraints are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or execution error

    • internalAddToContext

      public void internalAddToContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Performs the internal low-level operations to add the entity/relationship to the target context.
      Specified by:
      internalAddToContext in interface ERManagement
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context assignment violates rules
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system error

    • addToContext

      public void addToContext(UUID contextUUID) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Adds the entity/relationship to the specified context, evaluating schemas and constraints.
      Specified by:
      addToContext in interface ERManagement
      Parameters:
      contextUUID - the UUID of the destination context
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if schema rules are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the context does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context assignment violates rules
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system error

    • internalRemoveFromContext

      public void internalRemoveFromContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Performs the internal low-level operations to remove the entity/relationship from the context.
      Specified by:
      internalRemoveFromContext in interface ERManagement
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if removal violates rules
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system error

    • reallyRemoveFromContext

      protected void reallyRemoveFromContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Abstract method implementation that performs the database-level operations to remove the entity from the target context, applying any cascade deletions if required.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if context rules or scoping constraints are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or execution error

    • removeFromContext

      public void removeFromContext(UUID contextUUID) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from interface: ERManagement
      Removes the entity/relationship from the specified context.
      Specified by:
      removeFromContext in interface ERManagement
      Parameters:
      contextUUID - the UUID of the context from which to remove
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if schema rules are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the context does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextException - if removal violates rules
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or system error

    • reallyGetAll

      public String reallyGetAll() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Serializes the Entity page using the configured projection and Context visibility.
      Specified by:
      reallyGetAll in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,ET extends org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      JSON array string of all elements
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database traversal or serialization error

    • reallyQuery

      public String reallyQuery(String relationType, String referenceType, UUID referenceUUID, com.orientechnologies.orient.core.record.ODirection direction, boolean polymorphic, Map<String,String> constraint) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Low-level query execution method that runs the graph traversal query on OrientDB and returns the matching entities as a serialized JSON array string.
      Parameters:
      relationType - the relationship class name to traverse
      referenceType - the target entity class name
      referenceUUID - the target entity UUID (optional)
      direction - the traversal direction (IN/OUT)
      polymorphic - whether to include subclasses of the target entity
      constraint - map of additional property constraints
      Returns:
      JSON array string of matching entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database, query, or serialization failure

    • query

      public String query(String relationType, String referenceType, UUID referenceUUID, com.orientechnologies.orient.core.record.ODirection direction, boolean polymorphic, Map<String,String> constraint) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      High-level query execution method that manages its own database session, performs schema validations, and delegates traversal execution to reallyQuery(java.lang.String, java.lang.String, java.util.UUID, com.orientechnologies.orient.core.record.ODirection, boolean, java.util.Map<java.lang.String, java.lang.String>).
      Parameters:
      relationType - the relationship class name to traverse
      referenceType - the target entity class name
      referenceUUID - the target entity UUID (optional)
      direction - the traversal direction (IN/OUT)
      polymorphic - whether to include subclasses of the target entity
      constraint - map of additional property constraints
      Returns:
      JSON array string of matching entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if parameters are invalid or execution fails