org.activiti.engine
Interface RuntimeService

public interface RuntimeService

Service which provides access to Deployments, ProcessDefinitions and ProcessInstances.

Author:

Tom Baeyens, Joram Barrez, Daniel Meyer

Method Summary

void	activateProcessInstanceById(String processInstanceId) Activates the process instance with the given id.
ExecutionQuery	createExecutionQuery() Creates a new ExecutionQuery instance, that can be used to query the executions and process instances.
ProcessInstanceQuery	createProcessInstanceQuery() Creates a new ProcessInstanceQuery instance, that can be used to query process 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.
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	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	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, 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.

Method Detail

startProcessInstanceByKey

ProcessInstance startProcessInstanceByKey(String processDefinitionKey)

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

Parameters:

processDefinitionKey - key of process definition, cannot be null.

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceByKey

ProcessInstance startProcessInstanceByKey(String processDefinitionKey,
                                          String businessKey)

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. Process instance from different process definition are allowed to have the same business key. The combination of processdefinitionKey-businessKey must be unique.

Parameters:

processDefinitionKey - key of process definition, cannot be null.

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

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceByKey

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

Parameters:

processDefinitionKey - key of process definition, cannot be null.

variables - the variables to pass, can be null.

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceByKey

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. 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. Process instance from different process definition are allowed to have the same business key. The combination of processdefinitionKey-businessKey must be unique.

Parameters:

processDefinitionKey - key of process definition, cannot be null.

variables - the variables to pass, can be null.

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

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceById

ProcessInstance startProcessInstanceById(String processDefinitionId)

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

Parameters:

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

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceById

ProcessInstance startProcessInstanceById(String processDefinitionId,
                                         String businessKey)

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. Process instance from different process definition are allowed to have the same business key.

Parameters:

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

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

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceById

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.

Parameters:

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

variables - variables to be passed, can be null

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceById

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. 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. Process instance from different process definition are allowed to have the same business key.

Parameters:

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

variables - variables to be passed, can be null

Throws:

ActivitiException - when no process definition is deployed with the given key.

startProcessInstanceByMessage

ProcessInstance startProcessInstanceByMessage(String messageName)

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, ActivitiException is thrown

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

Throws:

ActivitiExeception - if no subscription to a message with the given name exists

Since:

5.9

startProcessInstanceByMessage

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

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

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

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

Throws:

ActivitiExeception - if no subscription to a message with the given name exists

Since:

5.9

startProcessInstanceByMessage

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

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

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

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

Throws:

ActivitiExeception - if no subscription to a message with the given name exists

Since:

5.9

deleteProcessInstance

void deleteProcessInstance(String processInstanceId,
                           String deleteReason)

Delete an existing runtime process instance.

Parameters:

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

deleteReason - reason for deleting, can be null.

Throws:

ActivitiException - when no process instance is found with the given id.

getActiveActivityIds

List<String> getActiveActivityIds(String executionId)

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.

Parameters:

executionId - id of the execution, cannot be null.

Throws:

ActivitiException - when no execution exists with the given executionId.

signal

void signal(String executionId)

Sends an external trigger to an activity instance that is waiting inside the given execution.

Parameters:

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

Throws:

ActivitiException - when no execution is found for the given executionId.

signal

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

Sends an external trigger to an activity instance that is waiting inside the given execution.

Parameters:

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

processVariables - a map of process variables

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariables

Map<String,Object> getVariables(String executionId)

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

Parameters:

executionId - id of execution, cannot be null.

Returns:

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

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariablesLocal

Map<String,Object> getVariablesLocal(String executionId)

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 getVariablesLocal(String, Collection) for better performance.

Parameters:

executionId - id of execution, cannot be null.

Returns:

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

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariables

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

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.

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariablesLocal

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.

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.

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariable

Object getVariable(String executionId,
                   String variableName)

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.

Parameters:

executionId - id of 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.

Throws:

ActivitiException - when no execution is found for the given executionId.

getVariableLocal

Object getVariableLocal(String executionId,
                        String variableName)

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.

setVariable

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

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

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.

Throws:

ActivitiException - when no execution is found for the given executionId.

setVariableLocal

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

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.

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.

Throws:

ActivitiException - when no execution is found for the given executionId.

setVariables

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

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

Parameters:

executionId - id of the execution, cannot be null.

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

Throws:

ActivitiException - when no execution is found for the given executionId.

setVariablesLocal

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

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.

Parameters:

executionId - id of the execution, cannot be null.

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

Throws:

ActivitiException - when no execution is found for the given executionId.

createExecutionQuery

ExecutionQuery createExecutionQuery()

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

createProcessInstanceQuery

ProcessInstanceQuery createProcessInstanceQuery()

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

suspendProcessInstanceById

void suspendProcessInstanceById(String processInstanceId)

Suspends the process instance with the given id. If a process instance is in state suspended, activiti will not execute jobs (timers, messages) associated with this instance. If you have a process instance hierarchy, suspending one process instance form the hierarchy will not suspend other process instances form that hierarchy.

Throws:

ActivitiException - if no such processInstance can be found or if the process instance is already in state suspended.

activateProcessInstanceById

void activateProcessInstanceById(String processInstanceId)

Activates the process instance with the given id. If you have a process instance hierarchy, suspending one process instance form the hierarchy will not suspend other process instances form that hierarchy.

Throws:

ActivitiException - if no such processInstance can be found or if the process instance is already in state active.

signalEventReceived

void signalEventReceived(String signalName)

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.

Parameters:

signalName - the name of the signal event

signalEventReceived

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

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.

Parameters:

signalName - the name of the signal event

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

signalEventReceived

void signalEventReceived(String signalName,
                         String executionId)

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.

Parameters:

signalName - the name of the signal event

executionId - the id of the execution to deliver the signal to

Throws:

ActivitiException - if no such execution exists or if the execution has not subscribed to the signal

signalEventReceived

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

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.

Parameters:

signalName - the name of the signal event

executionId - the id of the execution to deliver the signal to

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

Throws:

ActivitiException - if no such execution exists or if the execution has not subscribed to the signal