Package org.camunda.bpm.client.task

Interface ExternalTaskService

All Known Implementing Classes:
ExternalTaskServiceImpl
public interface ExternalTaskService

Service that provides possibilities to interact with fetched and locked tasks.

Author:
Tassilo Weidner

  • Method Details

    • lock

      void lock(String externalTaskId, long lockDuration)
      Locks a task by a given amount of time. Note: This method should be used to lock external tasks that have been obtained without using the fetch & lock API.
      Parameters:
      externalTaskId - the id of the external task whose lock will be extended
      lockDuration - specifies the lock duration in milliseconds
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client

    • lock

      void lock(ExternalTask externalTask, long lockDuration)
      Locks a task by a given amount of time. Note: This method should be used to lock external tasks that have been obtained without using the fetch & lock API.
      Parameters:
      externalTask - which lock will be extended
      lockDuration - specifies the lock duration in milliseconds
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • unlock

      void unlock(ExternalTask externalTask)
      Unlocks a task and clears the tasks lock expiration time and worker id.
      Parameters:
      externalTask - which will be unlocked
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • complete

      void complete(ExternalTask externalTask)
      Completes a task.
      Parameters:
      externalTask - which will be completed
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if the tasks most recent lock could not be acquired
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.
      • if an object cannot be serialized
      • if no 'objectTypeName' is provided for non-null value
      • if value is of type abstract
      • if no suitable serializer could be found

    • setVariables

      void setVariables(String processInstanceId, Map<String,Object> variables)
      Set variables
      Parameters:
      variables - are set in the tasks ancestor execution hierarchy. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.
      • if an object cannot be serialized
      • if no 'objectTypeName' is provided for non-null value
      • if value is of type abstract
      • if no suitable serializer could be found

    • setVariables

      void setVariables(ExternalTask externalTask, Map<String,Object> variables)
      Set variables
      Parameters:
      variables - are set in the tasks ancestor execution hierarchy. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.
      • if an object cannot be serialized
      • if no 'objectTypeName' is provided for non-null value
      • if value is of type abstract
      • if no suitable serializer could be found

    • complete

      void complete(ExternalTask externalTask, Map<String,Object> variables)
      Completes a task.
      Parameters:
      externalTask - which will be completed
      variables - are set in the tasks ancestor execution hierarchy The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.
      • if an object cannot be serialized
      • if no 'objectTypeName' is provided for non-null value
      • if value is of type abstract
      • if no suitable serializer could be found

    • complete

      void complete(ExternalTask externalTask, Map<String,Object> variables, Map<String,Object> localVariables)
      Completes a task.
      Parameters:
      externalTask - which will be completed
      variables - are set in the tasks ancestor execution hierarchy. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      localVariables - are set in the execution of the external task instance. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.
      • if an object cannot be serialized
      • if no 'objectTypeName' is provided for non-null value
      • if value is of type abstract
      • if no suitable serializer could be found

    • complete

      void complete(String externalTaskId, Map<String,Object> variables, Map<String,Object> localVariables)
      Completes a task.
      Parameters:
      externalTaskId - the id of the external task which will be completed
      variables - are set in the tasks ancestor execution hierarchy. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      localVariables - are set in the execution of the external task instance. The key and the value represent the variable name and its value. Map can consist of both typed and untyped variables.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      ValueMapperException
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleFailure

      void handleFailure(ExternalTask externalTask, String errorMessage, String errorDetails, int retries, long retryTimeout)
      Reports a failure to execute a task. A number of retries and a timeout until the task can be specified. If the retries are set to 0, an incident for this task is created.
      Parameters:
      externalTask - external task for which a failure will be reported
      errorMessage - indicates the reason of the failure.
      errorDetails - provides a detailed error description.
      retries - specifies how often the task should be retried. Must be >= 0. If 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. The incident's message is set to the errorMessage parameter.
      retryTimeout - specifies a timeout in milliseconds before the external task becomes available again for fetching. Must be >= 0.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleFailure

      void handleFailure(String externalTaskId, String errorMessage, String errorDetails, int retries, long retryTimeout)
      Reports a failure to execute a task. A number of retries and a timeout until the task can be specified. If the retries are set to 0, an incident for this task is created.
      Parameters:
      externalTaskId - the id of the external task for which a failure will be reported
      errorMessage - indicates the reason of the failure.
      errorDetails - provides a detailed error description.
      retries - specifies how often the task should be retried. Must be >= 0. If 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. The incident's message is set to the errorMessage parameter.
      retryTimeout - specifies a timeout in milliseconds before the external task becomes available again for fetching. Must be >= 0.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleFailure

      void handleFailure(String externalTaskId, String errorMessage, String errorDetails, int retries, long retryTimeout, Map<String,Object> variables, Map<String,Object> localVariables)
      Reports a failure to execute a task. A number of retries and a timeout until the task can be specified. If the retries are set to 0, an incident for this task is created.
      Parameters:
      externalTaskId - the id of the external task for which a failure will be reported
      errorMessage - indicates the reason of the failure.
      errorDetails - provides a detailed error description.
      retries - specifies how often the task should be retried. Must be >= 0. If 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. The incident's message is set to the errorMessage parameter.
      retryTimeout - specifies a timeout in milliseconds before the external task becomes available again for fetching. Must be >= 0.
      variables - a map of variables to set on the execution the external task is assigned to
      localVariables - a map of variables to set on the execution locally
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleBpmnError

      void handleBpmnError(ExternalTask externalTask, String errorCode)
      Reports a business error in the context of a running task. The error code must be specified to identify the BPMN error handler.
      Parameters:
      externalTask - external task for which a BPMN error will be reported
      errorCode - that indicates the predefined error. The error code is used to identify the BPMN error handler.
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleBpmnError

      void handleBpmnError(ExternalTask externalTask, String errorCode, String errorMessage)
      Reports a business error in the context of a running task. The error code must be specified to identify the BPMN error handler.
      Parameters:
      externalTask - external task for which a BPMN error will be reported
      errorCode - that indicates the predefined error. The error code is used to identify the BPMN error handler.
      errorMessage - which will be passed when the BPMN error is caught
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleBpmnError

      void handleBpmnError(ExternalTask externalTask, String errorCode, String errorMessage, Map<String,Object> variables)
      Reports a business error in the context of a running task. The error code must be specified to identify the BPMN error handler.
      Parameters:
      externalTask - external task for which a BPMN error will be reported
      errorCode - that indicates the predefined error. The error code is used to identify the BPMN error handler.
      errorMessage - which will be passed when the BPMN error is caught
      variables - which will be passed to the execution when the BPMN error is caught
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • handleBpmnError

      void handleBpmnError(String externalTaskId, String errorCode, String errorMessage, Map<String,Object> variables)
      Reports a business error in the context of a running task. The error code must be specified to identify the BPMN error handler.
      Parameters:
      externalTaskId - the id of the external task for which a BPMN error will be reported
      errorCode - that indicates the predefined error. The error code is used to identify the BPMN error handler.
      errorMessage - which will be passed when the BPMN error is caught
      variables - which will be passed to the execution when the BPMN error is caught
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • extendLock

      void extendLock(ExternalTask externalTask, long newDuration)
      Extends the timeout of the lock by a given amount of time.
      Parameters:
      externalTask - which lock will be extended
      newDuration - specifies the new lock duration in milliseconds
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.

    • extendLock

      void extendLock(String externalTaskId, long newDuration)
      Extends the timeout of the lock by a given amount of time.
      Parameters:
      externalTaskId - the id of the external task which lock will be extended
      newDuration - specifies the new lock duration in milliseconds
      Throws:
      NotFoundException - if the task doesn't exist or has already been canceled or completed
      BadRequestException - if an illegal operation was performed or the given data is invalid.
      EngineException - if something went wrong during the engine execution (e.g., a persistence exception occurred)
      ConnectionLostException - if the connection could not be established
      UnknownHttpErrorException - if the HTTP status code is not known by the client.