Package de.aristaflow.adept2.core.orgmodelmanager

Interface ModelChangeOperations

  • public interface ModelChangeOperations
    The ModelChangeOperations provide methods to alter the OrgModel (add and delete attributes), add/delete entities, change their attributes and add/delete relations between entities.

    IDs of created entities must start with 1! IDs <= 0 are reserved for special (e.g. system-internal) purposes.

    • Method Detail

      • getPasswordQuality

        Pair<PasswordStrength.PasswordQuality,​PasswordStrength> getPasswordQuality​(SessionToken session,
                                                                                 String password,
                                                                                 Collection<String> blacklist,
                                                                                 Locale locale)
        Gets the quality of the designated password, that is, whether the password will be accepted when creating or updating it for an entity.
        Parameters:
        session - The session which is used to check for access rights on this method and which provides the locale for additional information for PasswordStrength.
        password - The new password which to check for its quality.
        blacklist - The user details like username and email that should not be used as password. Could be null or empty.
        locale - The locale that should be used to localise additional information for PasswordStrength.
        Returns:
        The password quality and optional additional information to the designated password. If no plugin for the password strength has been configured or password strength estimation has been disabled, PasswordStrength.PasswordQuality.ACCEPTED and null will be returned.

      • addAttribute

        void addAttribute​(SessionToken session,
                  EntityType entType,
                  String attrName,
                  DataType dataType,
                  boolean readOnly,
                  Map<String,​String> omExtMapping,
                  Collection<String> writeBackOmExts)
           throws OrgModelException,
                  DataSourceException
        Adds a new attribute with the designated data type to the designated entity type which is being mapped from the designated attributes from the corresponding org model extensions . Use/see OrgModelTools.isValidAttributeName(String) to find out whether a string is a valid attribute name if you're not sure.

        DataType.NULL is not allowed as the data type of an attribute!

        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - The entity type to which the attribute should be added.
        attrName - The unique (with respect to the entity type) name of the new attribute. This must not contain "_".
        dataType - The data type of the attribute to be added.
        readOnly - Whether the new attribute should be globally read-only, i. e. for all OM extensions.
        omExtMapping - The name of the org model extensions and the corresponding attribute names which the new attribute is mapped in priority order, higher priority first. This may be null.
        writeBackOmExts - The OM extension names (of the designated OM extensions) for which the attribute value should be written back when changed by the system (but not from another OM extension). If this is null, the attribute will not be written back for all of the designated OM extensions. Use omExtMapping.keySet() to make the attribute written back for all OM extensions.
        Throws:
        IllegalArgumentException - If the designated data type is DataType.NULL or the attribute name is invalid, an IllegalArgumentException will be thrown.
        OrgModelException - If an attribute of the designated name already exists, an OrgModelException will be thrown.
        DataSourceException - If there are unrecoverable problems accessing the data source, a DataSourceException will be thrown.

      • addStringAttribute

        void addStringAttribute​(SessionToken session,
                        EntityType entType,
                        String attrName,
                        int sizeHint,
                        boolean readOnly,
                        Map<String,​String> omExtMapping,
                        Collection<String> writeBackOmExts)
                 throws OrgModelException,
                        DataSourceException
        Adds a new DataType.STRING attribute of the designated size to the designated entity type which is being mapped from the designated attributes from the corresponding org model extensions . Use/see OrgModelTools.isValidAttributeName(String) to find out whether a string is a valid attribute name if you are not sure.

        DataType.NULL is not allowed as the data type of an attribute!

        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - The entity type to which the attribute should be added.
        attrName - The unique (with respect to the entity type) name of the new attribute. This must not contain "_".
        sizeHint - The desired size of the string.
        readOnly - Whether the new attribute should be globally read-only, i. e. for all OM extensions.
        omExtMapping - The name of the org model extensions and the corresponding attribute names which the new attribute is mapped in priority order, higher priority first. This may be null.
        writeBackOmExts - The OM extension names (of the designated OM extensions) for which the attribute value should be written back when changed by the system (but not from another OM extension). If this is null, the attribute will not be written back for all of the designated OM extensions. Use omExtMapping.keySet() to make the attribute written back for all OM extensions.
        Throws:
        IllegalArgumentException - If the designated attribute name is invalid or there is a mapping for a data type other than integer or string, an IllegalArgumentException will be thrown.
        OrgModelException - If an attribute of the designated name already exists, an OrgModelException will be thrown.
        DataSourceException - If there are unrecoverable problems accessing the data source, a DataSourceException will be thrown.

      • modifyAttribute

        @Deprecated(since="13.0.0",
            forRemoval=true)
void modifyAttribute​(SessionToken session,
                     EntityType entType,
                     String attrName,
                     String mappedTo,
                     boolean isImported,
                     boolean isReadOnly)
              throws OrgModelException,
                     DataSourceException
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use modifyAttribute(SessionToken, EntityType, String, Boolean, Map, Collection) instead.
        Changes the mapping properties of the specified attribute.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - the entity type to which the attribute belongs
        attrName - the name of the attribute to be edited
        mappedTo - the name of the mapped attribute in LDAP or null
        isImported - if the mapped attribute should be imported in the OM
        isReadOnly - if the mapped attribute should be read-only
        Throws:
        OrgModelException - when the attribute doesn't exist or the attribute is mandatory
        DataSourceException - when an unrecoverable error occurs while accessing the data source

      • modifyAttribute

        @Deprecated(since="13.0.0",
            forRemoval=true)
void modifyAttribute​(SessionToken session,
                     EntityType entType,
                     String attrName,
                     String omExt,
                     String mappedTo,
                     boolean isImported,
                     boolean isReadOnly)
              throws OrgModelException,
                     DataSourceException
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use modifyAttribute(SessionToken, EntityType, String, Boolean, Map, Collection) instead.
        Changes the mapping properties of the specified attribute including the org model extension.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - the entity type to which the attribute belongs
        attrName - the name of the attribute to be edited. This must not be null and it has to exist.
        omExt - The name of the org model extension from which to map the designated attribute or null to remove the mapping. model extension or null to remove the mapping.
        mappedTo - The name of the mapped attribute in the designated org model extension or null to remove the mapping.
        isImported - if the mapped attribute should be imported in the OM
        isReadOnly - if the mapped attribute should be read-only
        Throws:
        OrgModelException - when the attribute doesn't exist or the attribute is mandatory
        DataSourceException - when an unrecoverable error occurs while accessing the data source

      • modifyAttribute

        void modifyAttribute​(SessionToken session,
                     EntityType entType,
                     String attrName,
                     Boolean readOnly,
                     Map<String,​String> omExtMapping,
                     Collection<String> writeBackOmExts)
              throws OrgModelException,
                     DataSourceException
        Changes the mapping properties and the read-only status of the designated attribute.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - The entity type of which the attribute should be changed.
        attrName - The unique (with respect to the entity type) name of the attribute.
        readOnly - Whether the attribute should be globally read-only, i. e. for all OM extensions. Use null to not change the read-only status.
        omExtMapping - The name of (all) the org model extensions and the corresponding attribute names which the new attribute is mapped in priority order, higher priority first. null does not change the existing mapping, an empty map will remove the existing mapping.
        writeBackOmExts - The OM extension names (of the designated OM extensions) for which the attribute value should be written back when changed by the system (but not from another OM extension). If this is null, writing back will not change. Use an empty collection to disable writing back and omExtMapping.keySet() to make the attribute written back for all OM extensions.
        Throws:
        IllegalArgumentException - If the data type of the designated attribute is DataType.FLOAT or DataType.TIMESTAMP, an IllegalArgumentException will be thrown.
        OrgModelException - If the designated attribute does not exist or is mandatory, an OrgModelException will be thrown.
        DataSourceException - If there are unrecoverable problems accessing the data source, a DataSourceException will be thrown.

      • modifyAttribute

        void modifyAttribute​(SessionToken session,
                     EntityType entType,
                     String attrName,
                     Boolean readOnly,
                     Map<String,​Pair<String,​Boolean>> omExtMapping)
              throws OrgModelException,
                     DataSourceException
        Changes the mapping properties and the read-only status of the designated attribute.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - The entity type of which the attribute should be changed.
        attrName - The unique (with respect to the entity type) name of the attribute.
        readOnly - Whether the attribute should be globally read-only, i. e. for all OM extensions. Use null to not change the read-only status.
        omExtMapping - The name of (all) the org model extensions and the corresponding attribute names which the new attribute is mapped in priority order, higher priority first. null does not change the existing mapping, an empty map will remove the existing mapping. The Boolean specifies whether to write the attribute value back to the corresponding OM extension when changed by the system (but not from another OM extension). Use null to keep the current write back status of an existing mapping; in case of a new mapping Boolean.FALSE will be expected.
        Throws:
        IllegalArgumentException - If the data type of the designated attribute is DataType.FLOAT or DataType.TIMESTAMP, an IllegalArgumentException will be thrown.
        OrgModelException - If the designated attribute does not exist or is mandatory, an OrgModelException will be thrown.
        DataSourceException - If there are unrecoverable problems accessing the data source, a DataSourceException will be thrown.

      • createEntity

        long createEntity​(SessionToken session,
                  Entity entity)
           throws OrgModelException,
                  PasswordPolicyException,
                  DataSourceException
        Creates a new entity with the type and attribute values provided in the given Entity object and returns the assigned ID. All other attributes are set to null. An exception is the Agent entity: userName and password will receive a random value, therefore createAgent(SessionToken, String, String) is the preferred way to add new agents to the system. read-only attributes (other than user name and password) are simply ignored.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entity - the entity object containing the desired attribute values for the new entity
        Returns:
        the ID of the newly created entity
        Throws:
        OrgModelException - when one of the attributes doesn't exist or the value object doesn't have a data type that's compatible to the attribute's data type
        PasswordPolicyException - If the designated entity is an agent with a password and this password is too weak, a PasswordPolicyException will be thrown.
        DataSourceException - when an unrecoverable error occurs while accessing the data source
        See Also:
        #getPasswordQuality(SessionToken, String)

      • updateEntity

        void updateEntity​(SessionToken session,
                  Entity entity)
           throws OrgModelException,
                  PasswordPolicyException,
                  DataSourceException
        Updates an entity with the attribute values provided in the given Entity object. The entity to be updated is determined by the attribute id of the data type DataType.INTEGER which must be set within the Entity object.
        Parameters:
        session - The session which is used to check for access rights on this method.
        entity - contains the ID of the entity to be updated and the attribute values it should be updated with
        Throws:
        OrgModelException - when no entity with the given ID exists, one of the attributes doesn't exist or the value object doesn't have a data type that's compatible to the attribute's data type
        PasswordPolicyException - If the designated entity is an agent with a new password and this password is too weak, a PasswordPolicyException will be thrown.
        DataSourceException - when an unrecoverable error occurs while accessing the data source
        See Also:
        #getPasswordQuality(SessionToken, String)

      • deleteEntity

        void deleteEntity​(SessionToken session,
                  EntityType entType,
                  long id)
           throws OrgModelException,
                  DataSourceException
        This method deletes the entity with the given ID of the given type. Only the entity and its relations will be deleted and no other entity it is related with! This method is equivalent to calling deleteEntity(entType, id, false).
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - the type of the entity to be deleted
        id - the ID of the entity to be deleted
        Throws:
        OrgModelException - when no entity with this ID exists
        DataSourceException - when an unrecoverable error occurs while accessing the data source

      • deleteEntity

        void deleteEntity​(SessionToken session,
                  EntityType entType,
                  long id,
                  boolean recursive)
           throws OrgModelException,
                  DataSourceException
        This method deletes the entity with the given ID of the given type and all its relations. When an OrgPosition or Role is deleted their associated SubstitutionRules will be deleted too (This is mostly a consequence of some SQL related restrictions on SQL constraints).

        If the boolean parameter is true not only the entity will be deleted but also every other entity that in some way depends on it:

        • hierarchical structures: OrgUnits, ProjectGroups and Roles
        • for OrgUnits even their associated OrgPositions will be deleted
        Parameters:
        session - The session which is used to check for access rights on this method.
        entType - the type of the entity to be deleted
        id - the ID of the entity to be deleted
        recursive -
        Throws:
        OrgModelException - when no entity with this ID exists
        DataSourceException - when an unrecoverable error occurs while accessing the data source

      • addRelation

        void addRelation​(SessionToken session,
                 RelationType relType,
                 long id1,
                 long id2)
          throws OrgModelException,
                 DataSourceException
        This method adds a relation of the given type between the two entities identified by the given IDs.

        As both IDs are simple longs, you have to pay extra attention to their order. The following table will show you the required order for each relation type. See RelationType for information about why they are ordered like that.

        The entity types of the referenced IDs of a relation
        RelationType id1 id2
        OrgPositionOccupation (n:m) OrgPosition Agent
        OrgPositionDescription (n:m) OrgPosition Role
        OrgPositionAffiliation (1:m) OrgUnit OrgPosition
        OrgUnitSubordination (1:m) OrgUnit the subordinate OrgUnit (OrgUnit.supId)
        OrgUnitManagement (1:m) the managing OrgPosition OrgUnit (OrgUnit.managerId)
        OrgGroupManagement (1:m) the managing OrgPosition OrgGroup (OrgGroup.managerId)
        OrgGroupInvolvement (n:m) OrgGroup the involved OrgUnit
        ProjectGroupSubordination (1:m) ProjectGroup the subordinate ProjectGroup (ProjectGroup.supId)
        ProjectGroupManagement (1:m) OrgPosition ProjectGroup (ProjectGroup.managerId)
        ProjectInvolvementOrgPosition (n:m) ProjectGroup the involved OrgPosition
        ProjectInvolvementOrgUnit (n:m) ProjectGroup the involved OrgUnit
        AgentAbility (n:m) Agent Ability
        RoleDescription (n:m) Role Ability
        RoleSpecialisation (1:m) the more generic Role the specialised Role (Role.supId)
        OrgPositionSubstitution (1:m) OrgPosition SubstitutionRule
        OrgPositionSubstitute (1:m) the OrgPosition to substitute the other one SubstitutionRule
        RoleSubstitution (1:m) Role SubstitutionRule
        Parameters:
        session - The session which is used to check for access rights on this method.
        relType - the type of the relation to be added
        id1 - the ID of the first entity (see table)
        id2 - the ID of the second entity (see table)
        Throws:
        OrgModelException - when one of the entities does not exist, this exact relation already exists, the second entity already is in a relation and can only be in one (this is the case for 1:n relation types), the relation would create a cycle or it was tried to substitute an OrgPosition for itself in a SubstitutionRule
        DataSourceException - when an unrecoverable error occurs while accessing the data source

      • deleteRelation

        void deleteRelation​(SessionToken session,
                    RelationType relType,
                    long id1,
                    long id2)
             throws OrgModelException,
                    DataSourceException
        This method deletes a relation of the given type between the two entities identified by the given IDs.

        As both IDs are simple longs, you have to pay extra attention to their order. See addRelation(SessionToken, RelationType, long, long) for more information.

        Parameters:
        session - The session which is used to check for access rights on this method.
        relType - the type of the relation to be removed
        id1 - the ID of the first entity (see table)
        id2 - the ID of the second entity (see table)
        Throws:
        OrgModelException - when one of the entities does not exist or this exact relation does not exist
        DataSourceException - when an unrecoverable error occurs while accessing the data source