de.aristaflow.adept2.core.processmanager

Interface InstanceManager

public interface InstanceManager

This sub-interface of the process manager handles instances. It allows to create and retrieve process instances. The retrieval is distinguished between read-only access and executing a process instance. The manipulating of a process instance (including its status) is always exclusive.
Execution locks are session-specific and short-term locks. They just block other locks until released but do not lead to a LockException. Change locks are used for changing instances as well as instance status. They prevent other locks from being retrieved including other changes locks on the same instance. Since change locks are long-term locks, they are user-specific.

To simplify usage of locks and prevent deadlocks, the highest method in a method stack should retrieve a lock and the corresponding object. As soon as the lock is released, the corresponding object must not be re-used again! Called methods (and subsessions) are provided with such a "locked object" instead of retrieving it again. If a method is provided with an object needing a lock, for instance, an executable instance, the method may rely on the calling method (and the provided session) to have the corresponding lock. As soon as a new session token is created and provided to a called method, method must not be provided the "locked object"!

If the designated template or instance ID on any method expecting one does not exist, an IllegalArgumentException will be thrown.

Methods not throwing a LockException do not synchronise, that means the retrieved data may be slightly out of date.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	INSTANCE_CHANGE_LOCK The string constant for the lock type for changing instances.
static java.lang.String	INSTANCE_EXECUTION_LOCK The string constant for the lock type for executing instances.

Method Summary

Modifier and Type	Method and Description
java.util.Map<java.util.UUID,java.util.UUID>	archiveInstance(SessionToken session, java.util.UUID instanceID) Archives the designated instance, that is the instance and all related data like the status, child instances (and their statuses) as well as the (modified) template in case of a instance-specific template are removed from this instance manager.
ChangeReport	changeAndUnlockInstance(SessionToken session, ChangeableInstance instance, java.util.Locale... locales) Releases the lock of the designated instance and incorporates the made changes.
ChangeReport	changeInstance(SessionToken session, ChangeableInstance instance, java.util.Locale... locales) Changes the instance and returns a new UUID but does not release the lock.
ExecutableInstance	createInstanceOf(SessionToken session, java.util.UUID templateID, java.lang.String instanceName, QualifiedAgent supervisorAgent, long creationTime) Creates a new instance for execution.
ExecutableInstance	createSubInstanceOf(SessionToken session, java.util.UUID templateID, java.lang.String instanceName, QualifiedAgent supervisorAgent, EBPInstanceReference superInstanceActivity, long creationTime) Creates a new instance as subprocess for execution.
java.util.Map<java.util.UUID,java.util.Set<java.util.UUID>>	findInstanceIDsOf(SessionToken session, java.util.UUID[] templateIDs, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter) Finds all instances of the designated templates matching the two filters on Instance and InstanceStatus and returns their instance IDs.
RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>>	findInstanceIDsOfIterator(SessionToken session, java.util.UUID[] templateIDs, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter) Similar to findInstanceIDsOf(SessionToken, UUID[], boolean, Filter, Filter) but with partial retrieval of the instance IDs and therefore no grouping by template ID.
java.util.Map<java.util.UUID,java.util.Set<InstanceReference>>	findInstanceRefsOf(SessionToken session, java.util.UUID[] templateIds, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter) Finds all instances of the designated templates matching the two filters on Instance and InstanceStatus and returns lightweight objects.
RemoteIterator<java.util.List<InstanceReference>>	findInstanceRefsOfIterator(SessionToken session, java.util.UUID[] templateIds, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter) Similar to findInstanceRefsOf(SessionToken, UUID[], boolean, Filter, Filter) but with partial retrieval of the instance references and therefore no grouping by template ID.
java.util.Map<java.util.UUID,java.util.Set<java.util.UUID>>	getAllInstanceIDsOf(SessionToken session, java.util.UUID[] templateIDs, boolean recursively) Gets the (logical) IDs of all process instances of the designated process templates.
java.util.Set<java.util.UUID>	getAllInstanceIDsOf(SessionToken session, java.util.UUID templateID, boolean recursively) Gets the (logical) IDs of all process instances of the designated process template.
RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>>	getAllInstanceIDsOfIterator(SessionToken session, java.util.UUID[] templateIDs, boolean recursively) Similar to getAllInstanceIDsOf(SessionToken, UUID[], boolean) but with partial retrieval of the instance IDs and therefore no grouping by template ID.
ChangeableInstance	getAndLockInstanceForChanging(SessionToken session, java.util.UUID instanceID) Gets a process instance that may be changed after retrieval.
ExecutableInstance	getAndLockInstanceForExecution(SessionToken session, java.util.UUID instanceId) Gets an object allowing to execute the designated instance, which is, setting the states and the performer of the nodes.
InstanceStatus	getAndLockInstanceStatus(SessionToken session, java.util.UUID instanceID) Gets an object representing the status of the designated process instance and locks the instance for further manipulation, for instance, another status change, a schema-evolution or even a new instantiation.
QualifiedAgent	getChangeLockingAgent(java.util.UUID instanceID) Gets the agent currently locking the designated instance for changes.
Instance	getInstance(SessionToken session, java.util.UUID instanceID) Gets the designated process instance conforming to the ADEPT2-process model.
InstanceReference	getInstanceReference(SessionToken session, java.util.UUID instanceID) Gets the lightweight representation of the designated process instance.
InstanceStatus	getInstanceStatus(SessionToken session, java.util.UUID instanceID) Gets an object representing the status of the designated process instance, that is, whether the instance is outdated, may be derived, may be instantiated, whether instances may be migrated to and whether instances are changeable.
java.util.UUID	getLogicalInstanceID(SessionToken session, java.util.UUID logID) Gets the current logical ID of the instance with the designated log ID.
ExecutableInstance	regetInstanceForExecution(SessionToken session, java.util.UUID instanceId) Gets the executable instance again while holding the lock.
void	setExecutableInstance(SessionToken session, ExecutableInstance executableInstance) Saves the made changes for the designated instance but does not unlock the instance.
void	setExecutionStatus(SessionToken session, java.util.UUID instanceID, ProcessConstants.InstanceExecutionStatus executionStatus, java.lang.String comment) Sets the execution status of the designated instance according to the designated values.
void	setInstanceStatus(SessionToken session, InstanceStatus instanceStatus) Sets the status of the instance (identified by the instance status object), to the new status.
void	unlockChangeableInstance(SessionToken session, java.util.UUID instanceID) Releases the lock of the designated instance but ignores the made changes.
void	unlockExecutableInstance(SessionToken session, java.util.UUID instanceID) Unlocks the designated instance and ignores any changes.
void	unlockInstanceStatus(SessionToken session, java.util.UUID instanceID) Unlocks the status of the designated instance ignores made changes and and releases the change lock on the process instance status.

Field Detail

INSTANCE_EXECUTION_LOCK

static final java.lang.String INSTANCE_EXECUTION_LOCK

The string constant for the lock type for executing instances.

See Also:

Constant Field Values

INSTANCE_CHANGE_LOCK

static final java.lang.String INSTANCE_CHANGE_LOCK

The string constant for the lock type for changing instances.

See Also:

Constant Field Values

Method Detail

getLogicalInstanceID

java.util.UUID getLogicalInstanceID(SessionToken session,
                                    java.util.UUID logID)

Gets the current logical ID of the instance with the designated log ID. This just maps the (stable) log ID to the (changing) logical ID of an instance and is used, for instance, to identify the instance corresponding to a log entry.
This method is used internally only by low-level components! A high-level component calling this method does not work as intended.

Parameters:

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

logID - The stable ID used in logs of an instance.

Returns:

The logical (normal) ID of an instance or null in case there is no instance with the designated log ID.

getInstance

Instance getInstance(SessionToken session,
                     java.util.UUID instanceID)

Gets the designated process instance conforming to the ADEPT2-process model. The returned instance can not be changed. Also, the instance is not locked which means successive calls may result in different node states.

Parameters:

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

instanceID - The (logical) ID of the process instance to retrieve.

Returns:

An object representing the designated process instance.

Throws:

java.lang.IllegalArgumentException - If the designated instanceID does not exist, an IllegalArgumentException will be thrown.

getInstanceReference

InstanceReference getInstanceReference(SessionToken session,
                                       java.util.UUID instanceID)

Gets the lightweight representation of the designated process instance. This method does interfere with any locking of the instance.

Parameters:

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

instanceID - The (logical) ID of the process instance to retrieve the lightweight representation of.

Returns:

The lightweight representation of the designated process instance.

Throws:

java.lang.IllegalArgumentException - If the designated instanceID does not exist, an IllegalArgumentException will be thrown.

getAllInstanceIDsOf

java.util.Set<java.util.UUID> getAllInstanceIDsOf(SessionToken session,
                                                  java.util.UUID templateID,
                                                  boolean recursively)

Gets the (logical) IDs of all process instances of the designated process template. This includes instances that are modified but which are based on the designated template and it may include all instances of embedded templates.

Parameters:

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

templateID - The process template of which to retrieve all instances. Modified instances based on this template will also be returned. If this is an instance-specific or embedded template, only the actual instances will be returned but no instances having only the same base template. This must not be null.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

Returns:

The IDs of all process instances (including modified instances and possibly recursively all embedded subprocess templates) of the designated process template.

Throws:

java.lang.IllegalArgumentException - If the designated templateID does not exist, an IllegalArgumentException will be thrown.

getAllInstanceIDsOf

java.util.Map<java.util.UUID,java.util.Set<java.util.UUID>> getAllInstanceIDsOf(SessionToken session,
                                                                                java.util.UUID[] templateIDs,
                                                                                boolean recursively)

Gets the (logical) IDs of all process instances of the designated process templates. This includes instances that are modified but which are based on the designated template and it may include all instances of embedded templates recursively.

Parameters:

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

templateIDs - The process templates of which to retrieve all instances. If this is null, the instance IDs for all templates will be returned. If this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

Returns:

The IDs of all process instances (including modified instances and possibly recursively all embedded subprocess templates) of the designated process templates. The map contains the corresponding base template ID as key and the instance IDs as values. If a template does not have any instances, an empty set will be provided. If the designated template IDs contain an instance-specific or embedded template, the corresponding instances will be provided with the requested template ID as key. Therefore an instance may be in the map twice: once with the requested base template ID and once with the requested ID of the instance-specific template.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIDs does not exist, an IllegalArgumentException will be thrown.

getAllInstanceIDsOfIterator

RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>> getAllInstanceIDsOfIterator(SessionToken session,
                                                                                                            java.util.UUID[] templateIDs,
                                                                                                            boolean recursively)

Similar to getAllInstanceIDsOf(SessionToken, UUID[], boolean) but with partial retrieval of the instance IDs and therefore no grouping by template ID. The first element of each pair is the template ID, the pairs are naturally ordered by template ID. Note that the order of the designated template IDs is ignored.

Parameters:

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

templateIDs - The process templates of which to retrieve all instances. If this is null, the instance IDs for all templates will be returned. If this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

Returns:

An iterator for the IDs of all process instances (including modified instances and possibly recursively all embedded subprocess templates) of the designated process templates. The first element of each pair is the corresponding (base) template ID. The instance IDs (the pairs) are naturally ordered by their template ID. If the designated template IDs contain an instance-specific or embedded template, the corresponding instances will be provided with the requested template ID as first element. Therefore an instance may be in the list twice: once with the requested base template ID and once with the requested ID of the instance-specific template.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIDs does not exist, an IllegalArgumentException will be thrown.

findInstanceIDsOf

java.util.Map<java.util.UUID,java.util.Set<java.util.UUID>> findInstanceIDsOf(SessionToken session,
                                                                              java.util.UUID[] templateIDs,
                                                                              boolean recursively,
                                                                              Filter instanceFilter,
                                                                              Filter instanceStatusFilter)

Finds all instances of the designated templates matching the two filters on Instance and InstanceStatus and returns their instance IDs.

Parameters:

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

templateIDs - The process templates of which to retrieve all instances. If this is null, the instance IDs for all templates will be returned. If this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

instanceFilter - The filter on the Instances (optional).

instanceStatusFilter - The filter on the instance's status (optional).

Returns:

The IDs of all process instances (including modified instances and possibly recursively all embedded subprocess templates) matching the two filters indexed by the ID of the corresponding process template. The map contains the corresponding template ID as key and the instance IDs as values. If a template does not have any instances, an empty set will be provided. If the designated template IDs contain an instance-specific or embedded template, the corresponding instances will be provided with the requested template ID as key. Therefore an instance may be in the map twice: once with the requested base template ID and once with the requested ID of the instance-specific template.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIDs does not exist, an IllegalArgumentException will be thrown.

findInstanceIDsOfIterator

RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>> findInstanceIDsOfIterator(SessionToken session,
                                                                                                          java.util.UUID[] templateIDs,
                                                                                                          boolean recursively,
                                                                                                          Filter instanceFilter,
                                                                                                          Filter instanceStatusFilter)

Similar to findInstanceIDsOf(SessionToken, UUID[], boolean, Filter, Filter) but with partial retrieval of the instance IDs and therefore no grouping by template ID. The first element of each pair is the template ID, the pairs are naturally ordered by template ID. Note that the order of the designated template IDs is ignored.

Parameters:

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

templateIDs - The process templates of which to retrieve all instances. If this is null, the instance IDs for all templates will be returned. If this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

instanceFilter - The filter on the Instances (optional).

instanceStatusFilter - The filter on the instance's status (optional).

Returns:

An iterator for the IDs of all process instances (including modified instances and possibly recursively all embedded subprocess templates) matching the two filters. The first element of each pair is the corresponding template ID. The instance IDs (the pairs) are naturally ordered by their template ID. If the designated template IDs contain an instance-specific or embedded template, the corresponding instances will be provided with the requested template ID as first element. Therefore an instance may be in the list twice: once with the requested base template ID and once with the requested ID of the instance-specific template.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIDs does not exist, an IllegalArgumentException will be thrown.

findInstanceRefsOf

java.util.Map<java.util.UUID,java.util.Set<InstanceReference>> findInstanceRefsOf(SessionToken session,
                                                                                  java.util.UUID[] templateIds,
                                                                                  boolean recursively,
                                                                                  Filter instanceFilter,
                                                                                  Filter instanceStatusFilter)

Finds all instances of the designated templates matching the two filters on Instance and InstanceStatus and returns lightweight objects.

Parameters:

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

templateIds - The process templates of which to retrieve all instances. If this is null, the instance references for all templates will be returned. if this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

instanceFilter - The filter on the Instances (optional).

instanceStatusFilter - The filter on the instance's status (optional).

Returns:

All process instance references (including modified instances and possibly recursively all embedded subprocess templates) matching the two filters indexed by the ID of the corresponding process template. The map contains the corresponding template ID as key and the instance references as values. If a template does not have any instances, an empty set will be provided. If the designated template IDs contain an instance-specific or embedded template, the corresponding instances will be provided with the requested template ID as key. Therefore an instance may be in the map twice: once with the requested base template ID and once with the requested ID of the instance-specific template.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIds does not exist, an IllegalArgumentException will be thrown.

findInstanceRefsOfIterator

RemoteIterator<java.util.List<InstanceReference>> findInstanceRefsOfIterator(SessionToken session,
                                                                             java.util.UUID[] templateIds,
                                                                             boolean recursively,
                                                                             Filter instanceFilter,
                                                                             Filter instanceStatusFilter)

Similar to findInstanceRefsOf(SessionToken, UUID[], boolean, Filter, Filter) but with partial retrieval of the instance references and therefore no grouping by template ID. However, the instance references are ordered by template ID. Note that they are ordered naturally, the order of the designated template IDs is ignored.

Parameters:

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

templateIds - The process templates of which to retrieve all instances. If this is null, the instance references for all templates will be returned. if this contains an instance-specific or embedded template, for this template only the actual instances will be returned but no instances having only the same base template.

recursively - Whether to also recursively retrieve the instances of all embedded subprocesses. If not, no instance of an embedded subprocess will be included. Note that recursive retrieval may have a big performance impact.

instanceFilter - The filter on the Instances (optional).

instanceStatusFilter - The filter on the instance's status (optional).

Returns:

An iterator for instance references (including modified instances and possibly recursively all embedded subprocess templates) matching the two filters. The instance references are naturally ordered by their template ID.

Throws:

java.lang.IllegalArgumentException - If one of the designated templateIDs does not exist.

createInstanceOf

ExecutableInstance createInstanceOf(SessionToken session,
                                    java.util.UUID templateID,
                                    java.lang.String instanceName,
                                    QualifiedAgent supervisorAgent,
                                    long creationTime)
                             throws LockException

Creates a new instance for execution. The returned instance will be in its initial state, that is, all nodes (including the start node) are not activated. The instance may be executed after retrieval and it is locked for execution by the designated session. Do not forget to unlock the instance!

Parameters:

session - The session which is used to check for access rights on this method and to lock the instance for execution.

templateID - The ID of the template the created instance is based on.

instanceName - The name of the instance to be created.

supervisorAgent - The supervisor of the created instance.

creationTime - The creation time of the instance.

Returns:

A newly created instance having the designated attributes and locked for execution.

Throws:

LockException - If the creation is not possible since the template status of the corresponding template is currently locked for updates (which may set the template to not instantiable), a LockException will be thrown.

InternalServiceException - If the current licence does not support the process type of the designated template, an InvalidLicenceException wrapped as InternalServiceException will be thrown.

createSubInstanceOf

ExecutableInstance createSubInstanceOf(SessionToken session,
                                       java.util.UUID templateID,
                                       java.lang.String instanceName,
                                       QualifiedAgent supervisorAgent,
                                       EBPInstanceReference superInstanceActivity,
                                       long creationTime)
                                throws LockException

Creates a new instance as subprocess for execution. The returned instance will be in its initial state, that is, all nodes (including the start node) are not activated. The instance may be executed after retrieval and it is locked for execution by the designated session. Do not forget to unlock the instance!

Parameters:

session - The session which is used to check for access rights on this method and to lock the instance for execution.

templateID - The ID of the template the created instance is based on.

instanceName - The name of the instance to be created.

supervisorAgent - The supervisor of the created instance.

superInstanceActivity - A reference to the activity which represents the subprocess in the corresponding super-process.

creationTime - The creation time of the instance.

Returns:

A newly created instance having the designated attributes and locked for execution

Throws:

LockException - If the creation is not possible since the template status of the corresponding (subprocess-)template is currently locked for updates (which may set the template to not instantiable), a LockException will be thrown.

getAndLockInstanceForExecution

ExecutableInstance getAndLockInstanceForExecution(SessionToken session,
                                                  java.util.UUID instanceId)
                                           throws LockException

Gets an object allowing to execute the designated instance, which is, setting the states and the performer of the nodes.
This locks retrieval of change locks as well as other execution locks. However, since execution locks are meant to be short-term, retrieving a change or an execution lock waits until this execution lock is released. Therefore it is absolutely crucial to release the lock afterwards!
Execution locks are reentrant. Additionally, a user having a change lock may also retrieve an execution lock, but both locks have to be released separately.

Parameters:

session - The session which is used to check for access rights on this method and to lock the instance for execution.

instanceId - The (logical) ID of the process instance to execute.

Returns:

A representation of a process instance for execution.

Throws:

LockException - If the designated instance is already locked for changes, a LockException will be thrown.

regetInstanceForExecution

ExecutableInstance regetInstanceForExecution(SessionToken session,
                                             java.util.UUID instanceId)
                                      throws LockException

Gets the executable instance again while holding the lock. This is required when methods are called that change the executable instance using subsessions. Subsessions will get the execution lock, change the instance and store it. Afterwards the calling method has a deprecated object.
The designated session needs to have the execution lock on the designated instance.

Parameters:

session - The session which is used to check for access rights on this method and which holds the execution lock on the designated instance.

instanceId - The (logical) ID of the process instance to execute.

Returns:

A representation of a process instance for execution.

Throws:

LockException - If the designated instance is not locked for execution by the designated session or locked for changes, a LockException will be thrown.

setExecutableInstance

void setExecutableInstance(SessionToken session,
                           ExecutableInstance executableInstance)
                    throws LockException

Saves the made changes for the designated instance but does not unlock the instance. The designated instance has to be locked for execution by the designated session.
If the method is left due to a RuntimeException or Error, the lock will still be held by the session token!

Parameters:

session - The session which is used to check for access rights on this method and which holds the execution lock on the designated instance.

executableInstance - The process instance which has been executed.

Throws:

LockException - If the designated instance is not locked for execution by the designated session or locked for changes, a LockException will be thrown.

unlockExecutableInstance

void unlockExecutableInstance(SessionToken session,
                              java.util.UUID instanceID)
                       throws LockException

Unlocks the designated instance and ignores any changes. This method is usually called after an execution has failed or an execution lock is needed to retrieve up-to-date data but the executable instance has not change its state. The designated instance has to be locked for execution by the designated session.
If the method is left due to a RuntimeException or Error, the lock will still be held by the session token!

Parameters:

session - The session which is used to check for access rights on this method and which holds the execution lock on the designated instance.

instanceID - The ID of the instance to unlock.

Throws:

LockException - If the designated instance is not locked for execution by the designated session or locked for changes, a LockException will be thrown.

getChangeLockingAgent

QualifiedAgent getChangeLockingAgent(java.util.UUID instanceID)

Gets the agent currently locking the designated instance for changes. If the designated instance is not locked, null will be returned.

Parameters:

instanceID - The ID of the instance to retrieve the agent of that currently changes the instance.

Returns:

The agent that currently has the change lock on the designated instance or null in case the instance is not locked.

getAndLockInstanceForChanging

ChangeableInstance getAndLockInstanceForChanging(SessionToken session,
                                                 java.util.UUID instanceID)
                                          throws LockException

Gets a process instance that may be changed after retrieval. The process instance is locked by the designated user while it is modified.
Change locks are long-term and therefore no further execution lock nor any other change lock may be retrieved. Trying to retrieve a lock leads to a LockException. This also includes the very same user that already has the change lock; change locks are not reentrant.
A user having a change lock may also retrieve an execution lock. This is session-specific and needs to be released by the very same session.

A change lock will not be able to be retrieved if the corresponding template has a lock on the status. If the corresponding instance has an execution lock, this method will block until it is released.

Parameters:

session - The session which is used to check for access rights on this method and to identify the locking agent and the corresponding organisational position.

instanceID - The unique (logical) ID of the process instance to retrieve and lock for changing.

Returns:

An instance that may be changed after retrieval.

Throws:

LockException - If the designated instance is already locked for changes, its status or the status of the corresponding template is currently locked, a LockException will be thrown.

See Also:

InstanceChanging.getInstanceForChanging(SessionToken, UUID)

changeInstance

ChangeReport changeInstance(SessionToken session,
                            ChangeableInstance instance,
                            java.util.Locale... locales)
                     throws LockException

Changes the instance and returns a new UUID but does not release the lock. This is needed for work requiring the new UUID but still subject of the corresponding change transaction.

This method is called by the ExecutionManager and must not be called otherwise!

Parameters:

session - The session which is used to check for access rights on this method and to identify the unlocking agent and the corresponding organisational position.

instance - An instance that has been changed and is still locked.

locales - The locales the change report should provide (or at least a fallback of each). If this is null, Locale.ROOT will be used.

Returns:

A change report providing information on the validity of the instance as well as its new ID if the change has been successful.

Throws:

LockException - If the designated instance is not locked by the designated user for changes, a LockException will be thrown.

See Also:

InstanceChanging.changeAndUnlockInstance(SessionToken, ChangeableInstance, Locale...)

changeAndUnlockInstance

ChangeReport changeAndUnlockInstance(SessionToken session,
                                     ChangeableInstance instance,
                                     java.util.Locale... locales)
                              throws LockException

Releases the lock of the designated instance and incorporates the made changes. In case of an exception, the lock will not be released and still be held by the current lock owning user!

This method is called by the ExecutionManager and must not be called otherwise!

Parameters:

session - The session which is used to check for access rights on this method and to identify the unlocking agent and the corresponding organisational position.

instance - An instance that has been changed and is still locked.

locales - The locales the change report should provide (or at least a fallback of each). If this is null, Locale.ROOT will be used.

Returns:

A change report providing information on the validity of the instance as well as its new ID if the change has been successful.

Throws:

LockException - If the designated instance is not locked by the designated user for changes, a LockException will be thrown.

See Also:

InstanceChanging.changeAndUnlockInstance(SessionToken, ChangeableInstance, Locale...)

unlockChangeableInstance

void unlockChangeableInstance(SessionToken session,
                              java.util.UUID instanceID)
                       throws LockException

Releases the lock of the designated instance but ignores the made changes. In case of an exception, the lock will not be released and still be held by the current lock owning user!
This method is to be used after changing the instance via changeInstance(SessionToken, ChangeableInstance, Locale...) while keeping the lock. Since the changeable instance object is invalid after the change this method accepts the new ID instead of the object.
If you just need to unlock without having changed the instance, just provide the old instance ID. But be sure to always have the lock on the instance!

This method is called by the ExecutionManager and must not be called otherwise!

Parameters:

session - The session which is used to check for access rights on this method and to identify the unlocking agent and the corresponding organisational position.

instanceID - The ID of a a locked instance that has been changed via changeInstance(SessionToken, ChangeableInstance, Locale...) or of which the changes are to be aborted.

Throws:

LockException - If the designated instance is not locked by the designated user for changes, a LockException will be thrown.

See Also:

InstanceChanging.abortInstanceChanging(SessionToken, UUID)

getInstanceStatus

InstanceStatus getInstanceStatus(SessionToken session,
                                 java.util.UUID instanceID)

Gets an object representing the status of the designated process instance, that is, whether the instance is outdated, may be derived, may be instantiated, whether instances may be migrated to and whether instances are changeable. The returned object does not allow to change the status (set-methods and release). For changing the status, the corresponding instance has to be locked.

Parameters:

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

instanceID - The (logical) ID of the instance to get the status of.

Returns:

An object containing the status of the designated process instance.

See Also:

getAndLockInstanceStatus(SessionToken, UUID)

setExecutionStatus

void setExecutionStatus(SessionToken session,
                        java.util.UUID instanceID,
                        ProcessConstants.InstanceExecutionStatus executionStatus,
                        java.lang.String comment)
                 throws LockException

Sets the execution status of the designated instance according to the designated values. The used session has to have an execution lock on the instance.
This allows to adapt the execution status while executing an instance without having a change lock (for changing the instance status). A change lock will not be able to be retrieved if there is an execution lock on the instance.

Parameters:

session - The session which is used to check for access rights on this method and which has to have the execution lock on the instance.

instanceID - The (logical) ID of the instance to set the execution status of.

executionStatus - The new execution status of the instance.

comment - The comment for the new execution status.

Throws:

LockException - If the designated instance is not locked for execution by the designated session, a LockException will be thrown.

getAndLockInstanceStatus

InstanceStatus getAndLockInstanceStatus(SessionToken session,
                                        java.util.UUID instanceID)
                                 throws LockException

Gets an object representing the status of the designated process instance and locks the instance for further manipulation, for instance, another status change, a schema-evolution or even a new instantiation. The returned object allows to change whether the instance is outdated, may be derived, may be instantiated, whether instances may be migrated to and whether instances are changeable. The instance is locked by the designated user.
Instance status locks are the same locks used for changing instances. Therefore the constraints specified for getAndLockInstanceForChanging(SessionToken, UUID) also apply for an instance status lock.

Parameters:

session - The session which is used to check for access rights on this method and to identify the locking agent and the corresponding organisational position.

instanceID - The (logical) ID of the process instance to get and manipulate the status of.

Returns:

An object containing the status of the designated process instance.

Throws:

LockException - If the designated instance is already locked for changes, its status or the status of the corresponding template is currently locked, a LockException will be thrown.

setInstanceStatus

void setInstanceStatus(SessionToken session,
                       InstanceStatus instanceStatus)
                throws LockException

Sets the status of the instance (identified by the instance status object), to the new status. The caller needs to have the lock on the template status.

Parameters:

session - The session which is used to check for access rights on this method and to identify the setting agent and the corresponding organisational position.

instanceStatus - The object containing the new status of the process instance.

Throws:

LockException - If the corresponding status object is not locked by the designated user, a LockException will be thrown.

unlockInstanceStatus

void unlockInstanceStatus(SessionToken session,
                          java.util.UUID instanceID)
                   throws LockException

Unlocks the status of the designated instance ignores made changes and and releases the change lock on the process instance status. Unlocking will fail, if the designated user does not have the lock on the instance status. In case of an exception, the lock will not be released and still be held by the current lock owning user!

Parameters:

session - The session which is used to check for access rights on this method and to identify the unlocking agent and the corresponding organisational position.

instanceID - The ID of the instance to unlock the status of.

Throws:

LockException - If the corresponding status object is not locked by the designated user, a LockException will be thrown.

archiveInstance

java.util.Map<java.util.UUID,java.util.UUID> archiveInstance(SessionToken session,
                                                             java.util.UUID instanceID)
                                                      throws InvalidInstanceStateException,
                                                             LockException,
                                                             DataConsistencyException

Archives the designated instance, that is the instance and all related data like the status, child instances (and their statuses) as well as the (modified) template in case of a instance-specific template are removed from this instance manager. Neither the instance nor its status may be locked, the instance needs to be IE_FINISHED or IE_ABORTED. Additionally, only top-level instances may be archived; or more specific instances that do not have a parent instance within this instance manager. This ensures that only complete instance hierarchies will be archived.

Use this method carefully! When archiving instances one has to take care of the consistency manually, especially for instance hierarchies which are distributed on several instance managers. Additionally, also archive the values and the histories of the corresponding data elements in the data manager.

Parameters:

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

instanceID - The ID of the instance which to remove from this instance manager.

Returns:

The IDs of all archived instances (key) along with the corresponding log ID (value) which allows to archive data related to these instances.

Throws:

InvalidInstanceStateException - If the designated instance is not IE_FINISHED or IE_ABORTED, an InvalidInstanceStateException will be thrown.

LockException - If the designated instance can not be removed since a lock is held on either the instance or the instance status, a LockException will be thrown.

DataConsistencyException - If removing the instance leads to inconsistencies, that is, the prerequisites are not fulfilled, a DataConsistencyException will be thrown.