org.jbpm.pvm
Interface Execution

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

ExecutionImpl

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 PvmException 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 node 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_CANCELLED this execution was cancelled with the cancel() method before normal execution ended.
static java.lang.String	STATE_ENDED this execution has ended normally.
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

void	addLog(ProcessLog processLog) adds a log to this execution.
void	cancel() ends this execution and assigns the state STATE_CANCELLED.
Comment	createComment(java.lang.String message) adding a comment.
Execution	createExecution() creates a child path of execution.
Execution	createExecution(java.lang.String name) creates a child path of execution with the given name.
VariableScope	createVariableScope() creates a new variable scope.
VariableScope	createVariableScope(java.util.List<VariableDefinition> variableDefinitions) creates a new variable scope and initialize it according to the given variable definitions.
void	destroyVariableScope() removes the most inner variableScope.
void	end() ends this execution and all of its child executions.
void	end(java.lang.String state) ends this execution and all it's child executions with a user defined status.
void	end(java.lang.String state, boolean remove) ends this execution and all it's child executions with a user defined status.
void	execute(Node node) executes the given node.
void	execute(java.lang.String nodeName) executes the given nested node.
void	fire(java.lang.String eventName, ObservableElement eventSource) fires the event on the given eventSource and then propagates the event up to the eventSource's parent chain.
java.util.List<Comment>	getComments() the list of comments made on this execution.
long	getDbid() the meaningless database primary key
Event	getEvent() the event that is being fired, part of the current position in the process graph.
ObservableElement	getEventSource() the original object that fired the event, part of the current position in the process graph.
java.lang.Exception	getException() the exception in case an exception handler is handling an exception.
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.
<T> T	getExtension(java.lang.Class<T> extensionClass) way to access process language extensions in the execution without having to cast.
java.lang.String	getKey() the meaningful but optional business key that is unique within one process definition.
java.lang.String	getName() the name of this execution.
Node	getNode() the current node indicating the position in the process definition graph.
Execution	getParent() the parent execution in the execution structure.
Node	getPreviousNode() returns the previously executed node only if Node.isPreviousNeeded() is set to true.
Transition	getPreviousTransition() returns the previously taken transition only if Node.isPreviousNeeded() is set to true.
int	getPriority() indicates low priorities with negative values and high priorities with positive values.
ProcessDefinition	getProcessDefinition() the process definition for this execution.
Execution	getProcessInstance() the main path of execution in the execution structure.
java.lang.String	getState() the state of this execution.
Transition	getTransition() the current transition indicating the position in the process definition graph.
java.lang.Object	getVariable(java.lang.String key) retrieves the variable value for the given key.
java.util.Set<java.lang.String>	getVariableKeys() the variable keys for this execution in all visible scopes.
java.util.Map<java.lang.String,java.lang.Object>	getVariables() retrieves all variables, CAUTION : this might be a very costly operation in case you're using database persistence and many variables have to be fetched from the database.
java.util.Iterator<VariableScope>	getVariableScopeIterator() iterates over all variable scopes from inner to outer, including executionScopes on the parent execution chain.
boolean	hasExecution(java.lang.String executionName) indicates if this execution has a child execution with the given executionName
boolean	hasVariable(java.lang.String key) checks presence of the given variable key.
boolean	isActive() is this execution active ?
boolean	isEnded() is this execution ended normally ?
boolean	isFinished() is this execution ended or cancelled ?
boolean	isLocked() is this execution locked ?
boolean	isSuspended() is this execution suspended ?
void	lock(java.lang.String state) makes this execution read-only.
void	move(Node destination) reposition this execution in the destination node.
void	removeExecution(Execution execution) removes the child execution.
void	removeVariable(java.lang.String key) removes the variable with the given key.
void	resume() resumes an execution.
void	setPriority(int priority) setter for the priority.
void	setVariable(java.lang.String key, java.lang.Object value) sets the variable into the most inner matching variable scope.
void	setVariables(java.util.Map<java.lang.String,java.lang.Object> variables) sets all the variable into the most inner matching variable scope.
void	signal() feeds a external trigger into this execution.
void	signal(java.util.Map<java.lang.String,java.lang.Object> parameters) feeds an external trigger into the execution with parameters.
void	signal(java.lang.String signalName) feeds a named external trigger into the execution.
void	signal(java.lang.String signalName, java.util.Map<java.lang.String,java.lang.Object> parameters) feeds a named external trigger into the execution with parameters.
void	suspend() suspends this execution and all it's child executions.
void	take(java.lang.String transitionName) takes the outgoing transition with the given name.
void	take(Transition transition) takes the given outgoing transition.
void	takeDefaultTransition() takes the default transition.
void	unlock() unlocks a locked execution.
void	waitForSignal() makes this execution wait in the current node until an external trigger is given with one of the signal() methods.

Field Detail

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 normally. 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_CANCELLED

static final java.lang.String STATE_CANCELLED

this execution was cancelled with the cancel() method before normal execution 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

Method Detail

getDbid

long getDbid()

the meaningless database primary key

getKey

java.lang.String getKey()

the meaningful but optional 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.

getName

java.lang.String getName()

the name of this execution. The name of a main path of execution is null.

getState

java.lang.String getState()

the state of this execution.

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().

isFinished

boolean isFinished()

is this execution ended or cancelled ?

isEnded

boolean isEnded()

is this execution ended normally ?

isSuspended

boolean isSuspended()

is this execution suspended ?

lock

void lock(java.lang.String state)

makes this execution read-only. All methods that change the state of this execution (incl the fire methods) will throw a PvmException. The only mutable method allowed is unlock().

Throws:

PvmException - when this execution is already locked.

unlock

void unlock()

unlocks a locked execution.

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.

setPriority

void setPriority(int priority)

setter for the priority. 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.

getProcessDefinition

ProcessDefinition getProcessDefinition()

the process definition for this execution.

getNode

Node getNode()

the current node indicating the position in the process definition graph. Can be null in case a transition is being taken.

getTransition

Transition getTransition()

the current transition indicating the position in the process definition graph. Can be null in case this execution is not taking a transition.

getEventSource

ObservableElement getEventSource()

the original object that fired the event, part of the current position in the process graph. Can be null in case no event is being fired. This is mostly the object that is listened to with an Activity, but the eventSource can also be a child of the object to which is listened in case of event propagation.

getEvent

Event getEvent()

the event that is being fired, part of the current position in the process graph. Can be null in case no event is being fired.

getPreviousNode

Node getPreviousNode()

returns the previously executed node only if Node.isPreviousNeeded() is set to true.

getPreviousTransition

Transition getPreviousTransition()

returns the previously taken transition only if Node.isPreviousNeeded() is set to true.

setVariable

void setVariable(java.lang.String key,
                 java.lang.Object value)

sets the variable into the most inner matching variable scope. If no variable scope is present, a new one is created on the process instance. So by default, variables are created in the most outer scope and hence they will be visible for the full process instance. For more about variables and variable scopes, see section variables in the package description.

See Also:

removeVariable(String), getVariableKeys()

setVariables

void setVariables(java.util.Map<java.lang.String,java.lang.Object> variables)

sets all the variable into the most inner matching variable scope. This doesn't replace the variables map, so the current variables for which there is no key in the given variables map are left untouched. Existing variables for which there is a key are overwritten. This method just delegates to setVariable(String, Object) for each entry in the given map. For more about variables and their scopes, see section variables in the package description.

See Also:

setVariable(String,Object), removeVariable(String), getVariableKeys()

getVariable

java.lang.Object getVariable(java.lang.String key)

retrieves the variable value for the given key. If no such key is present null will be returned. Variables can exist and have null as value. Variable lookup will be done according to the variable scoping rules as explained in section variables in the package description.

hasVariable

boolean hasVariable(java.lang.String key)

checks presence of the given variable key. All variable scopes are searched.

removeVariable

void removeVariable(java.lang.String key)

removes the variable with the given key. Lookup of the variable will be done just like in the getVariable(String) method. More can be found in section variables in the package description.

See Also:

setVariable(String, Object)

getVariableKeys

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

the variable keys for this execution in all visible scopes. This method never returns null. If no variables are present, an empty set will be returned.

See Also:

setVariable(String, Object), removeVariable(String)

getVariables

java.util.Map<java.lang.String,java.lang.Object> getVariables()

retrieves all variables, CAUTION : this might be a very costly operation in case you're using database persistence and many variables have to be fetched from the database. This method never returns null. If no variables are present, an empty map will be returned. Changes to the returned map will not lead to updates of the variables in this execution.

signal

void signal()

feeds a external trigger into this execution.

Typically a signal causes the execution to proceed, but that doesn't necessarily has to be the case . The ExternalActivity is responsible for interpreting the signal and acting upon it.

A signal can optionally be given a signal name, a map of parameters or both.

Since it's an external trigger, this method requires that this execution is waiting for an external trigger. So this method must be called as an external client and can not be called while this execution is executing. In an Activity for example you're not allowed to call the signal on the execution cause it is executing. But you are allowed to invoke this method on any other execution (at least, if that one is waiting for an external trigger).

Typically a signal will cause the execution to start executing, but that is not a must. What happens with this signal is defined in the ExternalActivity.signal(Execution, String, Map) of the current node.

See Also:

signal(String)

signal

void signal(java.lang.String signalName)

feeds a named external trigger into the execution.

In each state, a number of things can happen. The signal parameter specifies which of these things is happening. It's somewhat similar to a method name in the invocation of an object.

See Also:

See the unnamed signal for more information

signal

void signal(java.util.Map<java.lang.String,java.lang.Object> parameters)

feeds an external trigger into the execution with parameters.

See Also:

See the unnamed signal for more information

signal

void signal(java.lang.String signalName,
            java.util.Map<java.lang.String,java.lang.Object> parameters)

feeds a named external trigger into the execution with parameters.

In each state, a number of things can happen. The signal parameter specifies which of these things is happening. It's somewhat similar to a method name in the invocation of an object.

The parameters parameter provide extra information to the signal. Typically, the parameters are set as variables but the process language can overwrite that behaviour in the current node. See ExternalActivity.signal(Execution, String, Map) for more information.

See Also:

See the unnamed signal for more information

end

void end()

ends this execution and all of its child executions.

The execution will be removed from it's parent. Potentially this can cause a parent execution to start executing in case this is the last concurrent execution for which the parent is waiting.

This method should not be called in Activitys. It can be called from outside the process execution and in ExternalActivitys.

end

void end(java.lang.String state)

ends this execution and all it's child executions with a user defined status.

It is not recommended to use any of the defined statuses as that may case unpredictable side effects.

The execution will be removed from it's parent.

end

void end(java.lang.String state,
         boolean remove)

ends this execution and all it's child executions with a user defined status.

It is not recommended to use any of the defined statuses as that may case unpredictable side effects.

Parameters:

remove - indicates whether the execution must be removed from its parent.

cancel

void cancel()

ends this execution and assigns the state STATE_CANCELLED.

See Also:

end(String)

suspend

void suspend()

suspends this execution and all it's child executions. Human tasks of a suspended execution shouldn't show up in people's task list and timers of suspended executions shouldn't fire.

Throws:

PvmException - if this execution is already suspended.

resume

void resume()

resumes an execution. Inverse of suspend().

Throws:

PvmException - if this execution is not suspended.

createVariableScope

VariableScope createVariableScope()

creates a new variable scope. Variable scopes are typically managed by the process languages and users should not have to use this method.

createVariableScope

VariableScope createVariableScope(java.util.List<VariableDefinition> variableDefinitions)

creates a new variable scope and initialize it according to the given variable definitions. Variable scopes are typically managed by the process languages and users should not have to use this method.

destroyVariableScope

void destroyVariableScope()

removes the most inner variableScope. Variable scopes are typically managed by the process languages and users should not have to use this method.

getVariableScopeIterator

java.util.Iterator<VariableScope> getVariableScopeIterator()

iterates over all variable scopes from inner to outer, including executionScopes on the parent execution chain. Variable scopes are typically managed by the process languages and users should not have to use this method.

fire

void fire(java.lang.String eventName,
          ObservableElement eventSource)

fires the event on the given eventSource and then propagates the event up to the eventSource's parent chain. All the actions will see the given eventSource in getEventSource(), event if the events are registered to parent's of the given eventSource.

createExecution

Execution createExecution()

creates a child path of execution. This execution will serve as the parent of the newly created execution. When the child execution ends, it will be automatically removed from the list of executions. Creating a child execution implies that this execution will no longer be a leaf in the execution tree. So the state of this execution will automatically set to STATE_INACTIVE when this method is invoked.

createExecution

Execution createExecution(java.lang.String name)

creates a child path of execution with the given name. This execution will serve as the parent of the newly created execution. When the created execution is ended with end() or end(String), then it will be automatically removed from this parent execution. Creating a child execution implies that this execution will no longer be a leaf in the execution tree. So the state of this execution will automatically set to STATE_INACTIVE when this method is invoked.

removeExecution

void removeExecution(Execution execution)

removes the child execution. Even in case the removed execution was the last child execution, the state of this execution will not be changed. It is up to the node implementations to set the state appropriately.

hasExecution

boolean hasExecution(java.lang.String executionName)

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

addLog

void addLog(ProcessLog processLog)

adds a log to this execution.

getExtension

<T> T getExtension(java.lang.Class<T> extensionClass)

way to access process language extensions in the execution without having to cast. Casting can be problematic for persistence.

takeDefaultTransition

void takeDefaultTransition()

takes the default transition.

This method can only be called from inside ExternalActivity implementations and in rare occasions also from outside of the execution (from an external client while the process is in a wait state). For external clients, it is more normal to use the signal() method as in that case, it's the current node (hence the process language)that will decide how to interpret the signal.

Throws:

PvmException - in case there is no default transition in the current node or in case this method is called from inside an Activity

take

void take(java.lang.String transitionName)

takes the outgoing transition with the given name.

This method can only be called from inside ExternalActivity implementations and in rare occasions also from outside of the execution (from an external client while the process is in a wait state). For external clients, it is more normal to use the signal(String) method as in that case, it's the current node (hence the process language)that will decide how to interpret the signal.

Transitions will be looked up recursively starting from the current node and then up the node-parent-hierarchy

Parameters:

transitionName - is the name of the transition to take. A null value will match the first unnamed transition.

Throws:

PvmException - in case no such transition is found in the current node or in case this method is called from inside an Activity.

take

void take(Transition transition)

takes the given outgoing transition.

This method can only be called from inside ExternalActivity implementations and in rare occasions also from outside of the execution (from an external client while the process is in a wait state). For external clients, it is more normal to use the signal(String) method as in that case, it's the current node (hence the process language)that will decide how to interpret the signal.

CAUTION: It's up to the client to make sure that this transition makes sense as there is no check whether the given transition is an outgoing transition of the current node. The motivation for that is that in case of superstates, that check can become too 'expensive'.

execute

void execute(java.lang.String nodeName)

executes the given nested node.

The nodeName is looked up in the current node's nested nodes.

This method can only be called from inside ExternalActivity implementations and in rare occasions also from outside of the execution (from an external client while the process is in a wait state). For external clients, it is more normal to use the signal(String) method as in that case, it's the current node (hence the process language)that will decide how to interpret the signal.

execute

void execute(Node node)

executes the given node.

This method can only be called from inside ExternalActivity implementations and in rare occasions also from outside of the execution (from an external client while the process is in a wait state). For external clients, it is more normal to use the signal(String) method as in that case, it's the current node (hence the process language)that will decide how to interpret the signal.

waitForSignal

void waitForSignal()

makes this execution wait in the current node until an external trigger is given with one of the signal() methods.

move

void move(Node destination)

reposition this execution in the destination node.

createComment

Comment createComment(java.lang.String message)

adding a comment. The actor making this comment is taken from the environment if it is available with Environment.getUserId().

getComments

java.util.List<Comment> getComments()

the list of comments made on this execution.

getException

java.lang.Exception getException()

the exception in case an exception handler is handling an exception.