User stories

• In TaskContext I can complete tasks, handle failures, handle bpmn errors
• In TaskContext I can use variables (get) and set variables on task completion
  • all variables or a defined set of variables can be retrieved according to the name per client#registerWorker#variables
• I can configure the thread pool through application servers
• I can use the CamundaClient fluent builder to pass basic authentication credentials
• I can enable the priority flag per CamundaClient#create#usePriority / I can enable the priority flag per client#registerWorker#usePriority
• I can see/report if a task could not be successfully completed due to the expiration of the lock duration
• I can create/delete deployments and start process instances
• I can read documentation about the java client for external tasks
• CI / SRE
  • Tests are executed
  • Artefact is publicly available

See prototype on https://github.com/tasso94/camunda-worker-java

API

• CamundaClient#create returns a fluent builder to init the client with
  • endpoint url (mandatory), client id, max tasks per fetch and lock request, async respose timeout
  • queue size, number of worker threads => thread pool to execute Worker objects
• CamundaClient#build returns the configured CamundaClient object
• client#registerWorker returns a fluent builder to register a new worker with
  • topic name, lock duration, Worker object supposed to be executed, filter for variables by name (all variables if not invoked)
• client#build
  • adds the configured registration object to the WorkManager
  • returns the registration object WorkerRegistration
• WorkerRegistration#remove removes the registration from WorkManager
• TaskContext provides methods the user can invoke in the customized Worker implementation
  • methods are applied to a task which belongs to a task topic
  • TaskContext#getTaskId
  • TaskContext#complete
  • TaskContext#handleFailure
  • TaskContext#handleBpmnError
  • TaskContext#setVariable ? => complete
  • TaskContext#extendLock
  • TaskContext#getVariable
  • provide getters according to LockedExternalTask (e. g. worker id, topic name, retries, etc.)

Implementation

• WorkManager
  • holds a list of all WorkerRegistration s (registered workers)
    • this list is considered when tasks are being fetched and locked
  • has a singleton thread which is supposed to fetch and lock tasks
    • the respective runnable realizes the acquisition of external tasks (fetch and lock)
    • long polling realizes the back off strategy
  • has a thread pool which is supposed to execute Worker objects
    • has a default configuration in terms of number of threads and queue size
    • can be alternatively configured via the fluent builder of the CamundaClient
• FetchAndLockTasksRunnable
  • is supposed to fetch and lock tasks based on WorkerRegistration s of WorkManager
  • one acquisition cycle contains the following steps:
    • POST /external-task/fetchAndLock
      • request is performed with the information of all workers which has been registered (topic objects)
      • request is configured additionaly to the topic objects with the maximum number of tasks, the worker id and the async response timeout
        • it exists a sensible default configuration
    • Response
      • for each fetched task a WorkerTask object is created and added to the thread pool
      • each WorkerTask object consists of the respective external task dto, the command executor and the Worker object
• WorkerTask
  • for each fetched task an object of this class is created
  • object holds task id, task variables, Worker object
  • is a runnable that provides the context for the thread pool to execute the Worker object
    • WorkerTask#run invokes the method of the worker specific custom object to do the work
  • implements the TaskContext interface which provides methods which can be used in Worker object (e. g. complete task, handle failure, set variable, get variable)
• ClientCommandContext provides methods for the HTTP interaction and marshalling
• ClientCommandExecutor implementation of abstract HTTP methods

Questions

• change wording: registration to subscription
• back off
• jdk
• authentication
• zeebe naming conventions