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.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
void	addAttribute(SessionToken session, EntityType entType, java.lang.String attrName, DataType dataType) Adds a new attribute with the given data type to the given entity type.
void	addAttribute(SessionToken session, EntityType entType, java.lang.String attrName, DataType dataType, int sizeHint) Adds a new attribute with the given data type to the given entity type.
void	addAttribute(SessionToken session, EntityType entType, java.lang.String attrName, DataType dataType, int sizeHint, java.lang.String omExtension, java.lang.String mappedTo, boolean isImported, boolean isReadOnly) Adds a new attribute with the given data type to the given entity type which is being mapped from the designated org model extension.
void	addAttribute(SessionToken session, EntityType entType, java.lang.String attrName, DataType dataType, java.lang.String omExtension, java.lang.String mappedTo, boolean isImported, boolean isReadOnly) Adds a new attribute with the given data type to the given entity type which is being mapped from the designated org model extension.
void	addRelation(SessionToken session, RelationType relType, long id1, long id2) This method adds a relation of the given type between the two entities identified by the given IDs.
long	createAgent(SessionToken session, java.lang.String agentUserName, java.lang.String password) Adds a new Agent with the given (unique!)
long	createEntity(SessionToken session, Entity entity) Creates a new entity with the type and attribute values provided in the given Entity object and returns the assigned ID.
void	deleteAttribute(SessionToken session, EntityType entType, java.lang.String attrName) This method removes an attribute from an entity type.
void	deleteEntity(SessionToken session, EntityType entType, long id) This method deletes the entity with the given ID of the given type.
void	deleteEntity(SessionToken session, EntityType entType, long id, boolean recursive) This method deletes the entity with the given ID of the given type and all its relations.
void	deleteRelation(SessionToken session, RelationType relType, long id1, long id2) This method deletes a relation of the given type between the two entities identified by the given IDs.
void	modifyAttribute(SessionToken session, EntityType entType, java.lang.String attrName, java.lang.String mappedTo, boolean isImported, boolean isReadOnly) Changes the mapping properties of the specified attribute.
void	modifyAttribute(SessionToken session, EntityType entType, java.lang.String attrName, java.lang.String omExt, java.lang.String mappedTo, boolean isImported, boolean isReadOnly) Changes the mapping properties of the specified attribute including the org model extension.
void	updateEntity(SessionToken session, Entity entity) Updates an entity with the attribute values provided in the given Entity object.

Method Detail

addAttribute

void addAttribute(SessionToken session,
                  EntityType entType,
                  java.lang.String attrName,
                  DataType dataType)
           throws OrgModelException,
                  DataSourceException

Adds a new attribute with the given data type to the given entity type. 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 name of the new attribute

dataType - the data type of the attribute to be added

Throws:

java.lang.IllegalArgumentException - when DataType.NULL is used as data type or the attribute name isn't valid

OrgModelException - when the attribute already exists

DataSourceException - when an unrecoverable error occurs while accessing the data source

addAttribute

void addAttribute(SessionToken session,
                  EntityType entType,
                  java.lang.String attrName,
                  DataType dataType,
                  java.lang.String omExtension,
                  java.lang.String mappedTo,
                  boolean isImported,
                  boolean isReadOnly)
           throws OrgModelException,
                  DataSourceException

Adds a new attribute with the given data type to the given entity type which is being mapped from the designated org model extension. 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 name of the new attribute

dataType - the data type of the attribute to be added

omExtension - The name of the org model extension which handles the mapping or null.

mappedTo - The name of the mapped attribute in the designated org model extension.

isImported - if the mapped attribute should be imported in the OM

isReadOnly - if the mapped attribute should be read-only

Throws:

java.lang.IllegalArgumentException - when DataType.NULL is used as data type or the attribute name isn't valid

OrgModelException - when the attribute already exists

DataSourceException - when an unrecoverable error occurs while accessing the data source

addAttribute

void addAttribute(SessionToken session,
                  EntityType entType,
                  java.lang.String attrName,
                  DataType dataType,
                  int sizeHint)
           throws OrgModelException,
                  DataSourceException

Adds a new attribute with the given data type to the given entity type. 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 name of the new attribute

dataType - the data type of the attribute to be added

sizeHint - the desired size (only for STRING attributes)

Throws:

java.lang.IllegalArgumentException - when DataType.NULL is used as data type or the attribute name isn't valid

OrgModelException - when the attribute already exists

DataSourceException - when an unrecoverable error occurs while accessing the data source

addAttribute

void addAttribute(SessionToken session,
                  EntityType entType,
                  java.lang.String attrName,
                  DataType dataType,
                  int sizeHint,
                  java.lang.String omExtension,
                  java.lang.String mappedTo,
                  boolean isImported,
                  boolean isReadOnly)
           throws OrgModelException,
                  DataSourceException

Adds a new attribute with the given data type to the given entity type which is being mapped from the designated org model extension. 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 name of the new attribute

dataType - the data type of the attribute to be added

sizeHint - the desired size (only for STRING attributes)

omExtension - The name of the org model extension which handles the mapping or null.

mappedTo - The name of the mapped attribute in the designated org model extension.

isImported - if the mapped attribute should be imported in the OM

isReadOnly - if the mapped attribute should be read-only

Throws:

java.lang.IllegalArgumentException - when DataType.NULL is used as data type or the attribute name isn't valid

OrgModelException - when the attribute already exists

DataSourceException - when an unrecoverable error occurs while accessing the data source

modifyAttribute

void modifyAttribute(SessionToken session,
                     EntityType entType,
                     java.lang.String attrName,
                     java.lang.String mappedTo,
                     boolean isImported,
                     boolean isReadOnly)
              throws OrgModelException,
                     DataSourceException

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

void modifyAttribute(SessionToken session,
                     EntityType entType,
                     java.lang.String attrName,
                     java.lang.String omExt,
                     java.lang.String mappedTo,
                     boolean isImported,
                     boolean isReadOnly)
              throws OrgModelException,
                     DataSourceException

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

deleteAttribute

void deleteAttribute(SessionToken session,
                     EntityType entType,
                     java.lang.String attrName)
              throws OrgModelException,
                     DataSourceException

This method removes an attribute from an entity type. Mandatory attributes can't be deleted (see EntityType.getMandatoryAttributes() and EntityType.hasMandatoryAttribute(String)).

Parameters:

session - The session which is used to check for access rights on this method.

entType - the entity type from which to remove the attribute

attrName - the name of the attribute to be deleted

Throws:

java.lang.IllegalArgumentException - when the attribute name isn't valid

OrgModelException - when the attribute doesn't exist or the attribute is mandatory

DataSourceException - when an unrecoverable error occurs while accessing the data source

createAgent

long createAgent(SessionToken session,
                 java.lang.String agentUserName,
                 java.lang.String password)
          throws OrgModelException,
                 DataSourceException

Adds a new Agent with the given (unique!) user name and password. This method is preferred to creating agent entities using createEntity(SessionToken, Entity), because the latter will create an agent with random user name and password, which makes it necessary to change them both afterwards using updateEntity(SessionToken, Entity).

Parameters:

session - The session which is used to check for access rights on this method.

agentUserName - the user name of the new agent

password - the agent's password

Returns:

the ID of the new agent entity

Throws:

OrgModelException - when an agent with the same user name already exists

DataSourceException - when an unrecoverable error occurs while accessing the data source

createEntity

long createEntity(SessionToken session,
                  Entity entity)
           throws OrgModelException,
                  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

DataSourceException - when an unrecoverable error occurs while accessing the data source

updateEntity

void updateEntity(SessionToken session,
                  Entity entity)
           throws OrgModelException,
                  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

DataSourceException - when an unrecoverable error occurs while accessing the data source

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