Package org.camunda.community.bpmndt.api

Class ExternalTaskHandler<T extends ExternalTaskHandler<?>>

java.lang.Object
org.camunda.community.bpmndt.api.ExternalTaskHandler<T>
Type Parameters:
T - The handler implementation.
Direct Known Subclasses:
ExternalTaskClientHandler
public class ExternalTaskHandler<T extends ExternalTaskHandler<?>> extends Object
Fluent API to handle external tasks.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    fetchExtensionProperties
     
    protected boolean
    fetchLocalVariablesOnly
     
    protected final org.camunda.bpm.engine.ProcessEngine
    processEngine
     
    protected static final String
    WORKER_ID
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    ExternalTaskHandler(org.camunda.bpm.engine.ProcessEngine processEngine, String activityId, String topicName)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    apply(org.camunda.bpm.engine.runtime.ProcessInstance pi)
     
    void
    complete()
    Completes the locked external task by calling complete, using the specified variables and local variables, when the process instance is waiting at the corresponding activity.
    protected void
    complete(org.camunda.bpm.engine.externaltask.LockedExternalTask task)
     
    T
    customize(Consumer<T> customizer)
    Customizes the handler, using the given Consumer function.
    void
    execute(Consumer<String> action)
    Executes a custom action that handles the external task, when the process instance is waiting at the corresponding activity.
    void
    executeExternalTask(Consumer<org.camunda.bpm.engine.externaltask.ExternalTask> taskAction)
    Executes a custom action that handles the external task, which has been queried (by process instance ID, activity ID and topic name) and locked before, when the process instance is waiting at the corresponding activity.
    void
    executeLockedExternalTask(Consumer<org.camunda.bpm.engine.externaltask.LockedExternalTask> taskAction)
    Executes a custom action that handles the external task, which has been queried (by process instance ID, activity ID and topic name) and locked before, when the process instance is waiting at the corresponding activity.
    void
    handleBpmnError(String errorCode, String errorMessage)
    Continues the execution with an action that calls handleBpmnError using the given error code and message as well as the specified variables.
    protected void
    handleBpmnError(org.camunda.bpm.engine.externaltask.LockedExternalTask task)
     
    boolean
    isWaitingForBoundaryEvent()
    Determines if the external task is waiting for a boundary message, signal or timer event.
    T
    verify(BiConsumer<org.camunda.bpm.engine.test.assertions.bpmn.ProcessInstanceAssert,String> verifier)
    Verifies the external task's waiting state.
    T
    verifyTask(BiConsumer<org.camunda.bpm.engine.test.assertions.bpmn.ExternalTaskAssert,Map<String,Object>> taskVerifier)
    Verifies the external task's waiting state.
    void
    waitForBoundaryEvent()
    Applies no action at the external task's wait state.
    T
    withErrorMessage(String errorMessage)
    Sets the error message, which is used when the next activity is an error boundary event - in this case the handler's action is handleBpmnError.
    T
    withFetchExtensionProperties(boolean fetchExtensionProperties)
    Specifies if extension properties should be included when an external task is fetched - default: false
    T
    withFetchLocalVariablesOnly(boolean fetchLocalVariablesOnly)
    Specifies if only local variables should be fetched when an external task is fetched - default: false
    T
    withLocalVariable(String name, Object value)
    Sets a local variable, which is passed to the execution when the default behavior is used.
    T
    withLocalVariables(Map<String,Object> localVariables)
    Sets local variables, which are passed to the execution when the default behavior is used.
    T
    withLocalVariableTyped(String name, org.camunda.bpm.engine.variable.value.TypedValue value)
    Sets a typed local variable, which is passed to the execution when the default behavior is used.
    T
    withLockDuration(long lockDuration)
    Sets the duration in milliseconds for which the external task should be locked - default: 20_000
    T
    withVariable(String name, Object value)
    Sets a variable, which is passed to the execution when a predefined behavior is used.
    T
    withVariables(Map<String,Object> variables)
    Sets variables, which are passed to the execution when a predefined behavior is used.
    T
    withVariableTyped(String name, org.camunda.bpm.engine.variable.value.TypedValue value)
    Sets a typed variable, which is passed to the execution when a predefined behavior is used.
    T
    withWorkerId(String workerId)
    Sets a custom worker ID, which is used for lock, complete and handleBpmnError ExternalTaskService calls.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • WORKER_ID

      protected static final String WORKER_ID
      See Also:

    • processEngine

      protected final org.camunda.bpm.engine.ProcessEngine processEngine

    • fetchExtensionProperties

      protected boolean fetchExtensionProperties

    • fetchLocalVariablesOnly

      protected boolean fetchLocalVariablesOnly

  • Constructor Details

    • ExternalTaskHandler

      public ExternalTaskHandler(org.camunda.bpm.engine.ProcessEngine processEngine, String activityId, String topicName)

  • Method Details

    • apply

      protected void apply(org.camunda.bpm.engine.runtime.ProcessInstance pi)

    • complete

      public void complete()
      Completes the locked external task by calling complete, using the specified variables and local variables, when the process instance is waiting at the corresponding activity. Please note: this is the default behavior.
      See Also:
      • ExternalTaskService.complete(String, String, java.util.Map, java.util.Map)

    • complete

      protected void complete(org.camunda.bpm.engine.externaltask.LockedExternalTask task)

    • customize

      public T customize(Consumer<T> customizer)
      Customizes the handler, using the given Consumer function. This method can be used to apply a common customization needed for different test cases. 
       tc.handleExternalTask().customize(this::prepareExternalTask);
      Parameters:
      customizer - A function that accepts a ExternalTaskHandler.
      Returns:
      The handler.

    • execute

      public void execute(Consumer<String> action)
      Executes a custom action that handles the external task, when the process instance is waiting at the corresponding activity.
      Parameters:
      action - A specific action that accepts the related topic name (String).

    • executeExternalTask

      public void executeExternalTask(Consumer<org.camunda.bpm.engine.externaltask.ExternalTask> taskAction)
      Executes a custom action that handles the external task, which has been queried (by process instance ID, activity ID and topic name) and locked before, when the process instance is waiting at the corresponding activity.
      Parameters:
      taskAction - A specific action that accepts an ExternalTask.
      See Also:
      • ExternalTaskService.lock(String, String, long)

    • executeLockedExternalTask

      public void executeLockedExternalTask(Consumer<org.camunda.bpm.engine.externaltask.LockedExternalTask> taskAction)
      Executes a custom action that handles the external task, which has been queried (by process instance ID, activity ID and topic name) and locked before, when the process instance is waiting at the corresponding activity.
      Parameters:
      taskAction - A specific action that accepts an LockedExternalTask.
      See Also:
      • ExternalTaskService.lock(String, String, long)

    • handleBpmnError

      public void handleBpmnError(String errorCode, String errorMessage)
      Continues the execution with an action that calls handleBpmnError using the given error code and message as well as the specified variables.
      Parameters:
      errorCode - The error code of the attached boundary error event.
      errorMessage - An error message or null.
      See Also:
      • ExternalTaskService.handleBpmnError(String, String, String, String, java.util.Map)

    • handleBpmnError

      protected void handleBpmnError(org.camunda.bpm.engine.externaltask.LockedExternalTask task)

    • isWaitingForBoundaryEvent

      public boolean isWaitingForBoundaryEvent()
      Determines if the external task is waiting for a boundary message, signal or timer event.
      Returns:
      true, if it is waiting for a boundary event. false, if not.

    • verify

      public T verify(BiConsumer<org.camunda.bpm.engine.test.assertions.bpmn.ProcessInstanceAssert,String> verifier)
      Verifies the external task's waiting state.
      Parameters:
      verifier - Verifier that accepts an ProcessInstanceAssert instance and the related topic name (String).
      Returns:
      The handler.

    • verifyTask

      public T verifyTask(BiConsumer<org.camunda.bpm.engine.test.assertions.bpmn.ExternalTaskAssert,Map<String,Object>> taskVerifier)
      Verifies the external task's waiting state.
      Parameters:
      taskVerifier - Verifier that accepts an ExternalTaskAssert instance and the task's local variables.
      Returns:
      The handler.

    • waitForBoundaryEvent

      public void waitForBoundaryEvent()
      Applies no action at the external task's wait state. This is required to wait for events (e.g. message, signal or timer events) that are attached as boundary events on the activity itself or on the surrounding scope (e.g. embedded subprocess).

    • withErrorMessage

      public T withErrorMessage(String errorMessage)
      Sets the error message, which is used when the next activity is an error boundary event - in this case the handler's action is handleBpmnError.
      Parameters:
      errorMessage - An error message or null.
      Returns:
      The handler.
      See Also:

    • withFetchExtensionProperties

      public T withFetchExtensionProperties(boolean fetchExtensionProperties)
      Specifies if extension properties should be included when an external task is fetched - default: false
      Parameters:
      fetchExtensionProperties - Include extension properties, if available, or not.
      Returns:
      The handler.
      See Also:
      • ExternalTaskQueryTopicBuilder.includeExtensionProperties()

    • withFetchLocalVariablesOnly

      public T withFetchLocalVariablesOnly(boolean fetchLocalVariablesOnly)
      Specifies if only local variables should be fetched when an external task is fetched - default: false
      Parameters:
      fetchLocalVariablesOnly - Include only variables of the external task itself, but no variables of parent scopes.
      Returns:
      The handler.
      See Also:
      • ExternalTaskQueryTopicBuilder.localVariables()

    • withLocalVariable

      public T withLocalVariable(String name, Object value)
      Sets a local variable, which is passed to the execution when the default behavior is used.
      Parameters:
      name - The name of the local variable.
      value - The local variable's value.
      Returns:
      The handler.
      See Also:

    • withLocalVariables

      public T withLocalVariables(Map<String,Object> localVariables)
      Sets local variables, which are passed to the execution when the default behavior is used.
      Parameters:
      localVariables - A map of local variables to set.
      Returns:
      The handler.
      See Also:

    • withLocalVariableTyped

      public T withLocalVariableTyped(String name, org.camunda.bpm.engine.variable.value.TypedValue value)
      Sets a typed local variable, which is passed to the execution when the default behavior is used.
      Parameters:
      name - The name of the local variable.
      value - The local variable's typed value.
      Returns:
      The handler.
      See Also:

    • withLockDuration

      public T withLockDuration(long lockDuration)
      Sets the duration in milliseconds for which the external task should be locked - default: 20_000
      Parameters:
      lockDuration - The lock duration to use, when fetching and locking an external task.
      Returns:
      The handler.
      See Also:
      • ExternalTaskQueryBuilder.topic(String, long)

    • withVariable

      public T withVariable(String name, Object value)
      Sets a variable, which is passed to the execution when a predefined behavior is used.
      Parameters:
      name - The name of the variable.
      value - The variable's value.
      Returns:
      The handler.
      See Also:

    • withVariables

      public T withVariables(Map<String,Object> variables)
      Sets variables, which are passed to the execution when a predefined behavior is used.
      Parameters:
      variables - A map of variables to set.
      Returns:
      The handler.
      See Also:

    • withVariableTyped

      public T withVariableTyped(String name, org.camunda.bpm.engine.variable.value.TypedValue value)
      Sets a typed variable, which is passed to the execution when a predefined behavior is used.
      Parameters:
      name - The name of the variable.
      value - The variable's typed value.
      Returns:
      The handler.
      See Also:

    • withWorkerId

      public T withWorkerId(String workerId)
      Sets a custom worker ID, which is used for lock, complete and handleBpmnError ExternalTaskService calls. If not set, the default value "bpmndt-worker" is used.
      Parameters:
      workerId - A specific worker ID to use.
      Returns:
      The handler.