Package org.gcube.informationsystem.resourceregistry.environments

Class Environment

java.lang.Object
org.gcube.informationsystem.resourceregistry.environments.Environment
Direct Known Subclasses:
HierarchicalEnvironment, SystemEnvironment
public abstract class Environment extends Object
Author:
Luca Frosini (ISTI - CNR) Base class for any environment. In the current implementation it represents a portion of a graph which in OrientDB is implemented via security.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Environment.PermissionMode
    Defines database transaction permission level modes (Reader or Writer).
    static enum 
    Environment.SecurityType
    Defines OrientDB security artifact categories (Role or User).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static Set<String>
    allOperationAllowedRoles
    Infrastructure-wide roles that are allowed to perform any administrative operation regardless of the context from which the request is issued ("Infrastructure-Manager", "IS-Manager").
    static final String
    CONTEXT_MANAGER
    Role constant representing the Context-Manager role.
    protected static Set<String>
    contextSubtreeOperationAllowedRoles
    Roles allowed to manage contexts within the subtree of a context (create, activate, delete child contexts).
    protected static final String
    DEFAULT_READER_ROLE
    The default reader role name.
    protected static final String
    DEFAULT_WRITER_ROLE
    The default writer role name.
    protected final UUID
    environmentUUID
    The unique UUID identifier of this environment partition.
    static final String
    INFRASTRUCTURE_MANAGER
    Role constant representing the Infrastructure-Manager role.
    protected static Set<String>
    instanceOperationAllowedRoles
    Roles allowed to perform instance-level operations (read, create, update, delete instances; add/remove instances to/from child contexts; run query templates; use hierarchical mode) within the subtree of a context.
    static final String
    IS_ADMIN
    Role constant representing the IS-Admin role.
    static final String
    IS_INSTANCE_OPERATOR
    Placeholder role name for a lighter context-scoped role that can manage instances and sharing within a context subtree but cannot create, activate or delete child contexts.
    static final String
    IS_MANAGER
    Role constant representing the IS-Manager role.
    protected static Set<String>
    stateOverrideAllowedRoles
    Roles holding the administrative override of non-ACTIVE Context states: they operate on instances in a created or suspended Context.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Environment(UUID context)
    Creates a new Environment instance bound to the specified context.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addElement(com.orientechnologies.orient.core.record.OElement element)
    Adds an element to this environment, opening an admin database session.
    void
    addElement(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Adds an element to this environment within the specified database transaction.
    protected com.orientechnologies.orient.core.metadata.security.ORole
    addExtraRules(com.orientechnologies.orient.core.metadata.security.ORole role, Environment.PermissionMode permissionMode)
    Adds extra security rules to a role based on the permission mode (hook for subclasses).
    protected void
    allow(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
    Grants read and write roles permission on the specified document vertex.
    protected boolean
    allowed(com.orientechnologies.orient.core.metadata.security.ORole role, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
    Returns whether the specified role is allowed to access the document vertex.
    void
    create()
    Creates the database environment.
    void
    create(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Creates the security roles and users in the specified database document context.
    protected void
    createRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
    Creates OrientDB security roles and users for all permission modes in this environment.
    void
    delete()
    Deletes the database environment and associated security roles and users, opening an admin database session.
    void
    delete(com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph)
    Deletes all security roles and users within the specified database transaction.
    protected void
    deleteRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
    Drops all roles and users for all permission modes in this environment.
    protected void
    deny(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
    Denies read and write permission on the specified document vertex for this environment.
    protected void
    drop(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String name, Environment.SecurityType securityType)
    Drops the specified role or user from the security manager.
    static Set<String>
    getAllOperationsAllowedRoles()
    Returns the set of roles that are allowed to perform any administrative operation regardless of the context from which the request is issued.
    static Set<String>
    getAllowedRoles()
    Returns the set of roles allowed to perform administrative operations within the subtree of a context (context management: create, activate, delete child contexts).
    com.orientechnologies.orient.core.db.document.ODatabaseDocument
    getDatabaseDocument(Environment.PermissionMode permissionMode)
    Acquires and returns an active, thread-local database session for the specified permission mode.
    static Set<String>
    getInstanceOperationAllowedRoles()
    Returns the set of roles allowed to perform instance-level operations: read/write instances, sharing (add/remove to child contexts), query execution, hierarchical mode, and query template runs.
    protected com.orientechnologies.orient.core.metadata.security.ORole
    getOrCreateRole(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String roleName, Environment.PermissionMode permissionMode)
    Returns the role with the given name, creating it when missing, with this environment's extra rules applied either way (adding a rule it already has changes nothing).
    protected com.orientechnologies.orient.core.metadata.security.OUser
    getOrCreateUser(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String userName, Environment.PermissionMode permissionMode, com.orientechnologies.orient.core.metadata.security.ORole role)
    Returns the user with the given name, creating it with the given role when missing, and granting it that role when it exists without it.
    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.
    static String
    getRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType)
    Returns the standard role or user name based on permission mode and security type.
    String
    getSecurityRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType)
    Returns the context-scoped security role or user name.
    static Set<String>
    getStateOverrideAllowedRoles()
    Returns the set of roles allowed to operate on instances in a Context whose effectiveState is not ACTIVE: the global managers, "IS-Admin", and "Context-Manager".
    protected com.orientechnologies.orient.core.metadata.security.ORole
    getSuperRole(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Environment.PermissionMode permissionMode)
    Retrieves the super role from the database security context.
    UUID
    getUUID()
    Returns the UUID of this environment.
    boolean
    isElementInContext(com.orientechnologies.orient.core.record.OElement element)
    Returns whether the specified element belongs to this context.
    static boolean
    isUserAllowed(Collection<String> allowedRoles)
    Checks whether the caller holds at least one of the specified roles.
    void
    removeElement(com.orientechnologies.orient.core.record.OElement element)
    Removes an element from this environment.
    void
    removeElement(com.orientechnologies.orient.core.record.OElement element, com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Removes an element from this environment within the specified database transaction.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_WRITER_ROLE

      protected static final String DEFAULT_WRITER_ROLE
      The default writer role name.
      See Also:

    • DEFAULT_READER_ROLE

      protected static final String DEFAULT_READER_ROLE
      The default reader role name.
      See Also:

    • environmentUUID

      protected final UUID environmentUUID
      The unique UUID identifier of this environment partition.

    • allOperationAllowedRoles

      protected static Set<String> allOperationAllowedRoles
      Infrastructure-wide roles that are allowed to perform any administrative operation regardless of the context from which the request is issued ("Infrastructure-Manager", "IS-Manager").

      These are realm roles in the JWT token: they are not bound to any specific context and are always present in the token regardless of the context for which the token was issued. This means a holder of one of these roles can perform any operation — including managing contexts, managing types, creating query templates, and adding/removing instances to/from any context — using a token issued for any context, even one outside the subtree being operated on (e.g. moving an instance from a context to a sibling, or from a child of a sibling).

    • contextSubtreeOperationAllowedRoles

      protected static Set<String> contextSubtreeOperationAllowedRoles
      Roles allowed to manage contexts within the subtree of a context (create, activate, delete child contexts). This set extends allOperationAllowedRoles by additionally including the context-scoped "Context-Manager" role.

      "IS-Instance-Operator" is intentionally excluded from this set: the key distinction between "Context-Manager" and "IS-Instance-Operator" is that the latter cannot manage contexts.

      Token-context constraint for "Context-Manager"

      "Context-Manager" is a resource access role in the JWT token: it is bound to the specific context for which the token was issued. All operations performed by a "Context-Manager" must use a token issued for the context in which they hold the role (their "managed context"). The token context determines the boundary of their authority.

      What "Context-Manager" CAN do (using a token of their managed context):

      • Read instances belonging to their managed context and all descendant contexts.
      • Create, activate, and delete child contexts (contexts nested directly below their managed context), by presenting a token issued for the managed context (i.e. the parent of the contexts being managed).
      • Add or remove instances to/from child (or deeper descendant) contexts. The addToContext / removeFromContext operation is always issued from the caller's current token context toward a target context; a "Context-Manager" may therefore target any context that is a strict descendant of their managed context.

      What "Context-Manager" CANNOT do:

      • Manage types — type management is a global operation reserved to allOperationAllowedRoles ("Infrastructure-Manager", "IS-Manager").
      • Create or manage query templates — also a global operation.
      • Manage (create/delete/activate) their own managed context — that operation must be performed by the manager of the parent context (or by a global admin role).
      • Add/remove instances to/from their managed context itself or to contexts outside their subtree — the target context must be a strict descendant of the managed context.

      Holders of allOperationAllowedRoles ("Infrastructure-Manager", "IS-Manager") are not subject to these constraints: they may perform any operation using a token issued for any context, even one that is not in the same subtree as the resources being operated on.

    • instanceOperationAllowedRoles

      protected static Set<String> instanceOperationAllowedRoles
      Roles allowed to perform instance-level operations (read, create, update, delete instances; add/remove instances to/from child contexts; run query templates; use hierarchical mode) within the subtree of a context.

      This set extends contextSubtreeOperationAllowedRoles by additionally including the "IS-Instance-Operator" role. The key distinction between this set and contextSubtreeOperationAllowedRoles is that "IS-Instance-Operator" holders cannot create, activate or delete contexts — they can only operate on instances and relations.

      Use this set when checking authorisation for instance reads/writes, sharing operations, query execution, hierarchical mode, and query template runs.

      Use contextSubtreeOperationAllowedRoles when checking authorisation for context management (create, changeState, delete).

    • stateOverrideAllowedRoles

      protected static Set<String> stateOverrideAllowedRoles
      Roles holding the administrative override of non-ACTIVE Context states: they operate on instances in a created or suspended Context. These are the global managers, "IS-Admin", and "Context-Manager".

    • INFRASTRUCTURE_MANAGER

      public static final String INFRASTRUCTURE_MANAGER
      Role constant representing the Infrastructure-Manager role.
      See Also:

    • IS_MANAGER

      public static final String IS_MANAGER
      Role constant representing the IS-Manager role.
      See Also:

    • IS_ADMIN

      public static final String IS_ADMIN
      Role constant representing the IS-Admin role.
      See Also:

    • CONTEXT_MANAGER

      public static final String CONTEXT_MANAGER
      Role constant representing the Context-Manager role.
      See Also:

    • IS_INSTANCE_OPERATOR

      public static final String IS_INSTANCE_OPERATOR
      Placeholder role name for a lighter context-scoped role that can manage instances and sharing within a context subtree but cannot create, activate or delete child contexts.

      Note: this role is not yet implemented. The name is provisional and subject to change.

      See Also:

  • Constructor Details

    • Environment

      protected Environment(UUID context)
      Creates a new Environment instance bound to the specified context.
      Parameters:
      context - the UUID of the context

  • Method Details

    • getAllOperationsAllowedRoles

      public static Set<String> getAllOperationsAllowedRoles()
      Returns the set of roles that are allowed to perform any administrative operation regardless of the context from which the request is issued. These are infrastructure-wide, globally-privileged roles: "IS-Manager" and "Infrastructure-Manager".

      In the JWT token these roles are carried as realm roles, meaning they are not bound to any specific context and are always present regardless of the context for which the token was issued.

      Returns:
      a new mutable copy of the globally-privileged role set

    • getAllowedRoles

      public static Set<String> getAllowedRoles()
      Returns the set of roles allowed to perform administrative operations within the subtree of a context (context management: create, activate, delete child contexts). This set extends getAllOperationsAllowedRoles() by including the context-scoped "Context-Manager" role. "IS-Instance-Operator" is intentionally excluded — it cannot manage contexts.

      See contextSubtreeOperationAllowedRoles for a full description of what "Context-Manager" can and cannot do.

      Returns:
      a new mutable copy of the context-subtree allowed role set

    • getStateOverrideAllowedRoles

      public static Set<String> getStateOverrideAllowedRoles()
      Returns the set of roles allowed to operate on instances in a Context whose effectiveState is not ACTIVE: the global managers, "IS-Admin", and "Context-Manager".
      Returns:
      a new mutable copy of the state-override role set

    • getInstanceOperationAllowedRoles

      public static Set<String> getInstanceOperationAllowedRoles()
      Returns the set of roles allowed to perform instance-level operations: read/write instances, sharing (add/remove to child contexts), query execution, hierarchical mode, and query template runs.

      This is the widest context-scoped role set. It extends getAllowedRoles() by additionally including "IS-Instance-Operator".

      Use this set for authorisation checks on instance endpoints, sharing endpoints, query endpoints, and hierarchical mode.

      Use getAllowedRoles() for context management checks.

      Returns:
      a new mutable copy of the instance-operation allowed role set

    • 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.

      Delegates to ODatabasePoolManager, which shares one pool per connection username across every Environment instance, rather than owning a pool per instance — this instance may itself be transient (recreated per resolution), so it must not be the thing that owns the pool's lifecycle.

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

    • getUUID

      public UUID getUUID()
      Returns the UUID of this environment.
      Returns:
      the environment UUID

    • 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 (ROLE/USER)
      Returns:
      the role or user name string

    • getSecurityRoleOrUserName

      public String getSecurityRoleOrUserName(Environment.PermissionMode permissionMode, Environment.SecurityType securityType)
      Returns the context-scoped security role or user name.
      Parameters:
      permissionMode - the permission mode
      securityType - the security type (ROLE/USER)
      Returns:
      the context-scoped role or user name string

    • addElement

      public void addElement(com.orientechnologies.orient.core.record.OElement element) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Adds an element to this environment, opening an admin database session.
      Parameters:
      element - the element to add
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the operation fails

    • allow

      protected void allow(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
      Grants read and write roles permission on the specified document vertex.
      Parameters:
      oSecurity - the security manager
      oDocument - the document vertex

    • isElementInContext

      public boolean isElementInContext(com.orientechnologies.orient.core.record.OElement element) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns whether the specified element belongs to this context.
      Parameters:
      element - the element to check
      Returns:
      true if the element belongs to this context, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if database lookup fails

    • addElement

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

    • removeElement

      public void removeElement(com.orientechnologies.orient.core.record.OElement element) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Removes an element from this environment.
      Parameters:
      element - the element to remove
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the operation fails

    • deny

      protected void deny(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, com.orientechnologies.orient.core.record.impl.ODocument oDocument)
      Denies read and write permission on the specified document vertex for this environment.
      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)
      Removes an element from this environment within the specified database transaction.
      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)
      Returns whether the specified role is allowed to access the document vertex.
      Parameters:
      role - the security role to check
      oDocument - the document vertex
      Returns:
      true if the role is allowed, false otherwise

    • isUserAllowed

      public static boolean isUserAllowed(Collection<String> allowedRoles)
      Checks whether the caller holds at least one of the specified roles.

      The check is performed against the full set of roles carried by the caller's token, which includes both context-scoped roles (resource access roles, e.g. "Context-Manager") and infrastructure-wide realm roles (e.g. "IS-Manager", "Infrastructure-Manager"), regardless of their origin.

      Parameters:
      allowedRoles - the set of roles to check against
      Returns:
      true if the caller holds at least one of the specified roles, false otherwise

    • create

      public void create() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates the database environment.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if creation fails

    • addExtraRules

      protected com.orientechnologies.orient.core.metadata.security.ORole addExtraRules(com.orientechnologies.orient.core.metadata.security.ORole role, Environment.PermissionMode permissionMode)
      Adds extra security rules to a role based on the permission mode (hook for subclasses).
      Parameters:
      role - the role to modify
      permissionMode - the permission mode defining the type of access
      Returns:
      the modified role

    • getSuperRole

      protected com.orientechnologies.orient.core.metadata.security.ORole getSuperRole(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, Environment.PermissionMode permissionMode)
      Retrieves the super role from the database security context.
      Parameters:
      oSecurity - the OrientDB security context
      permissionMode - the permission mode (reader/writer)
      Returns:
      the matching OrientDB role

    • createRolesAndUsers

      protected void createRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Creates OrientDB security roles and users for all permission modes in this environment. Existing ones are kept and realigned, so that creating an environment again is harmless.
      Parameters:
      oSecurity - the security manager

    • getOrCreateRole

      protected com.orientechnologies.orient.core.metadata.security.ORole getOrCreateRole(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String roleName, Environment.PermissionMode permissionMode)
      Returns the role with the given name, creating it when missing, with this environment's extra rules applied either way (adding a rule it already has changes nothing).
      Parameters:
      oSecurity - the security manager
      roleName - the role name
      permissionMode - the permission mode the role grants
      Returns:
      the role

    • getOrCreateUser

      protected com.orientechnologies.orient.core.metadata.security.OUser getOrCreateUser(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String userName, Environment.PermissionMode permissionMode, com.orientechnologies.orient.core.metadata.security.ORole role)
      Returns the user with the given name, creating it with the given role when missing, and granting it that role when it exists without it.
      Parameters:
      oSecurity - the security manager
      userName - the user name
      permissionMode - the permission mode, which decides the default password
      role - the role the user holds
      Returns:
      the user

    • create

      public void create(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Creates the security roles and users in the specified database document context.
      Parameters:
      oDatabaseDocument - the database document connection

    • drop

      protected void drop(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity, String name, Environment.SecurityType securityType)
      Drops the specified role or user from the security manager.
      Parameters:
      oSecurity - the security manager
      name - the role or user name to drop
      securityType - the security type (ROLE/USER)

    • delete

      public void delete() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes the database environment and associated security roles and users, opening an admin database session.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if deletion fails

    • deleteRolesAndUsers

      protected void deleteRolesAndUsers(com.orientechnologies.orient.core.metadata.security.OSecurity oSecurity)
      Drops all roles and users for all permission modes in this environment.
      Parameters:
      oSecurity - the security manager

    • delete

      public void delete(com.orientechnologies.orient.core.db.document.ODatabaseDocument orientGraph)
      Deletes all security roles and users within the specified database transaction.
      Parameters:
      orientGraph - the database document connection

    • getDatabaseDocument

      public com.orientechnologies.orient.core.db.document.ODatabaseDocument getDatabaseDocument(Environment.PermissionMode permissionMode) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Acquires and returns an active, thread-local database session for the specified permission mode.
      Parameters:
      permissionMode - the permission mode (READER/WRITER)
      Returns:
      the acquired database session
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the connection cannot be established

    • toString

      public String toString()
      Overrides:
      toString in class Object