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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        ConnectionLostException - if the connection could not be established

      • complete

        void complete​(ExternalTask externalTask)
        Completes a task.
        Parameters:
        externalTask - which will be completed
        Throws:
        NotFoundException - if the task has been canceled and therefore does not exist anymore
        NotAcquiredException - if the tasks most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established
        ValueMapperException -
        • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established
        ValueMapperException -
        • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established
        ValueMapperException -
        • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established
        ValueMapperException -
        • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established
        ValueMapperException -
        • 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.

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        NotResumedException - if the corresponding process instance could not be resumed
        ConnectionLostException - if the connection could not be established

      • 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 the new lock duration in milliseconds
        Throws:
        NotFoundException - if the task has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        ConnectionLostException - if the connection could not be established

      • 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 the new lock duration in milliseconds
        Throws:
        NotFoundException - if the task has been canceled and therefore does not exist anymore
        NotAcquiredException - if the task's most recent lock could not be acquired
        ConnectionLostException - if the connection could not be established