de.aristaflow.adept2.core.executionmanager

Interface InstanceControl

public interface InstanceControl

This interface provides the means to control the execution of an instance, that is, starting, suspending, resuming, stopping and committing. It also allows to browse all instantiable templates (process templates existing in the underlying process manager that are allowed to be instantiated) and to create and start sub process instances. Like activities the instances have to be in the right state for transitions, for instance, only a suspended instance may be resumed but not an aborted one. The appropriate states are described at the corresponding transition methods.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
SerialisablePair<java.lang.Boolean,ProcessConstants.InstanceExecutionStatus>	checkForAndFixInconsistencies(SessionToken session, java.util.UUID instId) Checks the designated instance for inconsistencies and tries to fix them.
void	commitInstance(SessionToken session, java.util.UUID instanceID) Commits the designated instance, that means, the instance is marked as successfully completed.
java.util.UUID	createAndStartInstance(SessionToken session, java.util.UUID processTemplateID, ExecutionContext executionContext, java.net.URI[] rtMgr, java.net.URI[] stateListener) Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance.
java.util.UUID	createAndStartInstance(SessionToken session, java.util.UUID processTemplateID, java.net.URI[] stateListener) Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance.
java.util.UUID	createAndStartInstance(SessionToken session, java.util.UUID processTemplateID, java.net.URI[] rtMgr, java.net.URI[] stateListener) Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance.
java.util.UUID	createAndStartSubInstance(SessionToken session, EBPInstanceReference superInstanceActivity, ExecutionContext executionContext, java.net.URI[] stateListener) Creates a new instance of the designated process template as a subprocess of the designated activity.
InstanceDataContainer	createInstanceDataContainer(SessionToken session, java.util.UUID processTemplateID) Creates an instance data container for the input (and output) parameters of the designated template.
java.util.Set<TemplateReference>	getInstantiableTemplateReferences(SessionToken session, boolean includeOutdated) Gets the lightweight representations of all templates that can be instantiated as top-level-processes, that is, they exist in the process manager and they are in the state INSTANTIABLE as top-level processes.
RemoteIterator<java.util.List<TemplateReference>>	getInstantiableTemplateReferencesIterator(SessionToken session, boolean includeOutdated) The same as getInstantiableTemplateReferences(SessionToken, boolean) but with partial retrieval of the template references.
java.util.Set<java.util.UUID>	getInstantiableTemplates(SessionToken session, boolean includeOutdated) Gets the IDs of all templates that can be instantiated as top-level-processes, that is, they exist in the process manager and they are in the state INSTANTIABLE as top-level processes.
RemoteIterator<java.util.List<java.util.UUID>>	getInstantiableTemplatesIterator(SessionToken session, boolean includeOutdated) The same as getInstantiableTemplates(SessionToken, boolean) but with partial retrieval of the template IDs.
ParameterDataContext	getPublicDataContext(SessionToken session, java.util.UUID instanceID) Gets the data context providing the (most recent) values of the public data elements of the designated instance.
TemplateReference	getTemplateReference(SessionToken session, java.util.UUID templateID) Gets the lightweight representation of the designated process template.
Vote	prepareCommitInstance(SessionToken session, java.util.UUID instanceID) Prepares the commit of an instance.
void	resumeInstance(SessionToken session, java.util.UUID instanceID) Resumes the designated (top-level or sub-process) instance and (re-)offers all active (including suspended) activities to the worklist manager.
void	resumeInstance(SessionToken session, java.util.UUID instanceID, java.net.URI[] stateListener) Resumes the designated (top-level or sub-process) instance and (re-)offers all active (including suspended) activities to the worklist manager.
void	rollbackInstance(SessionToken session, java.util.UUID instanceID) Resets the designated instance, which includes rolling back the data and the effects of the instance as a whole.
void	stopAndAbortInstance(SessionToken session, java.util.UUID instanceID, boolean propagateToRunningActs, java.lang.String errorMessage, java.lang.String state, long errorCode) Stops the designated instance and if appropriate also the running activities.
boolean	suspendInstance(SessionToken session, java.util.UUID instanceID, boolean propagateToRunningActs) Suspends the designated instance and if appropriate also the running activities.

Method Detail

createInstanceDataContainer

InstanceDataContainer createInstanceDataContainer(SessionToken session,
                                                  java.util.UUID processTemplateID)

Creates an instance data container for the input (and output) parameters of the designated template. The values of the input parameters can be set and provided to the start of an instance based on the designated template.

Parameters:

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

processTemplateID - The template for which to create a data container having the corresponding input and output parameters.

Returns:

An InstanceDataContainer having all input and output parameters of the designated template which allows to set input parameters and retrieve the values of the output parameters.

getPublicDataContext

ParameterDataContext getPublicDataContext(SessionToken session,
                                          java.util.UUID instanceID)

Gets the data context providing the (most recent) values of the public data elements of the designated instance. The data context has the latest values of the public data elements which means, they are rather arbitrary.

Parameters:

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

instanceID - The ID of the instance for which to retrieve the values of the public data elements.

Returns:

The parameter data context providing the most recent values of the public data elements of the designated instance.

createAndStartInstance

java.util.UUID createAndStartInstance(SessionToken session,
                                      java.util.UUID processTemplateID,
                                      java.net.URI[] stateListener)
                               throws InvalidTemplateStateException,
                                      InvalidDataContainerException

Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance. The process may not have mandatory input or output parameters and is executed normally (in ExecutionMode PRODUCTION). The start node of the created instance is executed internally immediately. This method forwards to createAndStartInstance(SessionToken, UUID, ExecutionContext, URI[], URI[]) whereas the ExecutionContext contains only agent and orgPosition.

Parameters:

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

processTemplateID - The template which is to be instantiated. The template has to be in state INSTANTIABLE for top-level usage.

stateListener - The URIs identifying a callback interface to be notified when the top-level instance to be started has changed its state (has been suspended, resumed, finished or failed) or null in case no notification is necessary. The listener has to implement InstanceStateListener.

Returns:

The ID of the created process instance which is unique with respect to the process management system and the server respectively

Throws:

InvalidTemplateStateException - If the process template is not instantiable for top-level usage, an InvalidTemplateStateException will be raised.

InvalidDataContainerException - If the designated process has mandatory input parameters, an InvalidDataContainerException will be raised.

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

See Also:

TemplateStatus.isInstantiable(boolean)

createAndStartInstance

java.util.UUID createAndStartInstance(SessionToken session,
                                      java.util.UUID processTemplateID,
                                      java.net.URI[] rtMgr,
                                      java.net.URI[] stateListener)
                               throws InvalidTemplateStateException,
                                      InvalidDataContainerException

Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance. The process may not have mandatory input or output parameters and is executed normally (in ExecutionMode PRODUCTION). The start node of the created instance is executed internally immediately. This method forwards to createAndStartInstance(SessionToken, UUID, ExecutionContext, URI[], URI[]) whereas the ExecutionContext contains only agent and orgPosition.

Parameters:

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

processTemplateID - The template which is to be instantiated. The template has to be in state INSTANTIABLE for top-level usage.

rtMgr - The runtime manager URIs allowing to autostart the first activity on the designated runtime manager. If autostart is not enabled for the first activity or null is provided, no autostart will occur.

stateListener - The URIs identifying a callback interface to be notified when the top-level instance to be started has changed its state (has been suspended, resumed, finished or failed) or null in case no notification is necessary. The listener has to implement InstanceStateListener.

Returns:

The ID of the created process instance which is unique with respect to the process management system and the server respectively

Throws:

InvalidTemplateStateException - If the process template is not instantiable for top-level usage, an InvalidTemplateStateException will be raised.

InvalidDataContainerException - If the designated process has mandatory input parameters, an InvalidDataContainerException will be raised.

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

See Also:

TemplateStatus.isInstantiable(boolean)

createAndStartInstance

java.util.UUID createAndStartInstance(SessionToken session,
                                      java.util.UUID processTemplateID,
                                      ExecutionContext executionContext,
                                      java.net.URI[] rtMgr,
                                      java.net.URI[] stateListener)
                               throws InvalidTemplateStateException,
                                      InvalidDataContainerException

Creates a new instance of the designated process template, starts the instance and logs the designated user as initiator of the process instance. The start node of the created instance is executed immediately internally and the values of the input parameter provided by the (appropriate) data container are set in the created instance.

Parameters:

session - The session which is used to check for access rights on this method. The starting agent and the corresponding organisational position is retrieved from the execution context!

processTemplateID - The template which is to be instantiated. The template has to be in state INSTANTIABLE for top-level usage.

executionContext - The execution context contains the data container with input and output data of the instance and the execution mode.
The data container can be null in case the process does not have mandatory input parameters. In case of a test mode (SUBSTITUTED_TEST or COMPONENT_TEST) all activities are wrapped in the test environment and the mode is provided to the respective components - if not changed by the user at the corresponding step. Additionally, the ExecutableBusinessProcessInstance are ignored and may therefore be null.

rtMgr - The runtime manager URIs allowing to autostart the first activity on the designated runtime manager. If autostart is not enabled for the first activity or null is provided, no autostart will occur.

stateListener - The URIs identifying a callback interface to be notified when the subprocess instance to be started has changed its state (has been suspended, resumed, finished or failed) or null in case no notification is necessary. The listener has to implement InstanceStateListener.

Returns:

The ID of the created process instance which is unique with respect to the process management system and the server respectively

Throws:

InvalidTemplateStateException - If the process template is not instantiable for top-level usage, an InvalidTemplateStateException will be raised.

InvalidDataContainerException - If the designated process has mandatory input or output parameters that are not incorporated in the designated data container, an InvalidDataContainerException will be raised.

ServiceAccessControlException - if the current user (who owns the session) is not allowed to start an instance of the specified template

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

See Also:

TemplateStatus.isInstantiable(boolean)

createAndStartSubInstance

java.util.UUID createAndStartSubInstance(SessionToken session,
                                         EBPInstanceReference superInstanceActivity,
                                         ExecutionContext executionContext,
                                         java.net.URI[] stateListener)
                                  throws InvalidTemplateStateException,
                                         InvalidDataContainerException

Creates a new instance of the designated process template as a subprocess of the designated activity. The designated initiator (agent and organisational position) is logged.
The start node is set to running and delegated to the subprocess manager. Since the subprocess manager has been delegated the execution of the corresponding activity in the super-process, it knows the input parameters from the super-process and maps this to the output parameters of the start node. Having done the mapping, the subprocess manager normally finishes the start node of the subprocess and returns the data values. Creates a new instance of the designated process template as a subprocess, starts the instance and logs the designated user as initiator of the subprocess instance. The start node of the created instance is executed immediately internally and the values of the input parameter provided by the (appropriate) data container are set in the created instance. When the subprocess completes, the output parameters are written in the same data container. Significant changes of the instance state, for instance, suspending, resuming or aborting the subprocess are reflected in the super-instance.

Parameters:

session - The session which is used to check for access rights on this method. The starting agent and the corresponding organisational position is retrieved from the execution context!

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

executionContext - The execution context identifying the agent creating the subprocess instance, a reference to the light weight process containing the ID of the subprocess template, the data container forwarding the data from the super- to the subprocess and the execution mode.

stateListener - The URIs identifying a callback interface to be notified when the subprocess instance to be started has changed its state (has been suspended, resumed, finished or failed) or null in case no notification is necessary. The listener has to implement either InstanceStateListener or SubInstanceStateListener depending on whether the resumed instance is a top-level or a subprocess.

Returns:

The ID of the created subprocess instance which is unique with respect to the process management system and the server respectively

Throws:

InvalidTemplateStateException - If the process template is not instantiable for subprocess usage, an InvalidTemplateStateException will be raised.

InvalidDataContainerException - If the designated subprocess has mandatory input or output parameters that are not incorporated in the designated data container, an InvalidDataContainerException will be raised.

ServiceAccessControlException - if the current user (who owns the session) is not allowed to start an instance of the specified template

getInstantiableTemplates

java.util.Set<java.util.UUID> getInstantiableTemplates(SessionToken session,
                                                       boolean includeOutdated)

Gets the IDs of all templates that can be instantiated as top-level-processes, that is, they exist in the process manager and they are in the state INSTANTIABLE as top-level processes.

For a non-administrative user, only these templates are returned, which may be started by the qualified agent in the session.

Parameters:

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

includeOutdated - Whether outdated process templates should be included and returned.

Returns:

An set containing all IDs of process templates that exist in the process manager and may be instantiated as top-level processes.

getInstantiableTemplatesIterator

RemoteIterator<java.util.List<java.util.UUID>> getInstantiableTemplatesIterator(SessionToken session,
                                                                                boolean includeOutdated)

The same as getInstantiableTemplates(SessionToken, boolean) but with partial retrieval of the template IDs.

Parameters:

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

includeOutdated - Whether outdated process templates should be included and returned.

Returns:

An iterator providing all IDs of process templates that exist in the process manager and may be instantiated as top-level processes.

getTemplateReference

TemplateReference getTemplateReference(SessionToken session,
                                       java.util.UUID templateID)

Gets the lightweight representation of the designated process template. The requested ID has to be in the set of IDs returned by getInstantiableTemplates(SessionToken, boolean).

Parameters:

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

templateID - The ID of the process template to retrieve the lightweight representation of.

Returns:

The lightweight representation of the designated process template.

Throws:

java.lang.IllegalArgumentException - If the designated template ID is not known or it is not instantiable as top-level-process by the designated user, a IllegalArgumentException will be thrown.

getInstantiableTemplateReferences

java.util.Set<TemplateReference> getInstantiableTemplateReferences(SessionToken session,
                                                                   boolean includeOutdated)

Gets the lightweight representations of all templates that can be instantiated as top-level-processes, that is, they exist in the process manager and they are in the state INSTANTIABLE as top-level processes. Process templates in state OUTDATED will only be recognised if requested.

For a non-administrative user, only the references of the templates are returned, which may be started by the qualified agent in the session.

Parameters:

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

includeOutdated - Whether outdated process templates should be included and returned.

Returns:

An set containing all lightweight representations of process templates that exist in the process manager and may be instantiated as top-level processes.

See Also:

getInstantiableTemplates(SessionToken, boolean)

getInstantiableTemplateReferencesIterator

RemoteIterator<java.util.List<TemplateReference>> getInstantiableTemplateReferencesIterator(SessionToken session,
                                                                                            boolean includeOutdated)

The same as getInstantiableTemplateReferences(SessionToken, boolean) but with partial retrieval of the template references.

Parameters:

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

includeOutdated - Whether outdated process templates should be included and returned.

Returns:

An iterator providing all lightweight representations of process templates that exist in the process manager and may be instantiated as top-level processes.

checkForAndFixInconsistencies

SerialisablePair<java.lang.Boolean,ProcessConstants.InstanceExecutionStatus> checkForAndFixInconsistencies(SessionToken session,
                                                                                                           java.util.UUID instId)
                                                                                                    throws DataConsistencyException

Checks the designated instance for inconsistencies and tries to fix them. If the instance is currently running, it will be reevaluated. Checking requires the execution lock, i. e. this method will lock the instance for execution. Subprocess instances will not be checked. This method cannot ensure that all inconsistencies have been fixed.

Parameters:

session - The session with which to check for and fix inconsistencies in the designated instance. The agent must have the Capabilities.SUPERVISOR_ROLE.

instId - The ID of the instance which to check for inconsistencies and fix them.

Returns:

Whether inconsistencies have been found as well as the execution status of the instance. If this is ProcessConstants.InstanceExecutionStatus.IE_RUNNING, the instance will also be reevaluated. Otherwise reevaluation will take place when resuming the instance.

Throws:

DataConsistencyException - If an inconsistency was found that could not be fixed automatically a DataConsistencyException will be thrown.

suspendInstance

boolean suspendInstance(SessionToken session,
                        java.util.UUID instanceID,
                        boolean propagateToRunningActs)
                 throws InvalidInstanceStateException

Suspends the designated instance and if appropriate also the running activities. In case of a subprocess instance, the super-activity is also suspended. The instance has to be in state IE_RUNNING, IE_SOFTLY_SUSPENDED or IE_SUSPENDED.

Parameters:

session - The session which is used to check for access rights on this method. This can also be used to allow only a dependent session to resume the designated instance. The policy is determined by the corresponding implementation.

instanceID - The ID of the instance to be suspended.

propagateToRunningActs - Whether running activities also should be suspended ( IE_SUSPENDED) or not. This will also propagate to subprocesses if the running nodes refer to subprocesses.

Returns:

Whether all running activities could be suspended; FALSE indicates, that a few activities are still running but as soon as they are finished, the instance does not progress any more.

Throws:

InvalidInstanceStateException - If the process instance is not running or suspended or it is a sub-process instance and its parent instance is not running, softly suspended or softly aborted, an InvalidInstanceStateException will be raised. This will also apply if either is locked for changes.

See Also:

ProcessConstants.InstanceExecutionStatus

resumeInstance

void resumeInstance(SessionToken session,
                    java.util.UUID instanceID)
             throws InvalidInstanceStateException

Resumes the designated (top-level or sub-process) instance and (re-)offers all active (including suspended) activities to the worklist manager. Activities that are subprocesses (including embedded processes) are also resumed. Additionally, the enquiries are sent appropriately to the worklist manager. In case of a subprocess instance, the super-activity is also resumed. The instance has to be in state IE_SUSPENDED or IE_SOFTLY_SUSPENDED.

If the instance has a state listener it will be notified and kept for further notifications. If you need to change the state listener, for instance, when moving a suspended process instance from one execution manager to another one, you will need to use resumeInstance(SessionToken, UUID, URI[]).

Parameters:

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

instanceID - The ID of the instance to be resumed.

Throws:

InvalidInstanceStateException - If the process instance is not suspended or it is a sub-process instance and its parent instance is not running, an InvalidInstanceStateException will be raised. This will also apply if either is locked for changes.

See Also:

ProcessConstants.InstanceExecutionStatus

resumeInstance

void resumeInstance(SessionToken session,
                    java.util.UUID instanceID,
                    java.net.URI[] stateListener)
             throws InvalidInstanceStateException

Resumes the designated (top-level or sub-process) instance and (re-)offers all active (including suspended) activities to the worklist manager. Activities that are subprocesses (including embedded processes) are also resumed. Additionally, the enquiries are sent appropriately to the worklist manager. In case of a subprocess instance, the super-activity is also resumed. The instance has to be in state IE_SUSPENDED or IE_SOFTLY_SUSPENDED.

If the instance already has a state listener it will not be notified and it will be removed from further notifications. The designated state listener will be used instead. But the new one will not receive the current resume.

Parameters:

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

instanceID - The ID of the instance to be resumed.

stateListener - The URIs identifying a callback interface to be notified when the top-level instance to be started has changed its state (has been suspended, resumed, finished or failed). The listener has to implement InstanceStateListener. It will not be notified about the current resume.

Throws:

InvalidInstanceStateException - If the process instance is not suspended or it is a sub-process instance and its parent instance is not running, an InvalidInstanceStateException will be raised. This will also apply if either is locked for changes.

See Also:

ProcessConstants.InstanceExecutionStatus

stopAndAbortInstance

void stopAndAbortInstance(SessionToken session,
                          java.util.UUID instanceID,
                          boolean propagateToRunningActs,
                          java.lang.String errorMessage,
                          java.lang.String state,
                          long errorCode)
                   throws InvalidInstanceStateException

Stops the designated instance and if appropriate also the running activities. In case of a subprocess instance, the super-activity fails. The instance has to be in state IE_RUNNING, IE_SUSPENDED, IE_SOFTLY_SUSPENDED, IE_SOFTLY_ABORTED or IE_ABORTED. Afterwards the instance is in state IE_ABORTED (with propagation to running activities) or IE_SOFTLY_ABORTED (without propagation).
When aborting a subprocess instance, the execution state of the parent instance is relevant. Changing the subprocess instance state requires adapting the state of the corresponding node in the parent instance. This is only allowed if the parent instance is running, softly suspended or softly aborted. Additionally, aborting a subprocess instance may take place for a suspended subprocess instance even if the parent instance is IE_SUSPENDED or IE_ABORTED.

Parameters:

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

instanceID - The ID of the instance to be stopped.

propagateToRunningActs - Whether running activities should also be aborted (IE_ABORTED) or not (IE_SOFTLY_ABORTED). This will also propagate to subprocesses if the running nodes refer to subprocesses.

errorMessage - A human readable description of the reason for the abortion.

state - The state of the caller in which the error occurred that led to the abortion.

errorCode - A code that identifies the reason why the instance should be aborted.

Throws:

InvalidInstanceStateException - If the process instance is not running, suspended or aborted or it is a sub-process instance and its parent instance is not running, softly suspended or softly aborted, an InvalidInstanceStateException will be raised. This will also apply if either is locked for changes.

See Also:

ProcessConstants.InstanceExecutionStatus

prepareCommitInstance

Vote prepareCommitInstance(SessionToken session,
                           java.util.UUID instanceID)
                    throws InvalidInstanceStateException

Prepares the commit of an instance. This method is needed for the 2-phase-commit-protocol. In case of an instance, the preparation pertains mainly to the data elements. The process steps are already committed since the instance has successfully finished and therefore all workflow transactions are committed.
The instance has to be in state IE_FINISHED.

Parameters:

session - The session which is used to check for access rights on this method. This can also be used to allow only a dependent session to commit the designated instance. The policy is determined by the corresponding implementation.

instanceID - The ID of the instance to be committed.

Returns:

Whether the instance can participate in committing or needs to abort.

Throws:

InvalidInstanceStateException - If the process instance is not finished, an InvalidInstanceStateException will be raised.

See Also:

ProcessConstants.InstanceExecutionStatus

commitInstance

void commitInstance(SessionToken session,
                    java.util.UUID instanceID)
             throws InvalidInstanceStateException

Commits the designated instance, that means, the instance is marked as successfully completed. It then may be used for analysis, as a new template,... Committing also indicates that the produced data is fixed and will not be changed any more, analogue to the commit in an SQL-database.
In case of a super-process instance, the subprocess-instances are also committed (by calling the appropriate commit-methods). The instance has to be in state IE_FINISHED.

Parameters:

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

instanceID - The ID of the instance to be committed.

Throws:

InvalidInstanceStateException - If the process instance is not finished, an InvalidInstanceStateException will be raised.

See Also:

ProcessConstants.InstanceExecutionStatus

rollbackInstance

void rollbackInstance(SessionToken session,
                      java.util.UUID instanceID)
               throws InvalidInstanceStateException

Resets the designated instance, which includes rolling back the data and the effects of the instance as a whole. This is different from rolling back single process steps since an instance is not running when rolled back.
In case of a super-process instance, the subprocess-instances are also rolled back (by calling the appropriate rollback-methods). The instance has to be in state IE_FINISHED, IE_ABORTED or IE_SOFTLY_ABORTED.

Parameters:

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

instanceID - The ID of the instance to be committed.

Throws:

InvalidInstanceStateException - If the process instance is not finished or not aborted, an InvalidInstanceStateException will be raised.

See Also:

ProcessConstants.InstanceExecutionStatus