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 Summary

Modifier and Type	Method and Description
void	complete(ExternalTask externalTask) Completes a task.
void	complete(ExternalTask externalTask, Map<String,Object> variables) Completes a task.
void	complete(ExternalTask externalTask, Map<String,Object> variables, Map<String,Object> localVariables) Completes a task.
void	complete(String externalTaskId, Map<String,Object> variables, Map<String,Object> localVariables) Completes a task.
void	extendLock(ExternalTask externalTask, long newDuration) Extends the timeout of the lock by a given amount of time.
void	extendLock(String externalTaskId, long newDuration) Extends the timeout of the lock by a given amount of time.
void	handleBpmnError(ExternalTask externalTask, String errorCode) Reports a business error in the context of a running task.
void	handleBpmnError(ExternalTask externalTask, String errorCode, String errorMessage) Reports a business error in the context of a running task.
void	handleBpmnError(ExternalTask externalTask, String errorCode, String errorMessage, Map<String,Object> variables) Reports a business error in the context of a running task.
void	handleBpmnError(String externalTaskId, String errorCode, String errorMessage, Map<String,Object> variables) Reports a business error in the context of a running task.
void	handleFailure(ExternalTask externalTask, String errorMessage, String errorDetails, int retries, long retryTimeout) Reports a failure to execute a task.
void	handleFailure(String externalTaskId, String errorMessage, String errorDetails, int retries, long retryTimeout) Reports a failure to execute a task.
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.
void	lock(ExternalTask externalTask, long lockDuration) Locks a task by a given amount of time.
void	lock(String externalTaskId, long lockDuration) Locks a task by a given amount of time.
void	unlock(ExternalTask externalTask) Unlocks a task and clears the tasks lock expiration time and worker id.

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

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