Package org.gcube.informationsystem.resourceregistry.environments

Class HierarchicalEnvironment

java.lang.Object
org.gcube.informationsystem.resourceregistry.environments.Environment
org.gcube.informationsystem.resourceregistry.environments.HierarchicalEnvironment
Direct Known Subclasses:
HierarchicalContextEnvironment, HierarchicalInstanceEnvironment
public abstract class HierarchicalEnvironment extends Environment
Author:
Luca Frosini (ISTI - CNR) Base class for all environments which have a hierarchy. An example is InstanceEnvironment where the instances belonging to a context must be visible from parent context if the requesting client has enough privileges

  • Field Details

    • H

      public static final String H
      The hierarchical indicator suffix used in role or user name construction.
      See Also:

    • HA

      public static final String HA
      Prefix for the "Hierarchical Active-only" reader channel: a second, parallel hierarchical-reader role/user pair, independent of H, used only by non-administrative hierarchical instance reads. Unlike H (which always sees every descendant regardless of effectiveState, and is what administrative roles keep using unchanged), an environment's HAReaderRole_<uuid> is granted to its ancestors' HAReaderUser_<uuid> only while its own effectiveState is ACTIVE, and revoked while it is not - see ContextManagement.recomputeSubtreeDerivedFieldsSinglePass() for the trigger. Reader-only: there is no HAWriterRole/HAWriterUser, since hierarchical writes into a non-ACTIVE descendant are already rejected outright for non-administrative roles by an existing, separate check, with no "silently hide" equivalent needed for writes.
      See Also:

    • hierarchicalMode

      protected boolean hierarchicalMode
      Flag indicating if hierarchical mode is active for the current request context.

    • activeOnlyHierarchicalMode

      protected boolean activeOnlyHierarchicalMode
      Flag indicating that, while in hierarchical mode, the HA (active-only) reader channel must be used instead of the unrestricted H channel. Meaningless unless hierarchicalMode is also true; ignored for WRITER connections (no active-only writer channel exists). Set by the PEP layer based on caller role: every ALL_ADMIN_ROLES holder keeps using the unrestricted H channel (unchanged behavior); every other role uses this one.

    • parentEnvironment

      protected HierarchicalEnvironment parentEnvironment
      The parent environment in the hierarchy.

    • children

      protected Set<HierarchicalEnvironment> children
      The set of child environments in the hierarchy.

  • Constructor Details

    • HierarchicalEnvironment

      public HierarchicalEnvironment(UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new HierarchicalEnvironment instance.
      Parameters:
      uuid - the context environment UUID
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the environment cannot be initialized

  • Method Details

    • isHierarchicalMode

      public boolean isHierarchicalMode()
      Returns whether hierarchical mode is active.
      Returns:
      true if hierarchical mode is active, false otherwise

    • setHierarchicalMode

      public void setHierarchicalMode(boolean hierarchicalMode)
      Sets whether hierarchical mode is active.
      Parameters:
      hierarchicalMode - true to enable hierarchical mode, false to disable it

    • isActiveOnlyHierarchicalMode

      public boolean isActiveOnlyHierarchicalMode()
      Returns whether the active-only (HA) hierarchical reader channel must be used instead of the unrestricted H channel.
      Returns:
      true if the active-only channel must be used, false otherwise

    • setActiveOnlyHierarchicalMode

      public void setActiveOnlyHierarchicalMode(boolean activeOnlyHierarchicalMode)
      Sets whether the active-only (HA) hierarchical reader channel must be used instead of the unrestricted H channel. See the field Javadoc for who should set this and when.
      Parameters:
      activeOnlyHierarchicalMode - true to use the active-only channel

    • setParentEnvironment

      public void setParentEnvironment(HierarchicalEnvironment parentEnvironment)
      Sets the parent environment for this hierarchical context environment.
      Parameters:
      parentEnvironment - the parent environment to set

    • getParentEnvironment

      public HierarchicalEnvironment getParentEnvironment()
      Returns the parent environment in the hierarchy.
      Returns:
      the parent environment, or null if root

    • getChildren

      public Set<HierarchicalEnvironment> getChildren()
      Returns the children environments of this hierarchical environment.
      Returns:
      the set of children

    • changeParentEnvironment

      public void changeParentEnvironment(HierarchicalEnvironment newParentEnvironment, com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Use to change the parent not to set the first time.
      Parameters:
      newParentEnvironment - the new parent environment to transition to
      orientGraph - the active OrientDB database connection
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the parent change or security update fails

    • getPool

      protected com.orientechnologies.orient.core.db.ODatabasePool getPool(Environment.PermissionMode permissionMode, boolean recreate)
      Retrieves or creates a database connection pool for the specified permission mode, distinguishing the hierarchical-mode username from the regular one.

      Delegates to ODatabasePoolManager, for the same reason as Environment.getPool(org.gcube.informationsystem.resourceregistry.environments.Environment.PermissionMode, boolean): this instance may itself be transient, so it must not own the pool's lifecycle.

      Overrides:
      getPool in class Environment
      Parameters:
      permissionMode - the permission mode (READER/WRITER)
      recreate - true to force recreation of the pool
      Returns:
      the connection pool

    • getRoleOrUserName

      public static String getRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType)
      Returns the standard role or user name based on permission mode and security type.
      Parameters:
      permissionMode - the permission mode
      securityType - the security type
      Returns:
      the role or user name string

    • getRoleOrUserName

      public static String getRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType, boolean hierarchic)
      Returns the standard role or user name with optional hierarchical indicator.
      Parameters:
      permissionMode - the permission mode
      securityType - the security type
      hierarchic - true to prepand hierarchical prefix, false otherwise
      Returns:
      the role or user name string

    • getRoleOrUserName

      public static String getRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType, String hierarchicPrefix)
      Returns the standard role or user name with an explicit hierarchical-channel prefix ("" for non-hierarchical, H for the classic hierarchical channel, HA for the active-only hierarchical channel).
      Parameters:
      permissionMode - the permission mode
      securityType - the security type
      hierarchicPrefix - the hierarchical-channel prefix to prepend
      Returns:
      the role or user name string

    • getSecurityRoleOrUserName

      public String getSecurityRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType, boolean hierarchic)
      Returns the context-scoped security role or user name.
      Parameters:
      permissionMode - the permission mode
      securityType - the security type
      hierarchic - true to use hierarchical context, false otherwise
      Returns:
      the context-scoped role or user name string

    • getSecurityRoleOrUserName

      public String getSecurityRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType, String hierarchicPrefix)
      Returns the context-scoped security role or user name for an explicit hierarchical-channel prefix. See getRoleOrUserName(PermissionMode, SecurityType, String).
      Parameters:
      permissionMode - the permission mode
      securityType - the security type
      hierarchicPrefix - the hierarchical-channel prefix to prepend
      Returns:
      the context-scoped role or user name string

    • getOSecurity

      protected com.orientechnologies.orient.core.metadata.security.OSecurity getOSecurity(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Retrieves the security manager associated with the given database document.
      Parameters:
      oDatabaseDocument - the database session document
      Returns:
      the OrientDB security manager

    • getContexts

      public static Set<String> getContexts(com.orientechnologies.orient.core.record.OElement element)
      Returns the set of context UUID strings from the allowed security permissions of the element. A permission whose role or user record no longer exists grants nothing and is skipped: it is left by the deletion of a Context in an older version, whose roles were dropped while the links to them stayed.
      Parameters:
      element - the OrientDB element
      Returns:
      the set of context UUIDs

    • allow

      protected void allow(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument, boolean hierarchic)
      Grants permissions to hierarchical write and read roles on the specified document vertex.
      Parameters:
      oSecurity - the security manager
      oDocument - the document vertex
      hierarchic - true to use hierarchical role scoping, false otherwise

    • allowActiveReader

      protected void allowActiveReader(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
      Grants read access to this environment's own HA (active-only hierarchical reader) role on the specified document vertex. Reader-only, mirroring the read half of allow(OSecurity, ODocument, boolean) - there is no active-only writer channel.
      Parameters:
      oSecurity - the security manager
      oDocument - the document vertex

    • addElement

      public void addElement(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Description copied from class: Environment
      Adds an element to this environment within the specified database transaction.
      Overrides:
      addElement in class Environment
      Parameters:
      element - the element to add
      oDatabaseDocument - the database connection

    • deny

      protected void deny(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument, boolean hierarchical)
      Denies permissions to hierarchical write and read roles on the specified document vertex.
      Parameters:
      oSecurity - the security manager
      oDocument - the document vertex
      hierarchical - true to use hierarchical role scoping, false otherwise

    • denyActiveReader

      protected void denyActiveReader(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
      Denies read access to this environment's own HA role/user on the specified document vertex. Mirrors the read half of deny(OSecurity, ODocument, boolean).
      Parameters:
      oSecurity - the security manager
      oDocument - the document vertex

    • removeElement

      public void removeElement(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Description copied from class: Environment
      Removes an element from this environment within the specified database transaction.
      Overrides:
      removeElement in class Environment
      Parameters:
      element - the element to remove
      oDatabaseDocument - the database connection

    • allowed

      protected boolean allowed(com.orientechnologies.orient.core.metadata.security.ORole role, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
      Description copied from class: Environment
      Returns whether the specified role is allowed to access the document vertex.
      Overrides:
      allowed in class Environment
      Parameters:
      role - the security role to check
      oDocument - the document vertex
      Returns:
      true if the role is allowed, false otherwise

    • addHierarchicalRoleToParent

      protected void addHierarchicalRoleToParent(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Environment.PermissionMode permissionMode, com.orientechnologies.orient.core.metadata.security.ORole... roles)
      Propagates and adds the specified hierarchical roles up to all parent environments.
      Parameters:
      oSecurity - the security manager
      permissionMode - the permission mode (READER/WRITER)
      roles - the roles to propagate

    • grantActiveReaderRoleToAncestors

      public void grantActiveReaderRoleToAncestors(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Public entry point for grantActiveReaderRoleToAncestors(OSecurity), for callers outside this package (e.g. ContextManagement, on an effectiveState transition to ACTIVE) that only have an ODatabaseDocument at hand.
      Parameters:
      oDatabaseDocument - the active OrientDB database connection

    • revokeActiveReaderRoleFromAncestors

      public void revokeActiveReaderRoleFromAncestors(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Public entry point for revokeActiveReaderRoleFromAncestors(OSecurity), for callers outside this package (e.g. ContextManagement, on an effectiveState transition away from ACTIVE) that only have an ODatabaseDocument at hand.
      Parameters:
      oDatabaseDocument - the active OrientDB database connection

    • grantActiveReaderRoleToAncestors

      protected void grantActiveReaderRoleToAncestors(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Grants this environment's own HA reader role to every one of its ancestors' HA reader users, all the way to the root. Called when this environment's own effectiveState transitions to ACTIVE (including the very first such transition, out of the initial CREATED state - see createActiveReaderRoleAndUser(OSecurity)'s Javadoc for why nothing is granted at role-creation time itself).

      A no-op if this environment has no parent (root Context).

      Parameters:
      oSecurity - the OrientDB security manager

    • addActiveReaderRoleToParent

      protected void addActiveReaderRoleToParent(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.metadata.security.ORole activeReaderRole)
      Propagates and adds the specified HA reader role up to this environment and (recursively) all of its own ancestors.
      Parameters:
      oSecurity - the security manager
      activeReaderRole - the HA reader role being propagated (some descendant's own)

    • revokeActiveReaderRoleFromAncestors

      protected void revokeActiveReaderRoleFromAncestors(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Revokes this environment's own HA reader role from every one of its ancestors' HA reader users, all the way to the root. Called when this environment's own effectiveState transitions away from ACTIVE (to SUSPENDED or CREATED).

      A no-op if this environment has no parent (root Context).

      Parameters:
      oSecurity - the OrientDB security manager

    • removeActiveReaderRoleFromMyHAUser

      protected void removeActiveReaderRoleFromMyHAUser(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String activeReaderRoleName)
      Revokes the specified HA reader role name from this environment's own HA reader user, then (recursively) from all of its own ancestors.
      Parameters:
      oSecurity - the security manager
      activeReaderRoleName - the role name being revoked (some descendant's own)

    • createRolesAndUsers

      protected void createRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Creates both the non-hierarchical and the H hierarchical roles/users for this environment, overriding Environment.createRolesAndUsers(OSecurity) to also cover the hierarchical channel. Does not create the HA active-only reader role/user — that channel is created separately, only where it is actually needed, via createActiveReaderRoleAndUser(OSecurity).
      Overrides:
      createRolesAndUsers in class Environment
      Parameters:
      oSecurity - the OrientDB security manager

    • createRolesAndUsers

      protected void createRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, boolean hierarchical)
      Creates OrientDB security roles and users for all permission modes in this environment, optionally generating them in hierarchical context format.
      Parameters:
      oSecurity - the OrientDB security manager
      hierarchical - true to create hierarchical-scoped roles and users, false otherwise

    • createActiveReaderRoleAndUser

      protected void createActiveReaderRoleAndUser(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Creates the HA (active-only hierarchical reader) role and user for this environment, reader-only, with no grant to any ancestor.

      Unlike the H channel, this deliberately does not propagate a grant to the parent environment at creation time - a brand new Context always starts with effectiveState=CREATED (never ACTIVE, see ContextManagement.reallyCreate()), so there is nothing to grant yet. The grant to ancestors is added later, uniformly, the first time (and every subsequent time) this environment's own effectiveState transitions to ACTIVE - see grantActiveReaderRoleToAncestors(OSecurity) and its revoke counterpart, triggered from ContextManagement.recomputeSubtreeDerivedFieldsSinglePass().

      Parameters:
      oSecurity - the OrientDB security manager

    • removeChildrenHRolesFromParents

      protected void removeChildrenHRolesFromParents(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Revokes all hierarchical child roles from all parent database users in the hierarchy.
      Parameters:
      oSecurity - the security manager

    • removeChildrenHRolesFromParents

      protected void removeChildrenHRolesFromParents(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Set<HierarchicalEnvironment> parents, Set<HierarchicalEnvironment> children)
      Revokes the specified list of child roles from the specified list of parent database users.
      Parameters:
      oSecurity - the security manager
      parents - the set of parent environments
      children - the set of child environments

    • removeChildrenHRolesFromMyHUsers

      protected void removeChildrenHRolesFromMyHUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Set<HierarchicalEnvironment> children)
      Revokes child hierarchical roles from the database users of this environment.
      Parameters:
      oSecurity - the security manager
      children - the set of child environments whose roles to revoke

    • removeHierarchicRoleFromMyHUser

      protected void removeHierarchicRoleFromMyHUser(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Environment.PermissionMode permissionMode, String roleName)
      Revokes a specific hierarchical role from the database user of this environment.
      Parameters:
      oSecurity - the security manager
      permissionMode - the permission mode (READER/WRITER)
      roleName - the name of the role to revoke

    • deleteRolesAndUsers

      protected void deleteRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Deletes both the non-hierarchical and the H hierarchical roles/users for this environment, overriding Environment.deleteRolesAndUsers(OSecurity). Before dropping the hierarchical roles/users themselves, first revokes this environment's own children's hierarchical roles from every ancestor's hierarchical user, via removeChildrenHRolesFromParents(OSecurity). Does not touch the HA active-only reader role/user.
      Overrides:
      deleteRolesAndUsers in class Environment
      Parameters:
      oSecurity - the OrientDB security manager