org.ogf.saga.task
Interface Task<T,E>

All Superinterfaces:

Cloneable, Future<E>, Monitorable, SagaObject

All Known Subinterfaces:

Job, JobSelf

public interface Task<T,E>
extends SagaObject, Monitorable, Future<E>

Tasks can only be created through asynchronous method calls. The generic parameter T denotes the type of the object that generated this task. Note that T cannot be specified as T extends SagaObject because factories can also generate tasks and factories are not Saga objects. The generic parameter E denotes the type of the return value of the asynchronous method call.

Field Summary

static String

TASK_STATE Metric name: fires on task state change, and has the literal value of the task state enumeration.

Fields inherited from interface org.ogf.saga.SagaObject

NO_WAIT, WAIT_FOREVER

Method Summary

void	cancel() Cancels the asynchronous operation.
void	cancel(float timeoutInSeconds) Cancels the asynchronous operation.
T	getObject() Gets the object from which the task was created.
E	getResult() Obtains the result of the asynchronous method call.
State	getState() Gets the state of the task.
void	rethrow() Throws any exception a failed task caught.
void	run() Starts the asynchronous operation.
void	waitFor() Waits for the task end up in a final state.
boolean	waitFor(float timeoutInSeconds) Waits for the task to end up in a final state.

Methods inherited from interface org.ogf.saga.SagaObject

clone, getId, getSession

Methods inherited from interface org.ogf.saga.monitoring.Monitorable

addCallback, getMetric, listMetrics, removeCallback

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Field Detail

TASK_STATE

static final String TASK_STATE

Metric name: fires on task state change, and has the literal value of the task state enumeration.

See Also:

Constant Field Values

Method Detail

run

void run()
         throws NotImplementedException,
                IncorrectStateException,
                TimeoutException,
                NoSuccessException

Starts the asynchronous operation.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the task is not in NEW state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

waitFor

void waitFor()
             throws NotImplementedException,
                    IncorrectStateException,
                    TimeoutException,
                    NoSuccessException

Waits for the task end up in a final state. The SAGA API specifies that this method is called wait, for Java the name needs to be changed slightly.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the task is in NEW state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

waitFor

boolean waitFor(float timeoutInSeconds)
                throws NotImplementedException,
                       IncorrectStateException,
                       TimeoutException,
                       NoSuccessException

Waits for the task to end up in a final state. The SAGA API specifies that this method is called wait, for Java the name needs to be changed slightly.

Parameters:

timeoutInSeconds - maximum number of seconds to wait.

Returns:

true if the task is finished within the specified time.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out. Note that this is not thrown when the specified timeout expires. In that case, false is returned.

IncorrectStateException - is thrown when the task is in NEW state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

cancel

void cancel()
            throws NotImplementedException,
                   IncorrectStateException,
                   TimeoutException,
                   NoSuccessException

Cancels the asynchronous operation. This is a non-blocking version, which may continue to try and cancel the task in the background. The task state will remain RUNNING until the cancel operation succeeds.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the task is in NEW state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

cancel

void cancel(float timeoutInSeconds)
            throws NotImplementedException,
                   IncorrectStateException,
                   TimeoutException,
                   NoSuccessException

Cancels the asynchronous operation. If it does not succeed to cancel the task within the specified timeout, it may continue to try and cancel the task in the background. The task state will remain RUNNING until the cancel operation succeeds.

Parameters:

timeoutInSeconds - maximum time for freeing resources.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the task is in NEW state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getState

State getState()
               throws NotImplementedException,
                      TimeoutException,
                      NoSuccessException

Gets the state of the task.

Returns:

the state of the task.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getResult

E getResult()
            throws NotImplementedException,
                   IncorrectURLException,
                   BadParameterException,
                   AlreadyExistsException,
                   DoesNotExistException,
                   IncorrectStateException,
                   PermissionDeniedException,
                   AuthorizationFailedException,
                   AuthenticationFailedException,
                   TimeoutException,
                   SagaIOException,
                   NoSuccessException

Obtains the result of the asynchronous method call. Implies a waitFor(). If the task is in State.FAILED state after a waitFor(), a rethrow() is called.

Returns:

the result.

Throws:

IncorrectURLException - is thrown when the failed task threw it.

NoSuccessException - is thrown when the failed task threw it.

BadParameterException - is thrown when the failed task threw it.

IncorrectStateException - is thrown when the failed task threw it, or when the task is in State.NEW or State.CANCELED state.

PermissionDeniedException - is thrown when the failed task threw it.

AuthorizationFailedException - is thrown when the failed task threw it.

AuthenticationFailedException - is thrown when the failed task threw it.

NotImplementedException - is thrown when the failed task threw it, or when getResult() is not implemented.

AlreadyExistsException - is thrown when the failed task threw it.

DoesNotExistException - is thrown when the failed task threw it.

TimeoutException - is thrown when the failed task threw it.

SagaIOException - is thrown when the failed task threw it.

getObject

T getObject()
            throws NotImplementedException,
                   TimeoutException,
                   NoSuccessException

Gets the object from which the task was created.

Returns:

the object this task was created from.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

rethrow

void rethrow()
             throws NotImplementedException,
                    IncorrectURLException,
                    AuthenticationFailedException,
                    AuthorizationFailedException,
                    PermissionDeniedException,
                    BadParameterException,
                    IncorrectStateException,
                    AlreadyExistsException,
                    DoesNotExistException,
                    TimeoutException,
                    NoSuccessException,
                    SagaIOException

Throws any exception a failed task caught. It does nothing unless the task is in state State.FAILED. Rethrow can be called multiple times, always throwing the same exception.

Throws:

IncorrectURLException - is thrown when the failed task threw it.

NoSuccessException - is thrown when the failed task threw it.

BadParameterException - is thrown when the failed task threw it.

IncorrectStateException - is thrown when the failed task threw it.

PermissionDeniedException - is thrown when the failed task threw it.

AuthorizationFailedException - is thrown when the failed task threw it.

AuthenticationFailedException - is thrown when the failed task threw it.

NotImplementedException - is thrown when the failed task threw it.

AlreadyExistsException - is thrown when the failed task threw it.

DoesNotExistException - is thrown when the failed task threw it.

TimeoutException - is thrown when the failed task threw it.

SagaIOException - is thrown when the failed task threw it.