Package org.camunda.bpm.engine.cdi
Class BusinessProcess
java.lang.Object
org.camunda.bpm.engine.cdi.BusinessProcess
- All Implemented Interfaces:
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
1st unit of work ("process instantiation"):
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:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected void
protected void
protected void
void
associateExecutionById
(String executionId) Associate with the provided execution.void
Completes the current UserTask, seeTaskService.complete(String)
void
completeTask
(boolean endConversation) void
This method allows to flush the cached variables to the Task or Execution.Get theVariableMap
of local cached variables and clear the internal variable cache.Get theVariableMap
of cached variables and clear the internal variable cache.Deprecated.Deprecated.usegetAndClearCachedLocalVariableMap()
insteadGet a copy of theVariableMap
of local cached variables.Get a copy of theVariableMap
of cached variables.Returns the currently associated execution or 'null'Returns theProcessInstance
currently associated or 'null'Returns the id of the currently associated process instance or 'null'getTask()
Returns the currently associatedTask
or 'null'Returns the id of the task associated with the current conversation or 'null'.<T> T
getVariable
(String variableName) Deprecated.usegetCachedVariableMap()
instead<T> T
getVariableLocal
(String variableName) Deprecated.usegetCachedLocalVariableMap()
instead<T extends TypedValue>
TgetVariableLocalTyped
(String variableName) <T extends TypedValue>
TgetVariableTyped
(String variableName) boolean
returns true if anExecution
is associated.boolean
void
saveTask()
Save the currently associated task.void
setExecution
(Execution execution) protected void
setExecutionId
(String executionId) void
void
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
Signals the current execution, seeRuntimeService.signal(String)
void
signalExecution
(boolean endConversation) startProcessById
(String processDefinitionId) startProcessById
(String processDefinitionId, String businessKey) startProcessById
(String processDefinitionId, Map<String, Object> variables) startProcessByKey
(String key) startProcessByKey
(String key, String businessKey) startProcessByKey
(String key, Map<String, Object> variables) startProcessByMessage
(String messageName) startProcessByMessage
(String messageName, Map<String, Object> processVariables) Associates the task with the provided taskId with the current conversation.void
stopTask()
Stop working on a task.void
stopTask
(boolean endConversation) Stop working on a task.
-
Constructor Details
-
BusinessProcess
public BusinessProcess()
-
-
Method Details
-
startProcessById
-
startProcessById
-
startProcessById
-
startProcessById
-
startProcessByKey
-
startProcessByKey
-
startProcessByKey
-
startProcessByKey
-
startProcessByMessage
-
startProcessByMessage
public ProcessInstance startProcessByMessage(String messageName, Map<String, Object> processVariables) -
startProcessByMessage
-
associateExecutionById
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 anExecution
is associated.- See Also:
-
signalExecution
public void signalExecution()Signals the current execution, seeRuntimeService.signal(String)
Ends the current unit of work (flushes changes to process variables set usingsetVariable(String, Object)
or made on@BusinessProcessScoped
beans).- Throws:
ProcessEngineCdiException
- if no execution is currently associatedProcessEngineException
- if the activiti command fails
-
signalExecution
public void signalExecution(boolean endConversation) -
startTask
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
-
completeTask
public void completeTask()Completes the current UserTask, seeTaskService.complete(String)
Ends the current unit of work (flushes changes to process variables set usingsetVariable(String, Object)
or made on@BusinessProcessScoped
beans).- Throws:
ProcessEngineCdiException
- if no task is currently associatedProcessEngineException
- if the activiti command fails
-
completeTask
public void completeTask(boolean endConversation) -
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.
- If you want to flush changes to process variables, call
-
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.
- If you want to flush changes to process variables, call
-
getVariable
- 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
- 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
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 setvalue
- the value to be set
-
getAndClearCachedVariableMap
Get theVariableMap
of cached variables and clear the internal variable cache.- Returns:
- the
VariableMap
of cached variables - Since:
- 7.3
-
getAndClearVariableCache
Deprecated.usegetAndClearCachedVariableMap()
insteadGet the map of cached variables and clear the internal variable cache.- Returns:
- the map of cached variables
-
getCachedVariableMap
Get a copy of theVariableMap
of cached variables.- Returns:
- a copy of the
VariableMap
of cached variables. - Since:
- 7.3
-
getVariableCache
Deprecated.usegetCachedVariableMap()
insteadGet a copy of the map of cached variables.- Returns:
- a copy of the map of cached variables.
-
getVariableLocal
- 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
- 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
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 setvalue
- the value to be set
-
getAndClearCachedLocalVariableMap
Get theVariableMap
of local cached variables and clear the internal variable cache.- Returns:
- the
VariableMap
of cached variables - Since:
- 7.3
-
getAndClearVariableLocalCache
Deprecated.usegetAndClearCachedLocalVariableMap()
insteadGet the map of local cached variables and clear the internal variable cache.- Returns:
- the map of cached variables
-
getCachedLocalVariableMap
Get a copy of theVariableMap
of local cached variables.- Returns:
- a copy of the
VariableMap
of local cached variables. - Since:
- 7.3
-
getVariableLocalCache
Deprecated.usegetCachedLocalVariableMap()
insteadGet 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.
- If a Task instance is currently associated,
the variables will be flushed using
-
setTask
- See Also:
-
setTaskId
- See Also:
-
setExecution
- See Also:
-
setExecutionId
- See Also:
-
getProcessInstanceId
Returns the id of the currently associated process instance or 'null' -
getTaskId
Returns the id of the task associated with the current conversation or 'null'. -
getTask
Returns the currently associatedTask
or 'null'- Throws:
ProcessEngineCdiException
- if noTask
is associated. UseisTaskAssociated()
to check whether an association exists.
-
getExecution
Returns the currently associated execution or 'null' -
getExecutionId
- See Also:
-
getProcessInstance
Returns theProcessInstance
currently associated or 'null'- Throws:
ProcessEngineCdiException
- if noExecution
is associated. UseisAssociated()
to check whether an association exists.
-
assertExecutionAssociated
protected void assertExecutionAssociated() -
assertTaskAssociated
protected void assertTaskAssociated() -
assertCommandContextNotActive
protected void assertCommandContextNotActive()
-
getAndClearCachedVariableMap()
instead