public interface InstanceManager
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.
| 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.
|
| 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.
|
static final java.lang.String INSTANCE_EXECUTION_LOCK
static final java.lang.String INSTANCE_CHANGE_LOCK
java.util.UUID getLogicalInstanceID(SessionToken session, java.util.UUID logID)
session - The session which is used to check for access rights on this
method.logID - The stable ID used in logs of an instance.Instance getInstance(SessionToken session, java.util.UUID instanceID)
session - The session which is used to check for access rights on this
method.instanceID - The (logical) ID of the process instance to retrieve.java.lang.IllegalArgumentException - If the designated instanceID
does not exist, an IllegalArgumentException will be
thrown.InstanceReference getInstanceReference(SessionToken session, java.util.UUID instanceID)
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.java.lang.IllegalArgumentException - If the designated instanceID
does not exist, an IllegalArgumentException will be
thrown.java.util.Set<java.util.UUID> getAllInstanceIDsOf(SessionToken session, java.util.UUID templateID, boolean recursively)
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.java.lang.IllegalArgumentException - If the designated templateID
does not exist, an IllegalArgumentException will be
thrown.java.util.Map<java.util.UUID,java.util.Set<java.util.UUID>> getAllInstanceIDsOf(SessionToken session, java.util.UUID[] templateIDs, boolean recursively)
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.java.lang.IllegalArgumentException - If one of the designated
templateIDs does not exist, an
IllegalArgumentException will be thrown.RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>> getAllInstanceIDsOfIterator(SessionToken session, java.util.UUID[] templateIDs, boolean recursively)
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.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.java.lang.IllegalArgumentException - If one of the designated
templateIDs does not exist, an
IllegalArgumentException will be thrown.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)
Instance and InstanceStatus and returns their instance IDs.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).java.lang.IllegalArgumentException - If one of the designated
templateIDs does not exist, an
IllegalArgumentException will be thrown.RemoteIterator<java.util.List<SerialisablePair<java.util.UUID,java.util.UUID>>> findInstanceIDsOfIterator(SessionToken session, java.util.UUID[] templateIDs, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter)
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.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).java.lang.IllegalArgumentException - If one of the designated
templateIDs does not exist, an
IllegalArgumentException will be thrown.java.util.Map<java.util.UUID,java.util.Set<InstanceReference>> findInstanceRefsOf(SessionToken session, java.util.UUID[] templateIds, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter)
Instance and InstanceStatus and returns lightweight
objects.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).java.lang.IllegalArgumentException - If one of the designated
templateIds does not exist, an
IllegalArgumentException will be thrown.RemoteIterator<java.util.List<InstanceReference>> findInstanceRefsOfIterator(SessionToken session, java.util.UUID[] templateIds, boolean recursively, Filter instanceFilter, Filter instanceStatusFilter)
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.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).java.lang.IllegalArgumentException - If one of the designated
templateIDs does not exist.ExecutableInstance createInstanceOf(SessionToken session, java.util.UUID templateID, java.lang.String instanceName, QualifiedAgent supervisorAgent, long creationTime) throws LockException
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.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.ExecutableInstance createSubInstanceOf(SessionToken session, java.util.UUID templateID, java.lang.String instanceName, QualifiedAgent supervisorAgent, EBPInstanceReference superInstanceActivity, long creationTime) throws LockException
locked for execution
by the designated session. Do not forget to unlock the instance!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.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.ExecutableInstance getAndLockInstanceForExecution(SessionToken session, java.util.UUID instanceId) throws LockException
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.LockException - If the designated instance is already locked for
changes, a LockException will be thrown.ExecutableInstance regetInstanceForExecution(SessionToken session, java.util.UUID instanceId) throws LockException
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. 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.LockException - If the designated instance is not locked for
execution by the designated session or locked for changes, a
LockException will be thrown.void setExecutableInstance(SessionToken session, ExecutableInstance executableInstance) throws LockException
RuntimeException or
Error, the lock will still be held by the session token!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.LockException - If the designated instance is not locked for
execution by the designated session or locked for changes, a
LockException will be thrown.void unlockExecutableInstance(SessionToken session, java.util.UUID instanceID) throws LockException
RuntimeException or
Error, the lock will still be held by the session token!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.LockException - If the designated instance is not locked for
execution by the designated session or locked for changes, a
LockException will be thrown.QualifiedAgent getChangeLockingAgent(java.util.UUID instanceID)
null will be returned.instanceID - The ID of the instance to retrieve the agent of that
currently changes the instance.null in case the instance is not locked.ChangeableInstance getAndLockInstanceForChanging(SessionToken session, java.util.UUID instanceID) throws LockException
LockException. This also includes the very same user that
already has the change lock; change locks are not reentrant. 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.
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.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.InstanceChanging.getInstanceForChanging(SessionToken,
UUID)ChangeReport changeInstance(SessionToken session, ChangeableInstance instance, java.util.Locale... locales) throws LockException
This method is called by the ExecutionManager and must not be called otherwise!
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.LockException - If the designated instance is not locked by the designated user for
changes, a LockException will be thrown.InstanceChanging.changeAndUnlockInstance(SessionToken,
ChangeableInstance, Locale...)ChangeReport changeAndUnlockInstance(SessionToken session, ChangeableInstance instance, java.util.Locale... locales) throws LockException
This method is called by the ExecutionManager and must not be called otherwise!
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.LockException - If the designated instance is not locked by the designated user for
changes, a LockException will be thrown.InstanceChanging.changeAndUnlockInstance(SessionToken,
ChangeableInstance, Locale...)void unlockChangeableInstance(SessionToken session, java.util.UUID instanceID) throws LockException
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.
This method is called by the ExecutionManager and must not
be called otherwise!
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.LockException - If the designated instance is not locked by the
designated user for changes, a LockException will
be thrown.InstanceChanging.abortInstanceChanging(SessionToken,
UUID)InstanceStatus getInstanceStatus(SessionToken session, java.util.UUID instanceID)
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.getAndLockInstanceStatus(SessionToken, UUID)void setExecutionStatus(SessionToken session, java.util.UUID instanceID, ProcessConstants.InstanceExecutionStatus executionStatus, java.lang.String comment) throws LockException
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.LockException - If the designated instance is not locked for
execution by the designated session, a LockException
will be thrown.InstanceStatus getAndLockInstanceStatus(SessionToken session, java.util.UUID instanceID) throws LockException
getAndLockInstanceForChanging(SessionToken, UUID) also apply for
an instance status lock.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.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.void setInstanceStatus(SessionToken session, InstanceStatus instanceStatus) throws LockException
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.LockException - If the corresponding status object is not locked by
the designated user, a LockException will be thrown.void unlockInstanceStatus(SessionToken session, java.util.UUID instanceID) throws LockException
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.LockException - If the corresponding status object is not locked by
the designated user, a LockException will be
thrown.java.util.Map<java.util.UUID,java.util.UUID> archiveInstance(SessionToken session, java.util.UUID instanceID) throws InvalidInstanceStateException, LockException, DataConsistencyException
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.
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.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.