org.jbpm.api
Interface Execution

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

ActivityExecution, 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_ROOT or STATE_ACTIVE_CONCURRENT then it is locked. A locked execution is read only.

When a new execution is created, it is in STATE_ACTIVE_ROOT. 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. updating variables, updating priority are not considered to change an execution.

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_CONCURRENT concurrent path of execution that is an active indicator of the current position in the diagram.
static java.lang.String	STATE_ACTIVE_ROOT single (non-concurrent) path of execution that is an active indicator of the current position in the diagram.
static java.lang.String	STATE_ASYNC indicates that this execution is doing an asynchronous continuation.
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_CONCURRENT_ROOT parent of concurrent child executions.
static java.lang.String	STATE_INACTIVE_JOIN concurrent execution that is inactively waiting in a join until other concurrent executions arrive.
static java.lang.String	STATE_INACTIVE_SCOPE parent of a scoped execution.
static java.lang.String	STATE_SUSPENDED indicates that this execution is temporary suspended.

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.
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<? extends 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 that is used as a reference in the service methods.
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.
java.lang.String	getProcessDefinitionId() id of the process definition used for this execution
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(java.lang.String activityName) is the given activity active.
boolean	isEnded() is this execution ended
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. Typically this is only a very short period that is not observable thourgh the service interfaces.

See Also:

Constant Field Values

STATE_ACTIVE_ROOT

static final java.lang.String STATE_ACTIVE_ROOT

single (non-concurrent) path of execution that is an active indicator of the current position in the diagram. jBPM can be executing automatic activities or some external entity might be responsible for continuing the execution (wait state for jBPM). An active execution is always a leaf in the execution tree. 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_ACTIVE_CONCURRENT

static final java.lang.String STATE_ACTIVE_CONCURRENT

concurrent path of execution that is an active indicator of the current position in the diagram. The parent of an active concurrent execution is always an inactive concurrent root. jBPM can be executing automatic activities or some external entity might be responsible for continuing the execution (wait state for jBPM). 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_CONCURRENT_ROOT

static final java.lang.String STATE_INACTIVE_CONCURRENT_ROOT

parent of concurrent child executions. 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_INACTIVE_SCOPE

static final java.lang.String STATE_INACTIVE_SCOPE

parent of a scoped execution. This execution is inactive, but points to the parent scope like e.g. a group. This execution has exactly 1 child execution. That indicates the state inside of the scope. 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_JOIN

static final java.lang.String STATE_INACTIVE_JOIN

concurrent execution that is inactively waiting in a join until other concurrent executions arrive. 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. 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_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

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 that is used as a reference in the service methods.

getState

java.lang.String getState()

the state of this execution.

isProcessInstance

boolean isProcessInstance()

is this a process instance

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<? extends 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)

isActive

boolean isActive(java.lang.String activityName)

is the given activity active. This execution and its child executions are searched. If this is a process instance, this means that the whole process instance is searched.

getProcessDefinitionId

java.lang.String getProcessDefinitionId()

id of the process definition used for this execution