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 Detail

      • 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.