org.ogf.saga.task
Interface TaskContainer

All Superinterfaces:

Cloneable, Monitorable, SagaObject

public interface TaskContainer
extends SagaObject, Monitorable

Container object for tasks. Note that a task container must be able to contain any task, so it has no generic parameters for task result type or task object type. The consequence of this is that these types are unknown. So, a task pulled from a container has type Task<?,?>, and its getObject() an Task.getResult() methods return a Object.

Field Summary

static String

TASKCONTAINER_STATE Metric name: fires on state changes of any task in the container, and has the value of that task's object identifier.

Fields inherited from interface org.ogf.saga.SagaObject

NO_WAIT, WAIT_FOREVER

Method Summary

void	add(Task<?,?> task) Adds a task to the task container.
void	cancel() Cancels all the asynchronous operations in the container.
void	cancel(float timeoutInSeconds) Cancels all the asynchronous operations in the container.
State[]	getStates() Gets the states of all tasks in the task container.
Task<?,?>	getTask(String id) Gets a single task from the task container.
Task<?,?>[]	getTasks() Gets the tasks in this task container.
void	remove(Task<?,?> task) Removes the specified task from this container.
void	run() Starts all asynchronous operations in the container.
int	size() Returns the number of tasks in this task container.
Task<?,?>	waitFor() Waits for all tasks to end up in a final state.
Task<?,?>	waitFor(float timeoutInSeconds) Waits for all tasks to end up in a final state.
Task<?,?>	waitFor(float timeoutInSeconds, WaitMode mode) Waits for one or more of the tasks to end up in a final state.
Task<?,?>	waitFor(WaitMode mode) Waits for one or more of the tasks 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

Field Detail

TASKCONTAINER_STATE

static final String TASKCONTAINER_STATE

Metric name: fires on state changes of any task in the container, and has the value of that task's object identifier.

See Also:

Constant Field Values

Method Detail

add

void add(Task<?,?> task)
         throws NotImplementedException,
                TimeoutException,
                NoSuccessException

Adds a task to the task container. If the container already contains the task, the method returns silently.

Parameters:

task - the task to add.

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.

remove

void remove(Task<?,?> task)
            throws NotImplementedException,
                   DoesNotExistException,
                   TimeoutException,
                   NoSuccessException

Removes the specified task from this container.

Parameters:

task - the task to be removed.

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.

DoesNotExistException - is thrown when the container does not contain the specified task.

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

run

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

Starts all asynchronous operations in the container.

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 any of the tasks in the container is not in NEW state.

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

DoesNotExistException - is thrown when the container does not contain any tasks.

waitFor

Task<?,?> waitFor()
                  throws NotImplementedException,
                         IncorrectStateException,
                         DoesNotExistException,
                         TimeoutException,
                         NoSuccessException

Waits for all tasks to end up in a final state. This method blocks indefinitely. One of the finished tasks is returned, and removed from the task container.

Returns:

any of the finished tasks.

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 - may be thrown when any of the tasks in the container would throw this on Task.waitFor().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

waitFor

Task<?,?> waitFor(WaitMode mode)
                  throws NotImplementedException,
                         IncorrectStateException,
                         DoesNotExistException,
                         TimeoutException,
                         NoSuccessException

Waits for one or more of the tasks to end up in a final state. This method blocks indefinitely. One of the finished tasks is returned, and removed from the task container.

Parameters:

mode - wait for ALL or ANY task.

Returns:

any of the finished tasks.

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 - may be thrown when any of the tasks in the container would throw this on Task.waitFor().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

waitFor

Task<?,?> waitFor(float timeoutInSeconds)
                  throws NotImplementedException,
                         IncorrectStateException,
                         DoesNotExistException,
                         TimeoutException,
                         NoSuccessException

Waits for all tasks to end up in a final state. One of the finished tasks is returned, and removed from the task container. If none of the tasks is finished within the specified timeout, null is returned.

Parameters:

timeoutInSeconds - number of seconds to wait.

Returns:

any of the finished tasks.

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 - may be thrown when any of the tasks in the container would throw this on Task.waitFor().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

waitFor

Task<?,?> waitFor(float timeoutInSeconds,
                  WaitMode mode)
                  throws NotImplementedException,
                         IncorrectStateException,
                         DoesNotExistException,
                         TimeoutException,
                         NoSuccessException

Waits for one or more of the tasks to end up in a final state. One of the finished tasks is returned, and removed from the task container. If none of the tasks is finished within the specified timeout, null is returned.

Parameters:

timeoutInSeconds - number of seconds to wait.

mode - wait for ALL or ANY task.

Returns:

any of the finished tasks.

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 - may be thrown when any of the tasks in the container would throw this on Task.waitFor().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

cancel

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

Cancels all the asynchronous operations in the container. This is a non-blocking version, which may continue to try and cancel tasks in the background. The task states 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 any of the tasks in the container would throw this on Task.cancel().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

cancel

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

Cancels all the asynchronous operations in the container. When the timeout expires, this version may continue to try and cancel tasks in the background. The task states will remain RUNNING until the cancel operation succeeds.

Parameters:

timeoutInSeconds - 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 any of the tasks in the container would throw this on Task.cancel().

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

DoesNotExistException - is thrown when the container does not contain any tasks.

size

int size()
         throws NotImplementedException,
                TimeoutException,
                NoSuccessException

Returns the number of tasks in this task container.

Returns:

the number of tasks.

Throws:

NotImplementedException

TimeoutException

NoSuccessException

getTask

Task<?,?> getTask(String id)
                  throws NotImplementedException,
                         DoesNotExistException,
                         TimeoutException,
                         NoSuccessException

Gets a single task from the task container.

Parameters:

id - the object identifier of the task (typically obtained from the TASKCONTAINER_STATE metric).

Returns:

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.

DoesNotExistException - is thrown when the container does not contain a task for the specified id.

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

getTasks

Task<?,?>[] getTasks()
                     throws NotImplementedException,
                            TimeoutException,
                            NoSuccessException

Gets the tasks in this task container.

Returns:

the tasks.

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.

getStates

State[] getStates()
                  throws NotImplementedException,
                         TimeoutException,
                         NoSuccessException

Gets the states of all tasks in the task container.

Returns:

the states.

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.