org.camunda.bpm.engine.cdi

Class BusinessProcess

java.lang.Object

org.camunda.bpm.engine.cdi.BusinessProcess

All Implemented Interfaces:

Serializable

@Named
public class BusinessProcess
extends Object
implements Serializable

Bean supporting contextual business process management. This allows us to implement a unit of work, in which a particular CDI scope (Conversation / Request / Thread) is associated with a particular Execution / ProcessInstance or Task.

The protocol is that we associate the BusinessProcess bean with a particular Execution / Task, then perform some changes (retrieve / set process variables) and then end the unit of work. This bean makes sure that our changes are only "flushed" to the process engine when we successfully complete the unit of work.

A typical usage scenario might look like this:
1st unit of work ("process instantiation"):

 conversation.begin();
 ...
 businessProcess.setVariable("billingId", "1"); // setting variables before starting the process
 businessProcess.startProcessByKey("billingProcess");
 conversation.end();
 

2nd unit of work ("perform a user task"):

 conversation.begin();
 businessProcess.startTask(id); // now we have associated a task with the current conversation
 ...                            // this allows us to retrieve and change process variables
                                // and @BusinessProcessScoped beans
 businessProcess.setVariable("billingDetails", "someValue"); // these changes are cached in the conversation
 ...
 businessProcess.completeTask(); // now all changed process variables are flushed
 conversation.end();
 

NOTE: in the absence of a conversation, (non faces request, i.e. when processing a JAX-RS, JAX-WS, JMS, remote EJB or plain Servlet requests), the BusinessProcess bean associates with the current Request (see @RequestScoped).

NOTE: in the absence of a request, ie. when the JobExecutor accesses @BusinessProcessScoped beans, the execution is associated with the current thread.

Author:

Daniel Meyer, Falko Menge

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
BusinessProcess()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	assertCommandContextNotActive()
protected void	assertExecutionAssociated()
protected void	assertTaskAssociated()
void	associateExecutionById(String executionId) Associate with the provided execution.
void	completeTask() Completes the current UserTask, see TaskService.complete(String) Ends the current unit of work (flushes changes to process variables set using setVariable(String, Object) or made on @BusinessProcessScoped beans).
void	completeTask(boolean endConversation)
void	flushVariableCache() This method allows to flush the cached variables to the Task or Execution.
org.camunda.bpm.engine.variable.VariableMap	getAndClearCachedLocalVariableMap() Get the VariableMap of local cached variables and clear the internal variable cache.
org.camunda.bpm.engine.variable.VariableMap	getAndClearCachedVariableMap() Get the VariableMap of cached variables and clear the internal variable cache.
Map<String,Object>	getAndClearVariableCache() Deprecated. use getAndClearCachedVariableMap() instead
Map<String,Object>	getAndClearVariableLocalCache() Deprecated. use getAndClearCachedLocalVariableMap() instead
org.camunda.bpm.engine.variable.VariableMap	getCachedLocalVariableMap() Get a copy of the VariableMap of local cached variables.
org.camunda.bpm.engine.variable.VariableMap	getCachedVariableMap() Get a copy of the VariableMap of cached variables.
Execution	getExecution() Returns the currently associated execution or 'null'
String	getExecutionId()
ProcessInstance	getProcessInstance() Returns the ProcessInstance currently associated or 'null'
String	getProcessInstanceId() Returns the id of the currently associated process instance or 'null'
Task	getTask() Returns the currently associated Task or 'null'
String	getTaskId() Returns the id of the task associated with the current conversation or 'null'.
<T> T	getVariable(String variableName)
Map<String,Object>	getVariableCache() Deprecated. use getCachedVariableMap() instead
<T> T	getVariableLocal(String variableName)
Map<String,Object>	getVariableLocalCache() Deprecated. use getCachedLocalVariableMap() instead
<T extends org.camunda.bpm.engine.variable.value.TypedValue> T	getVariableLocalTyped(String variableName)
<T extends org.camunda.bpm.engine.variable.value.TypedValue> T	getVariableTyped(String variableName)
boolean	isAssociated() returns true if an Execution is associated.
boolean	isTaskAssociated()
void	saveTask() Save the currently associated task.
void	setExecution(Execution execution)
protected void	setExecutionId(String executionId)
void	setTask(Task task)
void	setTaskId(String taskId)
void	setVariable(String variableName, Object value) Set a value for a process variable.
void	setVariableLocal(String variableName, Object value) Set a value for a local process variable.
void	signalExecution() Signals the current execution, see RuntimeService.signal(String) Ends the current unit of work (flushes changes to process variables set using setVariable(String, Object) or made on @BusinessProcessScoped beans).
void	signalExecution(boolean endConversation)
ProcessInstance	startProcessById(String processDefinitionId)
ProcessInstance	startProcessById(String processDefinitionId, Map<String,Object> variables)
ProcessInstance	startProcessById(String processDefinitionId, String businessKey)
ProcessInstance	startProcessById(String processDefinitionId, String businessKey, Map<String,Object> variables)
ProcessInstance	startProcessByKey(String key)
ProcessInstance	startProcessByKey(String key, Map<String,Object> variables)
ProcessInstance	startProcessByKey(String key, String businessKey)
ProcessInstance	startProcessByKey(String key, String businessKey, Map<String,Object> variables)
ProcessInstance	startProcessByMessage(String messageName)
ProcessInstance	startProcessByMessage(String messageName, Map<String,Object> processVariables)
ProcessInstance	startProcessByMessage(String messageName, String businessKey, Map<String,Object> processVariables)
Task	startTask(String taskId) Associates the task with the provided taskId with the current conversation.
Task	startTask(String taskId, boolean beginConversation)
void	stopTask() Stop working on a task.
void	stopTask(boolean endConversation) Stop working on a task.

Methods inherited from class java.lang.Object

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

Constructor Detail

BusinessProcess

public BusinessProcess()

Method Detail

startProcessById

public ProcessInstance startProcessById(String processDefinitionId)

startProcessById

public ProcessInstance startProcessById(String processDefinitionId,
                               String businessKey)

startProcessById

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

startProcessById

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

startProcessByKey

public ProcessInstance startProcessByKey(String key)

startProcessByKey

public ProcessInstance startProcessByKey(String key,
                                String businessKey)

startProcessByKey

public ProcessInstance startProcessByKey(String key,
                                Map<String,Object> variables)

startProcessByKey

public ProcessInstance startProcessByKey(String key,
                                String businessKey,
                                Map<String,Object> variables)

startProcessByMessage

public ProcessInstance startProcessByMessage(String messageName)

startProcessByMessage

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

startProcessByMessage

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

associateExecutionById

public void associateExecutionById(String executionId)

Associate with the provided execution. This starts a unit of work.

Parameters:

executionId - the id of the execution to associate with.

isAssociated

public boolean isAssociated()

returns true if an Execution is associated.

See Also:

associateExecutionById(String)

signalExecution

public void signalExecution()

Signals the current execution, see RuntimeService.signal(String)

Ends the current unit of work (flushes changes to process variables set using setVariable(String, Object) or made on @BusinessProcessScoped beans).

Throws:

ProcessEngineCdiException - if no execution is currently associated

ProcessEngineException - if the activiti command fails

signalExecution

public void signalExecution(boolean endConversation)

See Also:

In addition, this method allows to end the current conversation

startTask

public Task startTask(String taskId)

Associates the task with the provided taskId with the current conversation.

Parameters:

taskId - the id of the task

Returns:

the resumed task

Throws:

ProcessEngineCdiException - if no such task is found

startTask

public Task startTask(String taskId,
             boolean beginConversation)

See Also:

this method allows to start a conversation if no conversation is active

completeTask

public void completeTask()

Completes the current UserTask, see TaskService.complete(String)

Ends the current unit of work (flushes changes to process variables set using setVariable(String, Object) or made on @BusinessProcessScoped beans).

Throws:

ProcessEngineCdiException - if no task is currently associated

ProcessEngineException - if the activiti command fails

completeTask

public void completeTask(boolean endConversation)

See Also:

In addition this allows to end the current conversation.

isTaskAssociated

public boolean isTaskAssociated()

saveTask

public void saveTask()

Save the currently associated task.

Throws:

ProcessEngineCdiException - if called from a process engine command or if no Task is currently associated.

stopTask

public void stopTask()

Stop working on a task. Clears the current association.

NOTE: this method does not flush any changes.

• If you want to flush changes to process variables, call flushVariableCache() prior to calling this method,
• If you need to flush changes to the task object, use saveTask() prior to calling this method.

Throws:

ProcessEngineCdiException - if called from a process engine command or if no Task is currently associated.

stopTask

public void stopTask(boolean endConversation)

Stop working on a task. Clears the current association.

NOTE: this method does not flush any changes.

• If you want to flush changes to process variables, call flushVariableCache() prior to calling this method,
• If you need to flush changes to the task object, use saveTask() prior to calling this method.

This method allows you to optionally end the current conversation

Parameters:

endConversation - if true, end current conversation.

Throws:

ProcessEngineCdiException - if called from a process engine command or if no Task is currently associated.

getVariable

public <T> T getVariable(String variableName)

Parameters:

variableName - the name of the process variable for which the value is to be retrieved

Returns:

the value of the provided process variable or 'null' if no such variable is set

getVariableTyped

public <T extends org.camunda.bpm.engine.variable.value.TypedValue> T getVariableTyped(String variableName)

Parameters:

variableName - the name of the process variable for which the value is to be retrieved

Returns:

the typed value of the provided process variable or 'null' if no such variable is set

Since:

7.3

setVariable

public void setVariable(String variableName,
               Object value)

Set a value for a process variable.

NOTE: If no execution is currently associated, the value is temporarily cached and flushed to the process instance at the end of the unit of work

Parameters:

variableName - the name of the process variable for which a value is to be set

value - the value to be set

getAndClearCachedVariableMap

public org.camunda.bpm.engine.variable.VariableMap getAndClearCachedVariableMap()

Get the VariableMap of cached variables and clear the internal variable cache.

Returns:

the VariableMap of cached variables

Since:

7.3

getAndClearVariableCache

@Deprecated
public Map<String,Object> getAndClearVariableCache()

Deprecated. use getAndClearCachedVariableMap() instead

Get the map of cached variables and clear the internal variable cache.

Returns:

the map of cached variables

getCachedVariableMap

public org.camunda.bpm.engine.variable.VariableMap getCachedVariableMap()

Get a copy of the VariableMap of cached variables.

Returns:

a copy of the VariableMap of cached variables.

Since:

7.3

getVariableCache

@Deprecated
public Map<String,Object> getVariableCache()

Deprecated. use getCachedVariableMap() instead

Get a copy of the map of cached variables.

Returns:

a copy of the map of cached variables.

getVariableLocal

public <T> T getVariableLocal(String variableName)

Parameters:

variableName - the name of the local process variable for which the value is to be retrieved

Returns:

the value of the provided local process variable or 'null' if no such variable is set

getVariableLocalTyped

public <T extends org.camunda.bpm.engine.variable.value.TypedValue> T getVariableLocalTyped(String variableName)

Parameters:

variableName - the name of the local process variable for which the value is to be retrieved

Returns:

the typed value of the provided local process variable or 'null' if no such variable is set

Since:

7.3

setVariableLocal

public void setVariableLocal(String variableName,
                    Object value)

Set a value for a local process variable.

NOTE: If a task or execution is currently associated, the value is temporarily cached and flushed to the process instance at the end of the unit of work - otherwise an Exception will be thrown

Parameters:

variableName - the name of the local process variable for which a value is to be set

value - the value to be set

getAndClearCachedLocalVariableMap

public org.camunda.bpm.engine.variable.VariableMap getAndClearCachedLocalVariableMap()

Get the VariableMap of local cached variables and clear the internal variable cache.

Returns:

the VariableMap of cached variables

Since:

7.3

getAndClearVariableLocalCache

@Deprecated
public Map<String,Object> getAndClearVariableLocalCache()

Deprecated. use getAndClearCachedLocalVariableMap() instead

Get the map of local cached variables and clear the internal variable cache.

Returns:

the map of cached variables

getCachedLocalVariableMap

public org.camunda.bpm.engine.variable.VariableMap getCachedLocalVariableMap()

Get a copy of the VariableMap of local cached variables.

Returns:

a copy of the VariableMap of local cached variables.

Since:

7.3

getVariableLocalCache

@Deprecated
public Map<String,Object> getVariableLocalCache()

Deprecated. use getCachedLocalVariableMap() instead

Get a copy of the map of local cached variables.

Returns:

a copy of the map of local cached variables.

flushVariableCache

public void flushVariableCache()

This method allows to flush the cached variables to the Task or Execution.

• If a Task instance is currently associated, the variables will be flushed using TaskService.setVariables(String, Map)
• If an Execution instance is currently associated, the variables will be flushed using RuntimeService.setVariables(String, Map)
• If neither a Task nor an Execution is currently associated, ProcessEngineCdiException is thrown.

A successful invocation of this method will empty the variable cache.

If this method is called from an active command (ie. from inside a Java Delegate). ProcessEngineCdiException is thrown.

Throws:

ProcessEngineCdiException - if called from a process engine command or if neither a Task nor an Execution is associated.

setTask

public void setTask(Task task)

See Also:

startTask(String)

setTaskId

public void setTaskId(String taskId)

See Also:

startTask(String)

setExecution

public void setExecution(Execution execution)

See Also:

associateExecutionById(String)

setExecutionId

protected void setExecutionId(String executionId)

See Also:

associateExecutionById(String)

getProcessInstanceId

public String getProcessInstanceId()

Returns the id of the currently associated process instance or 'null'

getTaskId

public String getTaskId()

Returns the id of the task associated with the current conversation or 'null'.

getTask

public Task getTask()

Returns the currently associated Task or 'null'

Throws:

ProcessEngineCdiException - if no Task is associated. Use isTaskAssociated() to check whether an association exists.

getExecution

public Execution getExecution()

Returns the currently associated execution or 'null'

getExecutionId

public String getExecutionId()

See Also:

getExecution()

getProcessInstance

public ProcessInstance getProcessInstance()

Returns the ProcessInstance currently associated or 'null'

Throws:

ProcessEngineCdiException - if no Execution is associated. Use isAssociated() to check whether an association exists.

assertExecutionAssociated

protected void assertExecutionAssociated()

assertTaskAssociated

protected void assertTaskAssociated()

assertCommandContextNotActive

protected void assertCommandContextNotActive()