BasicTask (Apache Brooklyn)

java.lang.Object
- brooklyn.util.task.BasicTask<T>

All Implemented Interfaces:

Task<T>, TaskAdaptable<T>, TaskInternal<T>, com.google.common.util.concurrent.ListenableFuture<T>, java.util.concurrent.Future<T>

Direct Known Subclasses:

CompoundTask, DynamicSequentialTask, ScheduledTask
```
public class BasicTask<T>
extends java.lang.Object
implements TaskInternal<T>
```
The basic concrete implementation of a Task to be executed. A Task is a wrapper for an executable unit, such as a Closure or a Runnable or Callable and will run in its own Thread.
The task can be given an optional displayName and description in its constructor (as named arguments in the first Map parameter). It is guaranteed to have Object.notify() called once whenever the task starts running and once again when the task is about to complete. Due to the way executors work it is ugly to guarantee notification after completion, so instead we notify just before then expect the user to call get() - which will throw errors if the underlying job did so - or blockUntilEnded() which will not throw errors.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class BasicTask.SubmissionErrorCatchingExecutor

static interface BasicTask.TaskFinalizer

Nested Classes
Modifier and Type	Class and Description
`static class`	`BasicTask.SubmissionErrorCatchingExecutor`
`static interface`	`BasicTask.TaskFinalizer`

Field Summary

Fields
Modifier and Type	Field and Description
`java.lang.String`	`description`
`java.lang.String`	`displayName`
`static BasicTask.TaskFinalizer`	`NO_OP`
`static BasicTask.TaskFinalizer`	`WARN_IF_NOT_RUN`

Constructor Summary

Constructors
Constructor and Description
`BasicTask(java.util.concurrent.Callable<T> job)`
`BasicTask(groovy.lang.Closure<T> job)`
`BasicTask(java.util.Map<?,?> flags, java.util.concurrent.Callable<T> job)`
`BasicTask(java.util.Map<?,?> flags, groovy.lang.Closure<T> job)`
`BasicTask(java.util.Map<?,?> flags, java.lang.Runnable job)`
`BasicTask(java.lang.Runnable job)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)`
`void`	`applyTagModifier(com.google.common.base.Function<java.util.Set<java.lang.Object>,java.lang.Void> modifier)`
`Task<T>`	`asTask()`
`void`	`blockUntilEnded()` Causes calling thread to block until the task is ended.
`boolean`	`blockUntilEnded(Duration timeout)` As `Task.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`	`blockUntilStarted(Duration timeout)`
`boolean`	`cancel()`
`boolean`	`cancel(boolean mayInterruptIfRunning)` As `Future.cancel(boolean)`.
`boolean`	`equals(java.lang.Object obj)`
`T`	`get()`
`T`	`get(Duration duration)` As `Future.get(long, java.util.concurrent.TimeUnit)`
`T`	`get(long timeout, java.util.concurrent.TimeUnit unit)`
`java.lang.String`	`getBlockingDetails()` returns a textual message giving details while the task is blocked
`Task<?>`	`getBlockingTask()` returns a task that this task is blocked on
`java.lang.String`	`getDescription()`
`java.lang.String`	`getDisplayName()`
`long`	`getEndTimeUtc()` if `Future.isDone()` (for any reason) returns the time when the task ended; guaranteed to be >= `Task.getStartTimeUtc()` > 0 if ended, or -1 otherwise
`java.lang.Object`	`getExtraStatusText()`
`java.lang.String`	`getId()`
`java.util.concurrent.Future<T>`	`getInternalFuture()` returns the underlying future where this task's results will come in; see `TaskInternal.initInternalFuture(ListenableFuture)`
`java.util.concurrent.Callable<T>`	`getJob()`
`com.google.common.util.concurrent.ExecutionList`	`getListeners()`
`java.util.Set<java.lang.Object>`	`getMutableTags()`
`Task<?>`	`getProxyTarget()` if a task is a proxy for another one (used mainly for internal tasks), this returns the "real" task represented by this one
`long`	`getQueuedTimeUtc()` if the job is queued for submission (e.g.
`long`	`getStartTimeUtc()` if `Task.isBegun()` returns the time when the task was starts; guaranteed to be >= `Task.getSubmitTimeUtc()` > 0 if started, or -1 otherwise
`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.
`java.lang.String`	`getStatusSummary()` Returns a brief status string Plain-text format.
`Task<?>`	`getSubmittedByTask()` task which submitted this task, if was submitted by a task
`long`	`getSubmitTimeUtc()` if `Task.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 `Future.get()`, but propagating checked exceptions as unchecked for convenience.
`T`	`getUnchecked(Duration duration)` As `Future.get()`, but propagating checked exceptions as unchecked for convenience (including a `TimeoutException` if the duration expires)
`int`	`hashCode()`
`void`	`ignoreIfNotRun()`
`void`	`initInternalFuture(com.google.common.util.concurrent.ListenableFuture<T> result)` sets the internal future object used to record the association to a job submitted to an `ExecutorService`
`boolean`	`isBegun()` Whether task has started running.
`boolean`	`isCancelled()`
`boolean`	`isDone()`
`boolean`	`isError()` Returns true if the task has had an error.
`boolean`	`isQueued()`
`boolean`	`isQueuedAndNotSubmitted()`
`boolean`	`isQueuedOrSubmitted()`
`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.
`void`	`markQueued()` marks the task as queued for execution
`void`	`resetBlockingDetails()`
`void`	`resetBlockingTask()`
`void`	`runListeners()`
`java.lang.String`	`setBlockingDetails(java.lang.String blockingDetails)` allows a task user to specify why a task is blocked; for use immediately before a blocking/wait, and typically cleared immediately afterwards; referenced by management api to inspect a task which is blocking
`Task<?>`	`setBlockingTask(Task<?> blockingTask)` as `TaskInternal.setBlockingDetails(String)` but records a task which is blocking, for use e.g.
`void`	`setEndTimeUtc(long val)`
`void`	`setExtraStatusText(java.lang.Object extraStatus)`
`void`	`setFinalizer(BasicTask.TaskFinalizer f)`
`void`	`setJob(java.util.concurrent.Callable<T> job)`
`void`	`setStartTimeUtc(long val)`
`void`	`setSubmittedByTask(Task<?> task)`
`void`	`setSubmitTimeUtc(long val)`
`void`	`setThread(java.lang.Thread thread)`
`java.lang.String`	`toString()`
`boolean`	`uncancel()` doesn't resume it, just means if something was cancelled but not submitted it could now be submitted; probably going to be removed and perhaps some mechanism for running again made available

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - displayName
```
public final java.lang.String displayName
```
  - description
```
public final java.lang.String description
```
  - WARN_IF_NOT_RUN
```
public static final BasicTask.TaskFinalizer WARN_IF_NOT_RUN
```
  - NO_OP
```
public static final BasicTask.TaskFinalizer NO_OP
```
- Constructor Detail
  - BasicTask
```
public BasicTask(java.util.concurrent.Callable<T> job)
```
  - BasicTask
```
public BasicTask(java.util.Map<?,?> flags,
         java.util.concurrent.Callable<T> job)
```
  - BasicTask
```
public BasicTask(java.lang.Runnable job)
```
  - BasicTask
```
public BasicTask(java.util.Map<?,?> flags,
         java.lang.Runnable job)
```
  - BasicTask
```
public BasicTask(groovy.lang.Closure<T> job)
```
  - BasicTask
```
public BasicTask(java.util.Map<?,?> flags,
         groovy.lang.Closure<T> job)
```
- Method Detail
  - getId
```
public java.lang.String getId()
```
    Specified by:
    
    getId in interface Task<T>
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - asTask
```
public Task<T> asTask()
```
    Specified by:
    
    asTask in interface TaskAdaptable<T>
  - initInternalFuture
```
public void initInternalFuture(com.google.common.util.concurrent.ListenableFuture<T> result)
```
    Description copied from interface: TaskInternal
    
    sets the internal future object used to record the association to a job submitted to an ExecutorService
    
    Specified by:
    
    initInternalFuture in interface TaskInternal<T>
  - getTags
```
public java.util.Set<java.lang.Object> getTags()
```
    Specified by:
    
    getTags in interface Task<T>
  - getQueuedTimeUtc
```
public long getQueuedTimeUtc()
```
    if the job is queued for submission (e.g. by another task) it can indicate that fact (and time) here; note tasks can (and often are) submitted without any queueing, in which case this value may be -1
    
    Specified by:
    
    getQueuedTimeUtc in interface TaskInternal<T>
  - getSubmitTimeUtc
```
public long getSubmitTimeUtc()
```
    Description copied from interface: Task
    
    if Task.isSubmitted() returns the time when the task was submitted; or -1 otherwise
    
    Specified by:
    
    getSubmitTimeUtc in interface Task<T>
  - getStartTimeUtc
```
public long getStartTimeUtc()
```
    Description copied from interface: Task
    
    if Task.isBegun() returns the time when the task was starts; guaranteed to be >= Task.getSubmitTimeUtc() > 0 if started, or -1 otherwise
    
    Specified by:
    
    getStartTimeUtc in interface Task<T>
  - getEndTimeUtc
```
public long getEndTimeUtc()
```
    Description copied from interface: Task
    
    if Future.isDone() (for any reason) returns the time when the task ended; guaranteed to be >= Task.getStartTimeUtc() > 0 if ended, or -1 otherwise
    
    Specified by:
    
    getEndTimeUtc in interface Task<T>
  - getInternalFuture
```
public java.util.concurrent.Future<T> getInternalFuture()
```
    Description copied from interface: TaskInternal
    
    returns the underlying future where this task's results will come in; see TaskInternal.initInternalFuture(ListenableFuture)
    
    Specified by:
    
    getInternalFuture in interface TaskInternal<T>
  - getSubmittedByTask
```
public Task<?> getSubmittedByTask()
```
    Description copied from interface: Task
    
    task which submitted this task, if was submitted by a task
    
    Specified by:
    
    getSubmittedByTask in interface Task<T>
  - getThread
```
public java.lang.Thread getThread()
```
    the thread where the task is running, if it is running
    
    Specified by:
    
    getThread in interface Task<T>
  - isQueued
```
public boolean isQueued()
```
    Specified by:
    
    isQueued in interface TaskInternal<T>
  - isQueuedOrSubmitted
```
public boolean isQueuedOrSubmitted()
```
    Specified by:
    
    isQueuedOrSubmitted in interface TaskInternal<T>
  - isQueuedAndNotSubmitted
```
public boolean isQueuedAndNotSubmitted()
```
    Specified by:
    
    isQueuedAndNotSubmitted in interface TaskInternal<T>
  - isSubmitted
```
public boolean isSubmitted()
```
    Description copied from interface: Task
    
    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.
    
    Specified by:
    
    isSubmitted in interface Task<T>
  - isBegun
```
public boolean isBegun()
```
    Description copied from interface: Task
    
    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.
    
    Specified by:
    
    isBegun in interface Task<T>
  - markQueued
```
public void markQueued()
```
    marks the task as queued for execution
    
    Specified by:
    
    markQueued in interface TaskInternal<T>
  - cancel
```
public final boolean cancel()
```
    Specified by:
    
    cancel in interface TaskInternal<T>
  - uncancel
```
@Beta
public boolean uncancel()
```
    doesn't resume it, just means if something was cancelled but not submitted it could now be submitted; probably going to be removed and perhaps some mechanism for running again made available
    
    Since:
    
    0.7.0
  - cancel
```
public boolean cancel(boolean mayInterruptIfRunning)
```
    Description copied from interface: Task
    
    As Future.cancel(boolean). Note that Future.isDone() and Task.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.
    
    Specified by:
    
    cancel in interface Task<T>
    
    Specified by:
    
    cancel in interface java.util.concurrent.Future<T>
  - isCancelled
```
public boolean isCancelled()
```
    Specified by:
    
    isCancelled in interface java.util.concurrent.Future<T>
  - isDone
```
public boolean isDone()
```
    Specified by:
    
    isDone in interface java.util.concurrent.Future<T>
  - isError
```
public boolean isError()
```
    Returns true if the task has had an error. Only true if calling get() will throw an exception when it completes (including cancel). Implementations may set this true before completion if they have that insight, or (the default) they may compute it lazily after completion (returning false before completion).
    
    Specified by:
    
    isError in interface Task<T>
  - get
```
public T get()
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException
```
    Specified by:
    
    get in interface java.util.concurrent.Future<T>
    
    Throws:
    
    java.lang.InterruptedException
    
    java.util.concurrent.ExecutionException
  - getUnchecked
```
public T getUnchecked()
```
    Description copied from interface: Task
    
    As Future.get(), but propagating checked exceptions as unchecked for convenience.
    
    Specified by:
    
    getUnchecked in interface Task<T>
  - blockUntilStarted
```
public void blockUntilStarted()
```
    Description copied from interface: Task
    
    Causes calling thread to block until the task is started.
    
    Specified by:
    
    blockUntilStarted in interface Task<T>
  - blockUntilStarted
```
public boolean blockUntilStarted(Duration timeout)
```
    Specified by:
    
    blockUntilStarted in interface TaskInternal<T>
  - blockUntilEnded
```
public void blockUntilEnded()
```
    Description copied from interface: Task
    
    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.)
    
    Specified by:
    
    blockUntilEnded in interface Task<T>
  - blockUntilEnded
```
public boolean blockUntilEnded(Duration timeout)
```
    Description copied from interface: Task
    
    As Task.blockUntilEnded(), but returning after the given timeout; true if the task has ended and false otherwise
    
    Specified by:
    
    blockUntilEnded in interface Task<T>
  - get
```
public T get(long timeout,
    java.util.concurrent.TimeUnit unit)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException
```
    Specified by:
    
    get in interface java.util.concurrent.Future<T>
    
    Throws:
    
    java.lang.InterruptedException
    
    java.util.concurrent.ExecutionException
    
    java.util.concurrent.TimeoutException
  - get
```
public T get(Duration duration)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException
```
    Description copied from interface: Task
    
    As Future.get(long, java.util.concurrent.TimeUnit)
    
    Specified by:
    
    get in interface Task<T>
    
    Throws:
    
    java.lang.InterruptedException
    
    java.util.concurrent.ExecutionException
    
    java.util.concurrent.TimeoutException
  - getUnchecked
```
public T getUnchecked(Duration duration)
```
    Description copied from interface: Task
    
    As Future.get(), but propagating checked exceptions as unchecked for convenience (including a TimeoutException if the duration expires)
    
    Specified by:
    
    getUnchecked in interface Task<T>
  - getStatusSummary
```
public java.lang.String getStatusSummary()
```
    Returns a brief status string Plain-text format. Reported status if there is one, otherwise state which will be one of:
    - Not submitted
    - Submitted for execution
    - Ended by error
    - Ended by cancellation
    - Ended normally
    - Running
    - Waiting
    Specified by:
    
    getStatusSummary in interface Task<T>
  - getStatusDetail
```
public 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.
    
    Specified by:
    
    getStatusDetail in interface Task<T>
  - getDisplayName
```
public java.lang.String getDisplayName()
```
    Specified by:
    
    getDisplayName in interface Task<T>
  - getDescription
```
public java.lang.String getDescription()
```
    Specified by:
    
    getDescription in interface Task<T>
  - setBlockingDetails
```
public java.lang.String setBlockingDetails(java.lang.String blockingDetails)
```
    allows a task user to specify why a task is blocked; for use immediately before a blocking/wait, and typically cleared immediately afterwards; referenced by management api to inspect a task which is blocking
    
    Specified by:
    
    setBlockingDetails in interface TaskInternal<T>
  - setBlockingTask
```
public Task<?> setBlockingTask(Task<?> blockingTask)
```
    Description copied from interface: TaskInternal
    
    as TaskInternal.setBlockingDetails(String) but records a task which is blocking, for use e.g. in a gui to navigate to the current active subtask
    returns previous blocking task, in case caller wishes to recall and restore it
    
    Specified by:
    
    setBlockingTask in interface TaskInternal<T>
  - resetBlockingDetails
```
public void resetBlockingDetails()
```
    Specified by:
    
    resetBlockingDetails in interface TaskInternal<T>
  - resetBlockingTask
```
public void resetBlockingTask()
```
    Specified by:
    
    resetBlockingTask in interface TaskInternal<T>
  - getBlockingDetails
```
public java.lang.String getBlockingDetails()
```
    returns a textual message giving details while the task is blocked
    
    Specified by:
    
    getBlockingDetails in interface TaskInternal<T>
  - getBlockingTask
```
public Task<?> getBlockingTask()
```
    returns a task that this task is blocked on
    
    Specified by:
    
    getBlockingTask in interface TaskInternal<T>
  - setExtraStatusText
```
public void setExtraStatusText(java.lang.Object extraStatus)
```
    Specified by:
    
    setExtraStatusText in interface TaskInternal<T>
  - getExtraStatusText
```
public java.lang.Object getExtraStatusText()
```
    Specified by:
    
    getExtraStatusText in interface TaskInternal<T>
  - ignoreIfNotRun
```
public void ignoreIfNotRun()
```
  - setFinalizer
```
public void setFinalizer(BasicTask.TaskFinalizer f)
```
  - addListener
```
public void addListener(java.lang.Runnable listener,
               java.util.concurrent.Executor executor)
```
    Specified by:
    
    addListener in interface com.google.common.util.concurrent.ListenableFuture<T>
  - runListeners
```
public void runListeners()
```
    Specified by:
    
    runListeners in interface TaskInternal<T>
  - setEndTimeUtc
```
public void setEndTimeUtc(long val)
```
    Specified by:
    
    setEndTimeUtc in interface TaskInternal<T>
  - setThread
```
public void setThread(java.lang.Thread thread)
```
    Specified by:
    
    setThread in interface TaskInternal<T>
  - getJob
```
public java.util.concurrent.Callable<T> getJob()
```
    Specified by:
    
    getJob in interface TaskInternal<T>
  - setJob
```
public void setJob(java.util.concurrent.Callable<T> job)
```
    Specified by:
    
    setJob in interface TaskInternal<T>
  - getListeners
```
public com.google.common.util.concurrent.ExecutionList getListeners()
```
    Specified by:
    
    getListeners in interface TaskInternal<T>
  - setSubmitTimeUtc
```
public void setSubmitTimeUtc(long val)
```
    Specified by:
    
    setSubmitTimeUtc in interface TaskInternal<T>
  - setSubmittedByTask
```
public void setSubmittedByTask(Task<?> task)
```
    Specified by:
    
    setSubmittedByTask in interface TaskInternal<T>
  - getMutableTags
```
public java.util.Set<java.lang.Object> getMutableTags()
```
    Specified by:
    
    getMutableTags in interface TaskInternal<T>
  - setStartTimeUtc
```
public void setStartTimeUtc(long val)
```
    Specified by:
    
    setStartTimeUtc in interface TaskInternal<T>
  - applyTagModifier
```
public void applyTagModifier(com.google.common.base.Function<java.util.Set<java.lang.Object>,java.lang.Void> modifier)
```
    Specified by:
    
    applyTagModifier in interface TaskInternal<T>
  - getProxyTarget
```
public Task<?> getProxyTarget()
```
    Description copied from interface: TaskInternal
    
    if a task is a proxy for another one (used mainly for internal tasks), this returns the "real" task represented by this one
    
    Specified by:
    
    getProxyTarget in interface TaskInternal<T>

Class BasicTask<T>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

displayName

description

WARN_IF_NOT_RUN

NO_OP

Constructor Detail

BasicTask

BasicTask

BasicTask

BasicTask

BasicTask

BasicTask

Method Detail

getId

hashCode

equals

toString

asTask

initInternalFuture

getTags

getQueuedTimeUtc

getSubmitTimeUtc

getStartTimeUtc

getEndTimeUtc

getInternalFuture

getSubmittedByTask

getThread

isQueued

isQueuedOrSubmitted

isQueuedAndNotSubmitted

isSubmitted

isBegun

markQueued

cancel

uncancel

cancel

isCancelled

isDone

isError

get

getUnchecked

blockUntilStarted

blockUntilStarted

blockUntilEnded

blockUntilEnded

get

get

getUnchecked

getStatusSummary

getStatusDetail

getDisplayName

getDescription

setBlockingDetails

setBlockingTask

resetBlockingDetails

resetBlockingTask

getBlockingDetails

getBlockingTask

setExtraStatusText

getExtraStatusText

ignoreIfNotRun

setFinalizer

addListener

runListeners

setEndTimeUtc

setThread

getJob

setJob

getListeners

setSubmitTimeUtc

setSubmittedByTask

getMutableTags

setStartTimeUtc

applyTagModifier