de.aristaflow.adept2.core.executionmanager

Interface ActivityExecutionControl

public interface ActivityExecutionControl

This interface provides methods to control the life cycle of activities after they are started (or resumed).

Author:

Markus Lauer, Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	abortActivity(SessionToken session, EBPInstanceReference activity, java.lang.String errorMessage, long errorCode, boolean force, boolean propagate) Instructs the ActivityExecutionControl to abort the activity and propagate the abortion if appropriate, e. g. to subprocess instances.
java.util.List<java.lang.String>	getSavepoints(SessionToken session, EBPInstanceReference activity) Gets all savepoints and their respective names for the designated activity.
void	resetActivity(SessionToken session, EBPInstanceReference activity, boolean forceReset) Resets the designated activity to its initial state when it is first activated.
void	resetActivity(SessionToken session, EBPInstanceReference activity, boolean forceReset, java.lang.String savepoint) Resets the designated activity to the designated savepoint.
java.lang.String	resetToPrevSavepoint(SessionToken session, EBPInstanceReference activity, boolean forceReset) Resets the designated activity to the previous savepoint.
boolean	suspendActivity(SessionToken session, EBPInstanceReference activity, boolean waitForAcknowledgement, boolean propagate) Instructs the ActivityExecutionControl to suspend the specified activity and propagate the suspension if appropriate, e. g. to subprocess instances.

Method Detail

getSavepoints

java.util.List<java.lang.String> getSavepoints(SessionToken session,
                                               EBPInstanceReference activity)
                                        throws InvalidActivityStateException

Gets all savepoints and their respective names for the designated activity. This allows to reset the activity to a specific savepoint and resume from there.

Parameters:

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

activity - The activity for which to retrieve all known savepoints.

Returns:

All savepoints and their respective names known for the designated activity in the order they have been created. If the activity has not been suspended yet, an empty list will be returned.

Throws:

InvalidActivityStateException - If the activity is neither NS_RUNNING nor NS_SUSPENDED nor NS_SUSPENDED_SUPPR nor NS_FAILED and thus cannot be reset or resumed from a specific savepoint, an InvalidActivityStateException is thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

ProcessConstants.NodeState

suspendActivity

boolean suspendActivity(SessionToken session,
                        EBPInstanceReference activity,
                        boolean waitForAcknowledgement,
                        boolean propagate)
                 throws InvalidActivityStateException

Instructs the ActivityExecutionControl to suspend the specified activity and propagate the suspension if appropriate, e. g. to subprocess instances.

By the parameter waitForAcknowledgement you can specify if the method should return not until the referenced EBP has acknowledged its suspension or if it should return at once.
Be aware: It may last some time until the activity is suspended!

Parameters:

session - The session the call is associated with.

activity - the activity to suspend.

waitForAcknowledgement - Should the method return not until the activity has acknowledged its suspension (TRUE) or should it return at once (FALSE).

propagate - Whether to propagate the suspension if appropriate, e. g. to subprocess instances.

Returns:

Returns whether the activity has been successfully suspended in case of waiting for the acknowledgement. If the abortion timeout of the execution manager elapses before or if no waiting should take place, false will be returned.

Throws:

InvalidActivityStateException - If the activity is in a state it cannot be suspended or can not be suspended at all an InvalidActivityStateException is thrown.

resetActivity

void resetActivity(SessionToken session,
                   EBPInstanceReference activity,
                   boolean forceReset)
            throws InvalidActivityStateException,
                   InvalidInstanceStateException

Resets the designated activity to its initial state when it is first activated. That is the current state is dropped and the node is re-activated. Resetting is logged in the execution history, and produced data will also be logged but invalidated.
Resetting may only take place for running, suspended or failed activities. A running activity is tried to suspend (with propagation). If the activity does not support this or the suspension does not work, the activity will be aborted (with propagation). If this is also not supported, an InvalidActivityStateException will be thrown.
However, the exception will not be thrown if the reset is forced. In this case the activity is just set to failed in the process instance without affecting the current execution. This execution will then fail since the state has changed server-side only.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_RUNNING, NS_SUSPENDED, NS_SUSPENDED_SUPPR or NS_FAILED). If the reset is not forced it will also have to support reset, and suspend.

It has to be assured that this method is only called by supervising agents. Normal users will be able to reset activities if the activity supports it via ActivityTermination.activityReset(SessionToken, EBPInstanceReference).

Parameters:

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

activity - The reference identifying the activity to reset. It does not need to have a valid runtime manager URI since this needs to be taken from the corresponding instance.

forceReset - Whether the reset is forced, that is the activity has to be suspended or aborted (and reset afterwards) under all circumstances.

Throws:

InvalidActivityStateException - If the reset is not forced and the activity (process step) is not resettable or not running, suspended or failed, an InvalidActivityStateException will be raised. This also applies to running activities that do not support suspension nor abortion.

InvalidInstanceStateException - If the instance is not running but stopped, (hard) aborted, finished or changed, an InvalidInstanceStateException is thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

resetActivity(SessionToken, EBPInstanceReference, boolean, String), ProcessConstants.NodeState

resetActivity

void resetActivity(SessionToken session,
                   EBPInstanceReference activity,
                   boolean forceReset,
                   java.lang.String savepoint)
            throws InvalidActivityStateException,
                   InvalidInstanceStateException

Resets the designated activity to the designated savepoint. That is, the latest states are dropped back to the designated savepoint and the node will be suspended. If no savepoint is provided, the activity will reset to its initial state and therefore re-activated. Resetting is logged in the execution history, and produced data will be invalidated back to the designated savepoint.
Resetting may only take place for running, suspended or failed activities. A running activity is tried to suspend (with propagation). If the activity does not support this or the suspension does not work, the activity will be aborted (with propagation). If this is also not supported, an InvalidActivityStateException will be thrown.
However, the exception will not be thrown if the reset is forced. In this case the activity is just set to failed in the process instance without affecting the current execution. This execution will then fail since the state has changed server-side only.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_RUNNING, NS_SUSPENDED, NS_SUSPENDED_SUPPR or NS_FAILED). If the reset is not forced it will also have to support reset, and suspend.

It has to be assured that this method is only called by supervising agents. Normal users will be able to reset activities if the activity supports it via ActivityTermination.activityReset(SessionToken, EBPInstanceReference).

Parameters:

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

activity - The reference identifying the activity to reset. It does not need to have a valid runtime manager URI since this needs to be taken from the corresponding instance.

forceReset - Whether the reset is forced, that is the activity has to be suspended or aborted (and reset afterwards) under all circumstances.

savepoint - The ID of the savepoint to which to reset. The activity will be resumed from this savepoint. Use null to reset the activity to its initial state.

Throws:

InvalidActivityStateException - If

• the reset is not forced and the activity (process step) is not resettable or not running, suspended or failed or
• the designated activity does not have the designated savepoint

, an InvalidActivityStateException will be raised. This also applies to running activities that do not support suspension nor abortion.

InvalidInstanceStateException - If the instance is not running but stopped, (hard) aborted, finished or changed, an InvalidInstanceStateException is thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

resetActivity(SessionToken, EBPInstanceReference, boolean), ProcessConstants.NodeState

resetToPrevSavepoint

java.lang.String resetToPrevSavepoint(SessionToken session,
                                      EBPInstanceReference activity,
                                      boolean forceReset)
                               throws InvalidActivityStateException,
                                      InvalidInstanceStateException

Resets the designated activity to the previous savepoint. That is, if the activity is running or failed, it will be reset to the last savepoint (usually the one the activity has been suspended the last time). If the activity is currently suspended, it will be reset to the savepoint of the previous suspension. Resetting is logged in the execution history, and produced data will be invalidated back to the designated savepoint.
Resetting may only take place for running, suspended or failed activities. A running activity is tried to suspend (with propagation). If the activity does not support this or the suspension does not work, the activity will be aborted (with propagation). If this is also not supported, an InvalidActivityStateException will be thrown.
However, the exception will not be thrown if the reset is forced. In this case the activity is just set to failed in the process instance without affecting the current execution. This execution will then fail since the state has changed server-side only.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_RUNNING, NS_SUSPENDED, NS_SUSPENDED_SUPPR or NS_FAILED). If the reset is not forced it will also have to support reset, and suspend.

It has to be assured that this method is only called by supervising agents. Normal users will be able to reset activities if the activity supports it via ActivityTermination.activityReset(SessionToken, EBPInstanceReference).

Parameters:

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

activity - The reference identifying the activity to reset. It does not need to have a valid runtime manager URI since this needs to be taken from the corresponding instance.

forceReset - Whether the reset is forced, that is the activity has to be suspended or aborted (and reset afterwards) under all circumstances.

Returns:

The name of the savepoint to which the activity has been reset. null indicates resetting to the initial state.

Throws:

InvalidActivityStateException - If

• the reset is not forced and the activity (process step) is not resettable or not running, suspended or failed or
• the designated activity does not have the designated savepoint

, an InvalidActivityStateException will be raised. This also applies to running activities that do not support suspension nor abortion.

InvalidInstanceStateException - If the instance is not running but stopped, (hard) aborted, finished or changed, an InvalidInstanceStateException is thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

resetActivity(SessionToken, EBPInstanceReference, boolean), ProcessConstants.NodeState

abortActivity

void abortActivity(SessionToken session,
                   EBPInstanceReference activity,
                   java.lang.String errorMessage,
                   long errorCode,
                   boolean force,
                   boolean propagate)
            throws InvalidActivityStateException

Instructs the ActivityExecutionControl to abort the activity and propagate the abortion if appropriate, e. g. to subprocess instances.

By the parameter force you can specify to wait until the abortion was successful. If this does not happen, the activity will be set to failed without respecting its current state (in its runtime manager).

Parameters:

session - The session the call is associated with.

activity - the activity to abort

errorMessage - a human readable message explaining the error that led to the abortion.

errorCode - the code of the error that led to the abortion.

force - Whether the activity is to be aborted independent from whether it allows this and reacts to this.

propagate - Whether to propagate the abortion if appropriate, e. g. to subprocess instances.

Throws:

InvalidActivityStateException - If the activity is in a state it cannot be aborted or it can not be aborted at all and the abortion is not forced, an InvalidActivityStateException is thrown.