org.apache.brooklyn.api.mgmt

Interface Task<T>

All Superinterfaces:

TaskAdaptable<T>

All Known Subinterfaces:

TaskInternal<T>

All Known Implementing Classes:

BasicTask, CompoundTask, DynamicSequentialTask, ForwardingTask, ParallelTask, ScheduledTask, SequentialTask

public interface Task<T>
extends TaskAdaptable<T>

Represents a unit of work for execution. When used with an ExecutionManager or ExecutionContext it will record submission time, execution start time, end time, and any result. A task can be submitted to the ExecutionManager or ExecutionContext, in which case it will be returned, or it may be created by submission of a Runnable or Callable and thereafter it can be treated just like a Future.

Method Summary

Modifier and Type	Method and Description
void	blockUntilEnded() Causes calling thread to block until the task is ended.
boolean	blockUntilEnded(Duration timeout) As blockUntilEnded(), but returning after the given timeout; true if the task has ended and false otherwise
void	blockUntilStarted() Causes calling thread to block until the task is started.
boolean	cancel(boolean mayInterruptIfRunning) As Future.cancel(boolean).
T	get(Duration duration) As #get(long, java.util.concurrent.TimeUnit)
java.lang.String	getDescription()
java.lang.String	getDisplayName()
long	getEndTimeUtc() if isDone() (for any reason) returns the time when the task ended; guaranteed to be >= getStartTimeUtc() > 0 if ended, or -1 otherwise
java.lang.String	getId()
long	getStartTimeUtc() if isBegun() returns the time when the task was starts; guaranteed to be >= getSubmitTimeUtc() > 0 if started, or -1 otherwise
java.lang.String	getStatusDetail(boolean multiline) Returns detailed status, suitable for a hover.
java.lang.String	getStatusSummary()
Task<?>	getSubmittedByTask() task which submitted this task, if was submitted by a task
java.lang.String	getSubmittedByTaskId() task which submitted this task, if was submitted by a task
long	getSubmitTimeUtc() if isSubmitted() returns the time when the task was submitted; or -1 otherwise
java.util.Set<java.lang.Object>	getTags()
java.lang.Thread	getThread() The thread where the task is running, if it is running.
T	getUnchecked() As #get(), but propagating checked exceptions as unchecked for convenience.
T	getUnchecked(Duration duration) As #get(), but propagating checked exceptions as unchecked for convenience (including a TimeoutException if the duration expires)
boolean	isBegun() Whether task has started running.
boolean	isDone() As Future.isDone().
boolean	isDone(boolean andTaskNotRunning) As isDone(), identical if the argument is false, but by supplying true this will also check getEndTimeUtc() if isBegun() to guarantee that the task is no longer running.
boolean	isError() Whether the task threw an error, including cancellation (implies isDone())
boolean	isSubmitted() Whether task has been submitted Submitted tasks are normally expected to start running then complete, but unsubmitted tasks are sometimes passed around for someone else to submit them.

Methods inherited from interface org.apache.brooklyn.api.mgmt.TaskAdaptable

asTask

Method Detail

getId

java.lang.String getId()

getTags

java.util.Set<java.lang.Object> getTags()

getSubmitTimeUtc

long getSubmitTimeUtc()

if isSubmitted() returns the time when the task was submitted; or -1 otherwise

getStartTimeUtc

long getStartTimeUtc()

if isBegun() returns the time when the task was starts; guaranteed to be >= getSubmitTimeUtc() > 0 if started, or -1 otherwise

getEndTimeUtc

long getEndTimeUtc()

if isDone() (for any reason) returns the time when the task ended; guaranteed to be >= getStartTimeUtc() > 0 if ended, or -1 otherwise

getDisplayName

java.lang.String getDisplayName()

getDescription

java.lang.String getDescription()

getSubmittedByTask

Task<?> getSubmittedByTask()

task which submitted this task, if was submitted by a task

getSubmittedByTaskId

java.lang.String getSubmittedByTaskId()

task which submitted this task, if was submitted by a task

getThread

java.lang.Thread getThread()

The thread where the task is running, if it is running.

isSubmitted

boolean isSubmitted()

Whether task has been submitted Submitted tasks are normally expected to start running then complete, but unsubmitted tasks are sometimes passed around for someone else to submit them.

isBegun

boolean isBegun()

Whether task has started running. Will remain true after normal completion or non-cancellation error. will be true on cancel iff the thread did actually start.

isError

boolean isError()

Whether the task threw an error, including cancellation (implies isDone())

isDone

boolean isDone()

As Future.isDone(). In particular if cancelled, this will return true as soon as it is cancelled. The thread for this task may still be running, if the cancellation (often an interruption, but may be weaker) has not applied, and submitted threads may also be running depending on cancellation parameters.

#get() is guaranteed to return immediately, throwing in the case of cancellation prior to completion (and including the case above where a thread may still be running).

To check whether cancelled threads for this task have completed, use #isDone(boolean)). inspect getEndTimeUtc(), which is guaranteed to be set when threads complete if the thread is started (as determinable by whether getStartTimeUtc() is set). (The threads of submitted/child tasks will usually be independent; to determine their completion requires inspecting the ExecutionManager.)

isDone

boolean isDone(boolean andTaskNotRunning)

As isDone(), identical if the argument is false, but by supplying true this will also check getEndTimeUtc() if isBegun() to guarantee that the task is no longer running. isDone() will return true for cancelled tasks even if they are still running.

In a task hierarchy, the threads of tasks submitted by this may still be ongoing. To determine their completion, inspect the ExecutionManager.

Parameters:

andTaskHasEnded -

Returns:

blockUntilStarted

void blockUntilStarted()

Causes calling thread to block until the task is started.

blockUntilEnded

void blockUntilEnded()

Causes calling thread to block until the task is ended.

Either normally or by cancellation or error, but without throwing error on cancellation or error. (Errors are logged at debug.)

blockUntilEnded

boolean blockUntilEnded(Duration timeout)

As blockUntilEnded(), but returning after the given timeout; true if the task has ended and false otherwise

getStatusSummary

java.lang.String getStatusSummary()

getStatusDetail

java.lang.String getStatusDetail(boolean multiline)

Returns detailed status, suitable for a hover. Plain-text format, with new-lines (and sometimes extra info) if multiline enabled.

get

T get(Duration duration)
throws java.lang.InterruptedException,
      java.util.concurrent.ExecutionException,
      java.util.concurrent.TimeoutException

As #get(long, java.util.concurrent.TimeUnit)

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException

getUnchecked

T getUnchecked()

As #get(), but propagating checked exceptions as unchecked for convenience.

getUnchecked

T getUnchecked(Duration duration)

As #get(), but propagating checked exceptions as unchecked for convenience (including a TimeoutException if the duration expires)

cancel

boolean cancel(boolean mayInterruptIfRunning)

As Future.cancel(boolean). Note that isDone() and blockUntilEnded(Duration) return immediately once a task is cancelled, consistent with the underlying FutureTask behaviour. TODO Fine-grained control over underlying jobs, e.g. to ensure anything represented by this task is actually completed, is not (yet) publicly exposed. See the convenience method blockUntilInternalTasksEnded in the Tasks set of helpers for more discussion.