org.camunda.bpm.engine.impl

Class RuntimeServiceImpl

java.lang.Object

org.camunda.bpm.engine.impl.ServiceImpl

org.camunda.bpm.engine.impl.RuntimeServiceImpl

All Implemented Interfaces:

RuntimeService

public class RuntimeServiceImpl
extends ServiceImpl
implements RuntimeService

Author:

Tom Baeyens, Daniel Meyer

Field Summary

Fields inherited from class org.camunda.bpm.engine.impl.ServiceImpl

commandExecutor

Constructor Summary

Constructors

Constructor and Description
RuntimeServiceImpl()

Method Summary

Methods

Modifier and Type	Method and Description
void	activateProcessInstanceById(String processInstanceId) Activates the process instance with the given id.
void	activateProcessInstanceByProcessDefinitionId(String processDefinitionId) Activates the process instance with the given process definition id.
void	activateProcessInstanceByProcessDefinitionKey(String processDefinitionKey) Activates the process instance with the given process definition key.
void	correlateMessage(String messageName) Correlates a message to either an execution that is waiting for this message or a process definition that can be started by this message.
void	correlateMessage(String messageName, Map<String,Object> correlationKeys) Correlates a message to an execution that is waiting for this message and can be correlated according to the given correlation keys.
void	correlateMessage(String messageName, Map<String,Object> correlationKeys, Map<String,Object> processVariables) Correlates a message to an execution that is waiting for this message and can be correlated according to the given correlation keys.
void	correlateMessage(String messageName, String businessKey) Correlates a message to an execution that is waiting for this message and belongs to a process instance with the given business key a process definition that can be started by this message.
void	correlateMessage(String messageName, String businessKey, Map<String,Object> processVariables) Correlates a message to an execution that is waiting for this message and belongs to a process instance with the given business key a process definition that can be started by this message.
void	correlateMessage(String messageName, String businessKey, Map<String,Object> correlationKeys, Map<String,Object> processVariables) Correlates a message to an execution that is waiting for this message and can be correlated according to the given correlation keys.
EventSubscriptionQuery	createEventSubscriptionQuery() Creates a new EventSubscriptionQuery instance, that can be used to query event subscriptions.
ExecutionQuery	createExecutionQuery() Creates a new ExecutionQuery instance, that can be used to query the executions and process instances.
IncidentQuery	createIncidentQuery() Creates a new IncidentQuery instance, that can be used to query incidents.
MessageCorrelationBuilder	createMessageCorrelation(String messageName) Define a complex message correlation using a fluent builder.
NativeExecutionQuery	createNativeExecutionQuery() creates a new NativeExecutionQuery to query Executions by SQL directly
NativeProcessInstanceQuery	createNativeProcessInstanceQuery() creates a new NativeProcessInstanceQuery to query ProcessInstances by SQL directly
ProcessInstanceQuery	createProcessInstanceQuery() Creates a new ProcessInstanceQuery instance, that can be used to query process instances.
VariableInstanceQuery	createVariableInstanceQuery() Creates a new VariableInstanceQuery instance, that can be used to query variable instances.
void	deleteProcessInstance(String processInstanceId, String deleteReason) Delete an existing runtime process instance.
List<String>	getActiveActivityIds(String executionId) Finds the activity ids for all executions that are waiting in activities.
ActivityInstance	getActivityInstance(String processInstanceId) Allows retrieving the activity instance tree for a given process instance.
FormData	getFormInstanceById(String processDefinitionId)
Object	getVariable(String executionId, String variableName) The variable value.
Object	getVariableLocal(String executionId, String variableName) The variable value for an execution.
Map<String,Object>	getVariables(String executionId) All variables visible from the given execution scope (including parent scopes).
Map<String,Object>	getVariables(String executionId, Collection<String> variableNames) The variable values for all given variableNames, takes all variables into account which are visible from the given execution scope (including parent scopes).
Map<String,Object>	getVariablesLocal(String executionId) All variable values that are defined in the execution scope, without taking outer scopes into account.
Map<String,Object>	getVariablesLocal(String executionId, Collection<String> variableNames) The variable values for the given variableNames only taking the given execution scope into account, not looking in outer scopes.
void	messageEventReceived(String messageName, String executionId) Notifies the process engine that a message event with name 'messageName' has been received and has been correlated to an execution with id 'executionId'.
void	messageEventReceived(String messageName, String executionId, Map<String,Object> processVariables) Notifies the process engine that a message event with the name 'messageName' has been received and has been correlated to an execution with id 'executionId'.
void	removeVariable(String executionId, String variableName) Removes a variable for an execution.
void	removeVariableLocal(String executionId, String variableName) Removes a variable for an execution (not considering parent scopes).
void	removeVariables(String executionId, Collection<String> variableNames) Removes variables for an execution.
void	removeVariablesLocal(String executionId, Collection<String> variableNames) Remove variables for an execution (not considering parent scopes).
void	setVariable(String executionId, String variableName, Object value) Update or create a variable for an execution.
void	setVariableLocal(String executionId, String variableName, Object value) Update or create a variable for an execution (not considering parent scopes).
void	setVariables(String executionId, Map<String,? extends Object> variables) Update or create given variables for an execution (including parent scopes).
void	setVariablesLocal(String executionId, Map<String,? extends Object> variables) Update or create given variables for an execution (not considering parent scopes).
void	signal(String executionId) Sends an external trigger to an activity instance that is waiting inside the given execution.
void	signal(String executionId, Map<String,Object> processVariables) Sends an external trigger to an activity instance that is waiting inside the given execution.
void	signal(String executionId, String signalName, Object signalData, Map<String,Object> processVariables) Sends an external trigger to an activity instance that is waiting inside the given execution.
void	signalEventReceived(String signalName) Notifies the process engine that a signal event of name 'signalName' has been received.
void	signalEventReceived(String signalName, Map<String,Object> processVariables) Notifies the process engine that a signal event of name 'signalName' has been received.
void	signalEventReceived(String signalName, String executionId) Notifies the process engine that a signal event of name 'signalName' has been received.
void	signalEventReceived(String signalName, String executionId, Map<String,Object> processVariables) Notifies the process engine that a signal event of name 'signalName' has been received.
ProcessInstance	startProcessInstanceById(String processDefinitionId) Starts a new process instance in the exactly specified version of the process definition with the given id.
ProcessInstance	startProcessInstanceById(String processDefinitionId, Map<String,Object> variables) Starts a new process instance in the exactly specified version of the process definition with the given id.
ProcessInstance	startProcessInstanceById(String processDefinitionId, String businessKey) Starts a new process instance in the exactly specified version of the process definition with the given id.
ProcessInstance	startProcessInstanceById(String processDefinitionId, String businessKey, Map<String,Object> variables) Starts a new process instance in the exactly specified version of the process definition with the given id.
ProcessInstance	startProcessInstanceByKey(String processDefinitionKey) Starts a new process instance in the latest version of the process definition with the given key.
ProcessInstance	startProcessInstanceByKey(String processDefinitionKey, Map<String,Object> variables) Starts a new process instance in the latest version of the process definition with the given key
ProcessInstance	startProcessInstanceByKey(String processDefinitionKey, String businessKey) Starts a new process instance in the latest version of the process definition with the given key.
ProcessInstance	startProcessInstanceByKey(String processDefinitionKey, String businessKey, Map<String,Object> variables) Starts a new process instance in the latest version of the process definition with the given key.
ProcessInstance	startProcessInstanceByMessage(String messageName) Signals the process engine that a message is received and starts a new ProcessInstance.
ProcessInstance	startProcessInstanceByMessage(String messageName, Map<String,Object> processVariables) Signals the process engine that a message is received and starts a new ProcessInstance.
ProcessInstance	startProcessInstanceByMessage(String messageName, String businessKey) Signals the process engine that a message is received and starts a new ProcessInstance.
ProcessInstance	startProcessInstanceByMessage(String messageName, String businessKey, Map<String,Object> processVariables) Signals the process engine that a message is received and starts a new ProcessInstance.
void	suspendProcessInstanceById(String processInstanceId) Suspends the process instance with the given id.
void	suspendProcessInstanceByProcessDefinitionId(String processDefinitionId) Suspends the process instances with the given process definition id.
void	suspendProcessInstanceByProcessDefinitionKey(String processDefinitionKey) Suspends the process instances with the given process definition key.
void	updateVariables(String executionId, Map<String,? extends Object> modifications, Collection<String> deletions)
void	updateVariablesLocal(String executionId, Map<String,? extends Object> modifications, Collection<String> deletions)

Methods inherited from class org.camunda.bpm.engine.impl.ServiceImpl

getCommandExecutor, setCommandExecutor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RuntimeServiceImpl

public RuntimeServiceImpl()

Method Detail

startProcessInstanceByKey

public ProcessInstance startProcessInstanceByKey(String processDefinitionKey)

Description copied from interface: RuntimeService

Starts a new process instance in the latest version of the process definition with the given key.

Specified by:

startProcessInstanceByKey in interface RuntimeService

Parameters:

processDefinitionKey - key of process definition, cannot be null.

startProcessInstanceByKey

public ProcessInstance startProcessInstanceByKey(String processDefinitionKey,
                                        String businessKey)

Description copied from interface: RuntimeService

Starts a new process instance in the latest version of the process definition with the given key. A business key can be provided to associate the process instance with a certain identifier that has a clear business meaning. For example in an order process, the business key could be an order id. This business key can then be used to easily look up that process instance , see ProcessInstanceQuery.processInstanceBusinessKey(String). Providing such a business key is definitely a best practice. Note that a business key MUST be unique for the given process definition WHEN you have added a database constraint for it. In this case, only Process instance from different process definition are allowed to have the same business key and the combination of processdefinitionKey-businessKey must be unique.

Specified by:

startProcessInstanceByKey in interface RuntimeService

Parameters:

processDefinitionKey - key of process definition, cannot be null.

businessKey - a key that uniquely identifies the process instance in the context of the given process definition.

startProcessInstanceByKey

public ProcessInstance startProcessInstanceByKey(String processDefinitionKey,
                                        Map<String,Object> variables)

Description copied from interface: RuntimeService

Starts a new process instance in the latest version of the process definition with the given key

Specified by:

startProcessInstanceByKey in interface RuntimeService

Parameters:

processDefinitionKey - key of process definition, cannot be null.

variables - the variables to pass, can be null.

startProcessInstanceByKey

public ProcessInstance startProcessInstanceByKey(String processDefinitionKey,
                                        String businessKey,
                                        Map<String,Object> variables)

Description copied from interface: RuntimeService

Starts a new process instance in the latest version of the process definition with the given key. A business key can be provided to associate the process instance with a certain identifier that has a clear business meaning. For example in an order process, the business key could be an order id. This business key can then be used to easily look up that process instance , see ProcessInstanceQuery.processInstanceBusinessKey(String). Providing such a business key is definitely a best practice. Note that a business key MUST be unique for the given process definition WHEN you have added a database constraint for it. In this case, only Process instance from different process definition are allowed to have the same business key and the combination of processdefinitionKey-businessKey must be unique. The combination of processdefinitionKey-businessKey must be unique.

Specified by:

startProcessInstanceByKey in interface RuntimeService

Parameters:

processDefinitionKey - key of process definition, cannot be null.

businessKey - a key that uniquely identifies the process instance in the context of the given process definition.

variables - the variables to pass, can be null.

startProcessInstanceById

public ProcessInstance startProcessInstanceById(String processDefinitionId)

Description copied from interface: RuntimeService

Starts a new process instance in the exactly specified version of the process definition with the given id.

Specified by:

startProcessInstanceById in interface RuntimeService

Parameters:

processDefinitionId - the id of the process definition, cannot be null.

startProcessInstanceById

public ProcessInstance startProcessInstanceById(String processDefinitionId,
                                       String businessKey)

Description copied from interface: RuntimeService

Starts a new process instance in the exactly specified version of the process definition with the given id. A business key can be provided to associate the process instance with a certain identifier that has a clear business meaning. For example in an order process, the business key could be an order id. This business key can then be used to easily look up that process instance , see ProcessInstanceQuery.processInstanceBusinessKey(String). Providing such a business key is definitely a best practice. Note that a business key MUST be unique for the given process definition WHEN you have added a database constraint for it. In this case, only Process instance from different process definition are allowed to have the same business key and the combination of processdefinitionKey-businessKey must be unique.

Specified by:

startProcessInstanceById in interface RuntimeService

Parameters:

processDefinitionId - the id of the process definition, cannot be null.

businessKey - a key that uniquely identifies the process instance in the context of the given process definition.

startProcessInstanceById

public ProcessInstance startProcessInstanceById(String processDefinitionId,
                                       Map<String,Object> variables)

Description copied from interface: RuntimeService

Starts a new process instance in the exactly specified version of the process definition with the given id.

Specified by:

startProcessInstanceById in interface RuntimeService

Parameters:

processDefinitionId - the id of the process definition, cannot be null.

variables - variables to be passed, can be null

startProcessInstanceById

public ProcessInstance startProcessInstanceById(String processDefinitionId,
                                       String businessKey,
                                       Map<String,Object> variables)

Description copied from interface: RuntimeService

Starts a new process instance in the exactly specified version of the process definition with the given id. A business key can be provided to associate the process instance with a certain identifier that has a clear business meaning. For example in an order process, the business key could be an order id. This business key can then be used to easily look up that process instance , see ProcessInstanceQuery.processInstanceBusinessKey(String). Providing such a business key is definitely a best practice. Note that a business key MUST be unique for the given process definition WHEN you have added a database constraint for it. In this case, only Process instance from different process definition are allowed to have the same business key and the combination of processdefinitionKey-businessKey must be unique.

Specified by:

startProcessInstanceById in interface RuntimeService

Parameters:

processDefinitionId - the id of the process definition, cannot be null.

businessKey - a key that uniquely identifies the process instance in the context of the given process definition.

variables - variables to be passed, can be null

deleteProcessInstance

public void deleteProcessInstance(String processInstanceId,
                         String deleteReason)

Description copied from interface: RuntimeService

Delete an existing runtime process instance.

Specified by:

deleteProcessInstance in interface RuntimeService

Parameters:

processInstanceId - id of process instance to delete, cannot be null.

deleteReason - reason for deleting, which will be stored in the history. Can be null.

createExecutionQuery

public ExecutionQuery createExecutionQuery()

Description copied from interface: RuntimeService

Creates a new ExecutionQuery instance, that can be used to query the executions and process instances.

Specified by:

createExecutionQuery in interface RuntimeService

createNativeExecutionQuery

public NativeExecutionQuery createNativeExecutionQuery()

Description copied from interface: RuntimeService

creates a new NativeExecutionQuery to query Executions by SQL directly

Specified by:

createNativeExecutionQuery in interface RuntimeService

createNativeProcessInstanceQuery

public NativeProcessInstanceQuery createNativeProcessInstanceQuery()

Description copied from interface: RuntimeService

creates a new NativeProcessInstanceQuery to query ProcessInstances by SQL directly

Specified by:

createNativeProcessInstanceQuery in interface RuntimeService

createIncidentQuery

public IncidentQuery createIncidentQuery()

Description copied from interface: RuntimeService

Creates a new IncidentQuery instance, that can be used to query incidents.

Specified by:

createIncidentQuery in interface RuntimeService

createEventSubscriptionQuery

public EventSubscriptionQuery createEventSubscriptionQuery()

Description copied from interface: RuntimeService

Creates a new EventSubscriptionQuery instance, that can be used to query event subscriptions.

Specified by:

createEventSubscriptionQuery in interface RuntimeService

createVariableInstanceQuery

public VariableInstanceQuery createVariableInstanceQuery()

Description copied from interface: RuntimeService

Creates a new VariableInstanceQuery instance, that can be used to query variable instances.

Specified by:

createVariableInstanceQuery in interface RuntimeService

getVariables

public Map<String,Object> getVariables(String executionId)

Description copied from interface: RuntimeService

All variables visible from the given execution scope (including parent scopes).

Specified by:

getVariables in interface RuntimeService

Parameters:

executionId - id of process instance or execution, cannot be null.

Returns:

the variables or an empty map if no such variables are found.

getVariablesLocal

public Map<String,Object> getVariablesLocal(String executionId)

Description copied from interface: RuntimeService

All variable values that are defined in the execution scope, without taking outer scopes into account. If you have many task local variables and you only need a few, consider using RuntimeService.getVariablesLocal(String, Collection) for better performance.

Specified by:

getVariablesLocal in interface RuntimeService

Parameters:

executionId - id of execution, cannot be null.

Returns:

the variables or an empty map if no such variables are found.

getVariables

public Map<String,Object> getVariables(String executionId,
                              Collection<String> variableNames)

Description copied from interface: RuntimeService

The variable values for all given variableNames, takes all variables into account which are visible from the given execution scope (including parent scopes).

Specified by:

getVariables in interface RuntimeService

Parameters:

executionId - id of process instance or execution, cannot be null.

variableNames - the collection of variable names that should be retrieved.

Returns:

the variables or an empty map if no such variables are found.

getVariablesLocal

public Map<String,Object> getVariablesLocal(String executionId,
                                   Collection<String> variableNames)

Description copied from interface: RuntimeService

The variable values for the given variableNames only taking the given execution scope into account, not looking in outer scopes.

Specified by:

getVariablesLocal in interface RuntimeService

Parameters:

executionId - id of execution, cannot be null.

variableNames - the collection of variable names that should be retrieved.

Returns:

the variables or an empty map if no such variables are found.

getVariable

public Object getVariable(String executionId,
                 String variableName)

Description copied from interface: RuntimeService

The variable value. Searching for the variable is done in all scopes that are visible to the given execution (including parent scopes). Returns null when no variable value is found with the given name or when the value is set to null.

Specified by:

getVariable in interface RuntimeService

Parameters:

executionId - id of process instance or execution, cannot be null.

variableName - name of variable, cannot be null.

Returns:

the variable value or null if the variable is undefined or the value of the variable is null.

getVariableLocal

public Object getVariableLocal(String executionId,
                      String variableName)

Description copied from interface: RuntimeService

The variable value for an execution. Returns the value when the variable is set for the execution (and not searching parent scopes). Returns null when no variable value is found with the given name or when the value is set to null.

Specified by:

getVariableLocal in interface RuntimeService

setVariable

public void setVariable(String executionId,
               String variableName,
               Object value)

Description copied from interface: RuntimeService

Update or create a variable for an execution. If the variable is not already existing somewhere in the execution hierarchy, it will be created in the process instance (which is the root execution).

Specified by:

setVariable in interface RuntimeService

Parameters:

executionId - id of process instance or execution to set variable in, cannot be null.

variableName - name of variable to set, cannot be null.

value - value to set. When null is passed, the variable is not removed, only it's value will be set to null.

setVariableLocal

public void setVariableLocal(String executionId,
                    String variableName,
                    Object value)

Description copied from interface: RuntimeService

Update or create a variable for an execution (not considering parent scopes). If the variable is not already existing, it will be created in the given execution.

Specified by:

setVariableLocal in interface RuntimeService

Parameters:

executionId - id of execution to set variable in, cannot be null.

variableName - name of variable to set, cannot be null.

value - value to set. When null is passed, the variable is not removed, only it's value will be set to null.

setVariables

public void setVariables(String executionId,
                Map<String,? extends Object> variables)

Description copied from interface: RuntimeService

Update or create given variables for an execution (including parent scopes). If the variables are not already existing, they will be created in the process instance (which is the root execution).

Specified by:

setVariables in interface RuntimeService

Parameters:

executionId - id of the process instance or the execution, cannot be null.

variables - map containing name (key) and value of variables, can be null.

setVariablesLocal

public void setVariablesLocal(String executionId,
                     Map<String,? extends Object> variables)

Description copied from interface: RuntimeService

Update or create given variables for an execution (not considering parent scopes). If the variables are not already existing, it will be created in the given execution.

Specified by:

setVariablesLocal in interface RuntimeService

Parameters:

executionId - id of the execution, cannot be null.

variables - map containing name (key) and value of variables, can be null.

removeVariable

public void removeVariable(String executionId,
                  String variableName)

Description copied from interface: RuntimeService

Removes a variable for an execution.

Specified by:

removeVariable in interface RuntimeService

Parameters:

executionId - id of process instance or execution to remove variable in.

variableName - name of variable to remove.

removeVariableLocal

public void removeVariableLocal(String executionId,
                       String variableName)

Description copied from interface: RuntimeService

Removes a variable for an execution (not considering parent scopes).

Specified by:

removeVariableLocal in interface RuntimeService

Parameters:

executionId - id of execution to remove variable in.

variableName - name of variable to remove.

removeVariables

public void removeVariables(String executionId,
                   Collection<String> variableNames)

Description copied from interface: RuntimeService

Removes variables for an execution.

Specified by:

removeVariables in interface RuntimeService

Parameters:

executionId - id of process instance or execution to remove variable in.

variableNames - collection containing name of variables to remove.

removeVariablesLocal

public void removeVariablesLocal(String executionId,
                        Collection<String> variableNames)

Description copied from interface: RuntimeService

Remove variables for an execution (not considering parent scopes).

Specified by:

removeVariablesLocal in interface RuntimeService

Parameters:

executionId - id of execution to remove variable in.

variableNames - collection containing name of variables to remove.

updateVariables

public void updateVariables(String executionId,
                   Map<String,? extends Object> modifications,
                   Collection<String> deletions)

updateVariablesLocal

public void updateVariablesLocal(String executionId,
                        Map<String,? extends Object> modifications,
                        Collection<String> deletions)

signal

public void signal(String executionId)

Description copied from interface: RuntimeService

Sends an external trigger to an activity instance that is waiting inside the given execution. Note that you need to provide the exact execution that is waiting for the signal if the process instance contains multiple executions.

Specified by:

signal in interface RuntimeService

Parameters:

executionId - id of process instance or execution to signal, cannot be null.

signal

public void signal(String executionId,
          String signalName,
          Object signalData,
          Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Sends an external trigger to an activity instance that is waiting inside the given execution. Note that you need to provide the exact execution that is waiting for the signal if the process instance contains multiple executions.

Specified by:

signal in interface RuntimeService

Parameters:

executionId - id of process instance or execution to signal, cannot be null.

signalName - name of the signal (can be null)

signalData - additional data of the signal (can be null)

processVariables - a map of process variables (can be null)

signal

public void signal(String executionId,
          Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Sends an external trigger to an activity instance that is waiting inside the given execution. Note that you need to provide the exact execution that is waiting for the signal if the process instance contains multiple executions.

Specified by:

signal in interface RuntimeService

Parameters:

executionId - id of process instance or execution to signal, cannot be null.

processVariables - a map of process variables

createProcessInstanceQuery

public ProcessInstanceQuery createProcessInstanceQuery()

Description copied from interface: RuntimeService

Creates a new ProcessInstanceQuery instance, that can be used to query process instances.

Specified by:

createProcessInstanceQuery in interface RuntimeService

getActiveActivityIds

public List<String> getActiveActivityIds(String executionId)

Description copied from interface: RuntimeService

Finds the activity ids for all executions that are waiting in activities. This is a list because a single activity can be active multiple times.

Specified by:

getActiveActivityIds in interface RuntimeService

Parameters:

executionId - id of the process instance or the execution, cannot be null.

getActivityInstance

public ActivityInstance getActivityInstance(String processInstanceId)

Description copied from interface: RuntimeService

Allows retrieving the activity instance tree for a given process instance. The activity instance tree is aligned with the concept of scope in the BPMN specification. Activities that are "on the same level of subprocess" (ie. part of the same scope, contained in the same subprocess) will have their activity instances at the same level in the tree.

Examples:

• Process with two parallel user tasks after parallel Gateway: in the activity instance tree you will see two activity instances below the root instance, one for each user task.
• Process with two parallel Multi Instance user tasks after parallel Gateway: in the activity instance tree, all instances of both user tasks will be listed below the root activity instance. Reason: all activity instances are at the same level of subprocess.
• Usertask inside embedded subprocess: the activity instance three will have 3 levels: the root instance representing the process instance itself, below it an activity instance representing the instance of the embedded subprocess, and below this one, the activity instance representing the usertask.

Identity & Uniqueness:

Each activity instance is assigned a unique Id. The id is persistent, if you invoke this method multiple times, the same activity instance ids will be returned for the same activity instances. (However, there might be different executions assigned, see below)

Relation to Executions

The Execution concept in the process engine is not completely aligned with the activity instance concept because the execution tree is in general not aligned with the activity / scope concept in BPMN. In general, there is a n-1 relationship between Executions and ActivityInstances, ie. at a given point in time, an activity instance can be linked to multiple executions. In addition, it is not guaranteed that the same execution that started a given activity instance will also end it. The process engine performs several internal optimizations concerning the compacting of the execution tree which might lead to executions being reordered and pruned. This can lead to situations where a given execution starts an activity instance but another execution ends it. Another special case is the process instance: if the process instance is executing a non-scope activity (for example a user task) below the process definition scope, it will be referenced by both the root activity instance and the user task activity instance.

If you need to interpret the state of a process instance in terms of a BPMN process model, it is usually easier to use the activity instance tree as opposed to the execution tree.

Specified by:

getActivityInstance in interface RuntimeService

Parameters:

processInstanceId - the id of the process instance for which the activity instance tree should be constructed.

Returns:

the activity instance tree for a given process instance or null if no such process instance exists.

getFormInstanceById

public FormData getFormInstanceById(String processDefinitionId)

suspendProcessInstanceById

public void suspendProcessInstanceById(String processInstanceId)

Description copied from interface: RuntimeService

Suspends the process instance with the given id. This means that the execution is stopped, so the token state will not change. However, actions that do not change token state, like setting/removing variables, etc. will succeed.

Tasks belonging to this process instance will also be suspended. This means that any actions influencing the tasks' lifecycles will fail, such as

• claiming
• completing
• delegation
• changes in task assignees, owners, etc.

Actions that only change task properties will succeed, such as changing variables or adding comments.

If a process instance is in state suspended, the engine will also not execute jobs (timers, messages) associated with this instance.

If you have a process instance hierarchy, suspending one process instance from the hierarchy will not suspend other process instances from that hierarchy.

Specified by:

suspendProcessInstanceById in interface RuntimeService

suspendProcessInstanceByProcessDefinitionId

public void suspendProcessInstanceByProcessDefinitionId(String processDefinitionId)

Description copied from interface: RuntimeService

Suspends the process instances with the given process definition id. This means that the execution is stopped, so the token state will not change. However, actions that do not change token state, like setting/removing variables, etc. will succeed.

Tasks belonging to the suspended process instance will also be suspended. This means that any actions influencing the tasks' lifecycles will fail, such as

• claiming
• completing
• delegation
• changes in task assignees, owners, etc.

Actions that only change task properties will succeed, such as changing variables or adding comments.

If a process instance is in state suspended, the engine will also not execute jobs (timers, messages) associated with this instance.

If you have a process instance hierarchy, suspending one process instance from the hierarchy will not suspend other process instances from that hierarchy.

Specified by:

suspendProcessInstanceByProcessDefinitionId in interface RuntimeService

suspendProcessInstanceByProcessDefinitionKey

public void suspendProcessInstanceByProcessDefinitionKey(String processDefinitionKey)

Description copied from interface: RuntimeService

Suspends the process instances with the given process definition key. This means that the execution is stopped, so the token state will not change. However, actions that do not change token state, like setting/removing variables, etc. will succeed.

Tasks belonging to the suspended process instance will also be suspended. This means that any actions influencing the tasks' lifecycles will fail, such as

• claiming
• completing
• delegation
• changes in task assignees, owners, etc.

Actions that only change task properties will succeed, such as changing variables or adding comments.

If a process instance is in state suspended, the engine will also not execute jobs (timers, messages) associated with this instance.

If you have a process instance hierarchy, suspending one process instance from the hierarchy will not suspend other process instances from that hierarchy.

Specified by:

suspendProcessInstanceByProcessDefinitionKey in interface RuntimeService

activateProcessInstanceById

public void activateProcessInstanceById(String processInstanceId)

Description copied from interface: RuntimeService

Activates the process instance with the given id.

If you have a process instance hierarchy, activating one process instance from the hierarchy will not activate other process instances from that hierarchy.

Specified by:

activateProcessInstanceById in interface RuntimeService

activateProcessInstanceByProcessDefinitionId

public void activateProcessInstanceByProcessDefinitionId(String processDefinitionId)

Description copied from interface: RuntimeService

Activates the process instance with the given process definition id.

If you have a process instance hierarchy, activating one process instance from the hierarchy will not activate other process instances from that hierarchy.

Specified by:

activateProcessInstanceByProcessDefinitionId in interface RuntimeService

activateProcessInstanceByProcessDefinitionKey

public void activateProcessInstanceByProcessDefinitionKey(String processDefinitionKey)

Description copied from interface: RuntimeService

Activates the process instance with the given process definition key.

If you have a process instance hierarchy, activating one process instance from the hierarchy will not activate other process instances from that hierarchy.

Specified by:

activateProcessInstanceByProcessDefinitionKey in interface RuntimeService

startProcessInstanceByMessage

public ProcessInstance startProcessInstanceByMessage(String messageName)

Description copied from interface: RuntimeService

Signals the process engine that a message is received and starts a new ProcessInstance.

Calling this method can have two different outcomes:

• If the message name is associated with a message start event, a new process instance is started.
• If no subscription to a message with the given name exists, ProcessEngineException is thrown

Specified by:

startProcessInstanceByMessage in interface RuntimeService

Parameters:

messageName - the 'name' of the message as specified as an attribute on the bpmn20 <message name="messageName" /> element.

Returns:

the ProcessInstance object representing the started process instance

startProcessInstanceByMessage

public ProcessInstance startProcessInstanceByMessage(String messageName,
                                            String businessKey)

Description copied from interface: RuntimeService

Signals the process engine that a message is received and starts a new ProcessInstance.

See RuntimeService.startProcessInstanceByMessage(String, Map). This method allows specifying a business key.

Specified by:

startProcessInstanceByMessage in interface RuntimeService

Parameters:

messageName - the 'name' of the message as specified as an attribute on the bpmn20 <message name="messageName" /> element.

businessKey - the business key which is added to the started process instance

startProcessInstanceByMessage

public ProcessInstance startProcessInstanceByMessage(String messageName,
                                            Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Signals the process engine that a message is received and starts a new ProcessInstance.

See RuntimeService.startProcessInstanceByMessage(String). In addition, this method allows specifying a the payload of the message as a map of process variables.

Specified by:

startProcessInstanceByMessage in interface RuntimeService

Parameters:

messageName - the 'name' of the message as specified as an attribute on the bpmn20 <message name="messageName" /> element.

processVariables - the 'payload' of the message. The variables are added as processes variables to the started process instance.

Returns:

the ProcessInstance object representing the started process instance

startProcessInstanceByMessage

public ProcessInstance startProcessInstanceByMessage(String messageName,
                                            String businessKey,
                                            Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Signals the process engine that a message is received and starts a new ProcessInstance.

See RuntimeService.startProcessInstanceByMessage(String, Map). In addition, this method allows specifying a business key.

Specified by:

startProcessInstanceByMessage in interface RuntimeService

Parameters:

messageName - the 'name' of the message as specified as an attribute on the bpmn20 <message name="messageName" /> element.

businessKey - the business key which is added to the started process instance

processVariables - the 'payload' of the message. The variables are added as processes variables to the started process instance.

Returns:

the ProcessInstance object representing the started process instance

signalEventReceived

public void signalEventReceived(String signalName)

Description copied from interface: RuntimeService

Notifies the process engine that a signal event of name 'signalName' has been received. This method delivers the signal to all executions waiting on the signal.

NOTE: The waiting executions are notified synchronously.

Specified by:

signalEventReceived in interface RuntimeService

Parameters:

signalName - the name of the signal event

signalEventReceived

public void signalEventReceived(String signalName,
                       Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Notifies the process engine that a signal event of name 'signalName' has been received. This method delivers the signal to all executions waiting on the signal.

NOTE: The waiting executions are notified synchronously.

Specified by:

signalEventReceived in interface RuntimeService

Parameters:

signalName - the name of the signal event

processVariables - a map of variables added to the execution(s)

signalEventReceived

public void signalEventReceived(String signalName,
                       String executionId)

Description copied from interface: RuntimeService

Notifies the process engine that a signal event of name 'signalName' has been received. This method delivers the signal to a single execution, being the execution referenced by 'executionId'. The waiting execution is notified synchronously. Note that you need to provide the exact execution that is waiting for the signal if the process instance contains multiple executions.

Specified by:

signalEventReceived in interface RuntimeService

Parameters:

signalName - the name of the signal event

executionId - id of the process instance or the execution to deliver the signal to

signalEventReceived

public void signalEventReceived(String signalName,
                       String executionId,
                       Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Notifies the process engine that a signal event of name 'signalName' has been received. This method delivers the signal to a single execution, being the execution referenced by 'executionId'. The waiting execution is notified synchronously. Note that you need to provide the exact execution that is waiting for the signal if the process instance contains multiple executions.

Specified by:

signalEventReceived in interface RuntimeService

Parameters:

signalName - the name of the signal event

executionId - the id of the process instance or the execution to deliver the signal to

processVariables - a map of variables added to the execution(s)

messageEventReceived

public void messageEventReceived(String messageName,
                        String executionId)

Description copied from interface: RuntimeService

Notifies the process engine that a message event with name 'messageName' has been received and has been correlated to an execution with id 'executionId'. The waiting execution is notified synchronously. Note that you need to provide the exact execution that is waiting for the message if the process instance contains multiple executions.

Specified by:

messageEventReceived in interface RuntimeService

Parameters:

messageName - the name of the message event

executionId - the id of the process instance or the execution to deliver the message to

messageEventReceived

public void messageEventReceived(String messageName,
                        String executionId,
                        Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Notifies the process engine that a message event with the name 'messageName' has been received and has been correlated to an execution with id 'executionId'. The waiting execution is notified synchronously. Note that you need to provide the exact execution that is waiting for the message if the process instance contains multiple executions.

Specified by:

messageEventReceived in interface RuntimeService

Parameters:

messageName - the name of the message event

executionId - the id of the process instance or the execution to deliver the message to

processVariables - a map of variables added to the execution

createMessageCorrelation

public MessageCorrelationBuilder createMessageCorrelation(String messageName)

Description copied from interface: RuntimeService

Define a complex message correlation using a fluent builder.

Specified by:

createMessageCorrelation in interface RuntimeService

Parameters:

messageName - the name of the message. Corresponds to the 'name' element of the message defined in BPMN 2.0 Xml.

Returns:

the fluent builder for defining the message correlation.

correlateMessage

public void correlateMessage(String messageName,
                    Map<String,Object> correlationKeys,
                    Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Correlates a message to

• an execution that is waiting for this message and can be correlated according to the given correlation keys. This is typically matched against process instance variables.
• a process definition that can be started by this message.

and updates the process instance variables. Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

correlationKeys - a map of key value pairs that are used to correlate the message to an execution

processVariables - a map of variables added to the execution or newly created process instance

correlateMessage

public void correlateMessage(String messageName,
                    String businessKey,
                    Map<String,Object> correlationKeys,
                    Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Correlates a message to

• an execution that is waiting for this message and can be correlated according to the given correlation keys. This is typically matched against process instance variables. The process instance it belongs to has to have the given business key.
• a process definition that can be started by this message.

and updates the process instance variables. Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

businessKey - the business key of process instances to correlate against

correlationKeys - a map of key value pairs that are used to correlate the message to an execution

processVariables - a map of variables added to the execution or newly created process instance

correlateMessage

public void correlateMessage(String messageName)

Description copied from interface: RuntimeService

Correlates a message to either an execution that is waiting for this message or a process definition that can be started by this message. Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

correlateMessage

public void correlateMessage(String messageName,
                    String businessKey)

Description copied from interface: RuntimeService

Correlates a message to

• an execution that is waiting for this message and belongs to a process instance with the given business key
• a process definition that can be started by this message.

Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

businessKey - the business key of process instances to correlate against

correlateMessage

public void correlateMessage(String messageName,
                    Map<String,Object> correlationKeys)

Description copied from interface: RuntimeService

Correlates a message to

• an execution that is waiting for this message and can be correlated according to the given correlation keys. This is typically matched against process instance variables.
• a process definition that can be started by this message.

Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

correlationKeys - a map of key value pairs that are used to correlate the message to an execution

correlateMessage

public void correlateMessage(String messageName,
                    String businessKey,
                    Map<String,Object> processVariables)

Description copied from interface: RuntimeService

Correlates a message to

• an execution that is waiting for this message and belongs to a process instance with the given business key
• a process definition that can be started by this message.

and updates the process instance variables. Notification and instantiation happen synchronously.

Specified by:

correlateMessage in interface RuntimeService

Parameters:

messageName - the name of the message event

businessKey - the business key of process instances to correlate against