org.jbpm.api
Interface Execution

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

ActivityExecution, ClientExecution, ClientProcessInstance, EventListenerExecution, OpenExecution, OpenProcessInstance, ProcessInstance

public interface Execution
extends java.io.Serializable

a runtime path of execution.

State of an execution

The state of an execution is either active or locked. An active execution is either executing or waiting for an external trigger. If an execution is not in STATE_ACTIVE, then it is locked. A locked execution is read only.

When a new execution is created, it is in STATE_ACTIVE. To change the state to a locked state, use #lock(String). Some STATE_* constants are provided that represent the most commonly used locked states. But the state '...' in the picture indicates that any string can be provided as the state in the lock method.

If an execution is locked, methods that change the execution will throw a JbpmException and the message will reference the actual locking state. Firing events, updating variables, updating priority and adding comments are not considered to change an execution. Also creation and removal of child executions are unchecked, which means that those methods can be invoked by external API clients and activity behaviour methods, even while the execution is in a locked state.

Make sure that comparisons between getState() and the STATE_* constants are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

Comments

Author:

Tom Baeyens

Field Summary

static java.lang.String	STATE_ACTIVE either executing or in a wait state waiting for a signal.
static java.lang.String	STATE_ASYNC indicates that this execution is doing an asynchronous continuation.
static java.lang.String	STATE_CANCELLED this execution has been cancelled before it came to completion.
static java.lang.String	STATE_CREATED between creation of a new process instance and the start of that process instance.
static java.lang.String	STATE_ENDED this execution has ended.
static java.lang.String	STATE_INACTIVE parents with concurrent child executions are inactive.
static java.lang.String	STATE_SUSPENDED indicates that this execution is temporary suspended with the #suspend() method.

Method Summary

java.util.Set<java.lang.String>	findActiveActivityNames() get the set of all activities that are active.
Execution	findActiveExecutionIn(java.lang.String activityName) search for an execution that is active and in the given activityName.
java.lang.String	getActivityName() represents the current position in the process by indicating the name of the current activity.
Execution	getExecution(java.lang.String name) the child execution for the given name or null in case such execution doesn't exist.
java.util.Collection<Execution>	getExecutions() the child executions in the execution structure.
java.util.Map<java.lang.String,Execution>	getExecutionsMap() maps child execution names to execution objects.
java.lang.String	getId() a globally unique identifier for this execution.
java.lang.String	getKey() the optional user provided business key that is unique within one process definition.
java.lang.String	getName() the externally given name or id of this execution.
Execution	getParent() the parent execution in the execution structure.
int	getPriority() indicates low priorities with negative values and high priorities with positive values.
Execution	getProcessInstance() the main path of execution in the execution structure.
java.lang.String	getState() the state of this execution.
boolean	hasExecution(java.lang.String executionName) indicates if this execution has a child execution with the given executionName
boolean	isActive() is this execution active ?
boolean	isEnded() is this execution ended
boolean	isLocked() is this execution locked ?
boolean	isProcessInstance() is this a process instance
boolean	isSuspended() is this execution suspended ?

Field Detail

STATE_CREATED

static final java.lang.String STATE_CREATED

between creation of a new process instance and the start of that process instance. The motivation of this state is that variables can be set programmatically on the process instance so that they can be used during initializations of variables and timers

See Also:

Constant Field Values

STATE_ACTIVE

static final java.lang.String STATE_ACTIVE

either executing or in a wait state waiting for a signal. This is the normal state of an execution and the initial state when creating a new execution. Make sure that comparisons are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

See Also:

Constant Field Values

STATE_INACTIVE

static final java.lang.String STATE_INACTIVE

parents with concurrent child executions are inactive. When an execution has concurrent child executions, it implies that this execution can't be active. For example, at a fork, the parent execution can wait inactively in the fork being till all the child executions are joined. Only leaves of the execution tree can be active. Make sure that comparisons are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

See Also:

Constant Field Values

STATE_ENDED

static final java.lang.String STATE_ENDED

this execution has ended. Make sure that comparisons are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

See Also:

Constant Field Values

STATE_SUSPENDED

static final java.lang.String STATE_SUSPENDED

indicates that this execution is temporary suspended with the #suspend() method. Human tasks of a suspended execution shouldn't show up in people's task list and timers of suspended executions shouldn't fire and the execution is locked. Make sure that comparisons are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

See Also:

Constant Field Values

STATE_ASYNC

static final java.lang.String STATE_ASYNC

indicates that this execution is doing an asynchronous continuation.

See Also:

Constant Field Values

STATE_CANCELLED

static final java.lang.String STATE_CANCELLED

this execution has been cancelled before it came to completion. Only history executions might expose this state. This state can be passed in ExecutionService.endProcessInstance(String, String). Make sure that comparisons are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

See Also:

Constant Field Values

Method Detail

getName

java.lang.String getName()

the externally given name or id of this execution. The id of a main path of execution is null. Can be used to differentiate concurrent paths of execution e.g. the shipping and billing paths.

getKey

java.lang.String getKey()

the optional user provided business key that is unique within one process definition. This could be for instance the order number. It's a user defined identifier for one execution within the scope of a single process definition.

getId

java.lang.String getId()

a globally unique identifier for this execution.

getActivityName

java.lang.String getActivityName()

represents the current position in the process by indicating the name of the current activity.

getState

java.lang.String getState()

the state of this execution.

isProcessInstance

boolean isProcessInstance()

is this a process instance

isActive

boolean isActive()

is this execution active ? This is the inverse of isLocked().

isLocked

boolean isLocked()

is this execution locked ? This is the inverse of isActive().

isEnded

boolean isEnded()

is this execution ended

isSuspended

boolean isSuspended()

is this execution suspended ?

getPriority

int getPriority()

indicates low priorities with negative values and high priorities with positive values. The default priority is 0, which means NORMAL. Other recognized named priorities are HIGHEST (2), HIGH (1), LOW (-1) and LOWEST (-2). For the rest, the user can set any other priority integer value, but then, the UI will have to display it as an integer and not the named value.

getProcessInstance

Execution getProcessInstance()

the main path of execution in the execution structure. Null will be returned in case this execution itself is the main execution path.

getParent

Execution getParent()

the parent execution in the execution structure. Null will be returned in case this execution itself is the main execution path.

getExecutions

java.util.Collection<Execution> getExecutions()

the child executions in the execution structure. Can be null and can be an empty collection.

getExecutionsMap

java.util.Map<java.lang.String,Execution> getExecutionsMap()

maps child execution names to execution objects. In case multiple executions have the same name, the first one is taken. Can be null or can be an empty map. The first execution without a name is also included with null as the key.

getExecution

Execution getExecution(java.lang.String name)

the child execution for the given name or null in case such execution doesn't exist.

hasExecution

boolean hasExecution(java.lang.String executionName)

indicates if this execution has a child execution with the given executionName

findActiveExecutionIn

Execution findActiveExecutionIn(java.lang.String activityName)

search for an execution that is active and in the given activityName. Returns null in case there is no such execution.

See Also:

findActiveActivityNames()

findActiveActivityNames

java.util.Set<java.lang.String> findActiveActivityNames()

get the set of all activities that are active. Returns an empty set in case there are no activities active.

See Also:

findActiveExecutionIn(String)