Package org.camunda.bpm.engine.cdi

Class BusinessProcess

  • All Implemented Interfaces:
    java.io.Serializable
    @Named
public class BusinessProcess
extends java.lang.Object
implements java.io.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 Detail

      • BusinessProcess

        public BusinessProcess()

    • Method Detail

      • startProcessById

        public ProcessInstance startProcessById​(java.lang.String processDefinitionId)

      • startProcessById

        public ProcessInstance startProcessById​(java.lang.String processDefinitionId,
                                        java.lang.String businessKey)

      • startProcessById

        public ProcessInstance startProcessById​(java.lang.String processDefinitionId,
                                        java.util.Map<java.lang.String,​java.lang.Object> variables)

      • startProcessById

        public ProcessInstance startProcessById​(java.lang.String processDefinitionId,
                                        java.lang.String businessKey,
                                        java.util.Map<java.lang.String,​java.lang.Object> variables)

      • startProcessByKey

        public ProcessInstance startProcessByKey​(java.lang.String key)

      • startProcessByKey

        public ProcessInstance startProcessByKey​(java.lang.String key,
                                         java.lang.String businessKey)

      • startProcessByKey

        public ProcessInstance startProcessByKey​(java.lang.String key,
                                         java.util.Map<java.lang.String,​java.lang.Object> variables)

      • startProcessByKey

        public ProcessInstance startProcessByKey​(java.lang.String key,
                                         java.lang.String businessKey,
                                         java.util.Map<java.lang.String,​java.lang.Object> variables)

      • startProcessByMessage

        public ProcessInstance startProcessByMessage​(java.lang.String messageName)

      • startProcessByMessage

        public ProcessInstance startProcessByMessage​(java.lang.String messageName,
                                             java.util.Map<java.lang.String,​java.lang.Object> processVariables)

      • startProcessByMessage

        public ProcessInstance startProcessByMessage​(java.lang.String messageName,
                                             java.lang.String businessKey,
                                             java.util.Map<java.lang.String,​java.lang.Object> processVariables)

      • associateExecutionById

        public void associateExecutionById​(java.lang.String executionId)
        Associate with the provided execution. This starts a unit of work.
        Parameters:
        executionId - the id of the execution to associate with.

      • startTask

        public Task startTask​(java.lang.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

      • 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​(java.lang.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 TypedValue> T getVariableTyped​(java.lang.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​(java.lang.String variableName,
                        java.lang.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 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 java.util.Map<java.lang.String,​java.lang.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 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 java.util.Map<java.lang.String,​java.lang.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​(java.lang.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 TypedValue> T getVariableLocalTyped​(java.lang.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​(java.lang.String variableName,
                             java.lang.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 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 java.util.Map<java.lang.String,​java.lang.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 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 java.util.Map<java.lang.String,​java.lang.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.

        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.

      • setTaskId

        public void setTaskId​(java.lang.String taskId)
        See Also:
        startTask(String)

      • getProcessInstanceId

        public java.lang.String getProcessInstanceId()
        Returns the id of the currently associated process instance or 'null'

      • getTaskId

        public java.lang.String getTaskId()
        Returns the id of the task associated with the current conversation or 'null'.

      • getExecution

        public Execution getExecution()
        Returns the currently associated execution or 'null'

      • getExecutionId

        public java.lang.String getExecutionId()
        See Also:
        getExecution()

      • assertExecutionAssociated

        protected void assertExecutionAssociated()

      • assertTaskAssociated

        protected void assertTaskAssociated()

      • assertCommandContextNotActive

        protected void assertCommandContextNotActive()