com.atlassian.jira.task

Interface TaskManager

All Known Implementing Classes:

TaskManagerImpl

public interface TaskManager

The TaskManager contains a collection of tasks that are long running. It schedules them to run at its discretion, but it does try to run them as soon as possible, assuming there is sufficient resources available.

Tasks are described operationally by TaskDescriptor.

NOTE: All task descriptors returned are a snapshot of the task state when the method returns. So while the task may finish, the TaskDescriptor will not be updated to reflect that. You must always re-ask the TaskManager for a new TaskDescriptor to find out if a task has finished or not.

Since:

v3.13

Method Summary

Modifier and Type	Method and Description
boolean	awaitUntilActiveTasksComplete(long seconds) Waits on the TaskManager until all current active tasks are completed.
void	cancelTask(Long taskId) Cancel a running task.
void	cancelTaskIfRunningLocally(Long taskId) Cancel a running task if it is running on this cluster node.
TaskDescriptor<?>	findFirstTask(TaskMatcher matcher) Find the first task that "matches" according to the passed matcher.
Collection<TaskDescriptor<?>>	findTasks(TaskMatcher matcher) Find all the tasks that "match" according to the passed matcher.
Collection<TaskDescriptor<?>>	getAllTasks() Return a collection of TaskDescriptors currently within the manager.
<V extends Serializable> TaskDescriptor<V>	getLiveTask(TaskContext taskContext) Return the live task associated with the passed context, if one exists.
Collection<TaskDescriptor<?>>	getLiveTasks() Return a collection of submitted or running TaskDescriptors in the manager.
<V extends Serializable> TaskDescriptor<V>	getTask(Long taskId) Returns the TaskDescriptor of the task that is identified by the passed id.
boolean	hasLiveTaskWithContext(TaskContext taskContext) Returns true if the there are live tasks (running or submitted) that have a task context that is EQUAL to the passed in taskContext.
boolean	hasTaskWithContext(TaskContext taskContext) Returns true if the there are any tasks (submitted, running or finished) that have a task context that is EQUAL to the passed in taskContext.
boolean	isCancellable(Long taskId) Returns true if the task can be cancelled.
boolean	isCancelled(Long taskId) Return true if this task has been cancelled.
void	removeTask(Long taskId) Remove a task from the manager.
boolean	shutdownAndWait(long timeout, TimeUnit unit) Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.
void	shutdownNow() Attempts to aggressively stop all actively executing tasks, halts the processing of waiting tasks.
void	start() Start the task manager.
<V extends Serializable> TaskDescriptor<V>	submitTask(Callable<V> callable, String taskDescription, TaskContext taskContext) This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon.
<V extends Serializable> TaskDescriptor<V>	submitTask(Callable<V> callable, String taskDescription, TaskContext taskContext, boolean cancellable) This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon.
<V extends Serializable> TaskDescriptor<V>	submitTask(Callable<V> callable, String taskDescription, TaskContext taskContext, boolean cancellable, SpanningOperation spanningOperation) This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon.
void	waitUntilTaskCompletes(Long taskId) Wait for a specific task to complete.

Method Detail

getAllTasks

Collection<TaskDescriptor<?>> getAllTasks()

Return a collection of TaskDescriptors currently within the manager. This will include tasks that are yet to start, tasks that are running and completed tasks.

The returned collection is sorted by task id, which should be in addition order.

Returns:

a collection of TaskDescriptors. The descriptors returned are a snapshot of each task state when the method returns will not reflect any future changes. An empty collection is returned when there are no current tasks.

getLiveTasks

Collection<TaskDescriptor<?>> getLiveTasks()

Return a collection of submitted or running TaskDescriptors in the manager.

The returned collection is sorted by task id, which should be in addition order.

Returns:

a collection of running TaskDescriptors. The descriptors returned are a snapshot of each task state when the method returns and will not reflect any future changes. An empty collection is returned when there are no descriptors to return.

getLiveTask

<V extends Serializable> TaskDescriptor<V> getLiveTask(@Nonnull
                                                       TaskContext taskContext)

Return the live task associated with the passed context, if one exists.

Parameters:

taskContext - the context to search for.

Returns:

currently live task associated with the passed context. The descriptor returned is a snapshot of the task state when the method returns will not reflect any future changes. null will be returned when no matching task can be found.

getTask

<V extends Serializable> TaskDescriptor<V> getTask(Long taskId)

Returns the TaskDescriptor of the task that is identified by the passed id.

Parameters:

taskId - the id of the task to retrieve, if null then null will be returned

Returns:

a TaskDescriptor or null if the manager has not such task. The descriptor returned is a snapshot of the task state when the method returns will not reflect any future changes. null will be returned when no matching task can be found.

submitTask

<V extends Serializable> TaskDescriptor<V> submitTask(@Nonnull
                                                      Callable<V> callable,
                                                      @Nonnull
                                                      String taskDescription,
                                                      @Nonnull
                                                      TaskContext taskContext)
                                               throws RejectedExecutionException,
                                                      AlreadyExecutingException

This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon. The TaskDescriptor returned is a snapshot of the task's state when the method returns and will not change to reflect the task's future state changes. The task's ID can be found in the returned TaskDescriptor. The task is not cancellable.

Parameters:

callable - the long running task

taskDescription - the description of the task

taskContext - some stateful context that the task knows about

Returns:

a TaskDescriptor for the new long running task. The returned descriptor is a snapshot of the task state when the method returns and will not reflect any future changes.

Throws:

RejectedExecutionException - if the task manager is being shutdown and cannot accept new tasks.

AlreadyExecutingException - if a task with an equal TaskContext is already running in the task manager.

submitTask

<V extends Serializable> TaskDescriptor<V> submitTask(@Nonnull
                                                      Callable<V> callable,
                                                      @Nonnull
                                                      String taskDescription,
                                                      @Nonnull
                                                      TaskContext taskContext,
                                                      boolean cancellable)
                                               throws RejectedExecutionException,
                                                      AlreadyExecutingException

This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon. The TaskDescriptor returned is a snapshot of the task's state when the method returns and will not change to reflect the task's future state changes. The task's ID can be found in the returned TaskDescriptor.

Parameters:

callable - the long running task

taskDescription - the description of the task

taskContext - some stateful context that the task knows about

cancellable - If set to true indicates that this potentially long running task supports being cancelled.

Returns:

a TaskDescriptor for the new long running task. The returned descriptor is a snapshot of the task state when the method returns and will not reflect any future changes.

Throws:

RejectedExecutionException - if the task manager is being shutdown and cannot accept new tasks.

AlreadyExecutingException - if a task with an equal TaskContext is already running in the task manager.

Since:

v5.2

submitTask

<V extends Serializable> TaskDescriptor<V> submitTask(@Nonnull
                                                      Callable<V> callable,
                                                      @Nonnull
                                                      String taskDescription,
                                                      @Nonnull
                                                      TaskContext taskContext,
                                                      boolean cancellable,
                                                      @Nullable
                                                      SpanningOperation spanningOperation)
                                               throws RejectedExecutionException,
                                                      AlreadyExecutingException

This submits a Callable task to the manager which can then be started at the managers discretion, but hopefully very soon. The TaskDescriptor returned is a snapshot of the task's state when the method returns and will not change to reflect the task's future state changes. The task's ID can be found in the returned TaskDescriptor.

Parameters:

callable - the long running task

taskDescription - the description of the task

taskContext - some stateful context that the task knows about

cancellable - If set to true indicates that this potentially long running task supports being cancelled.

spanningOperation - Operation that this task is part of

Returns:

a TaskDescriptor for the new long running task. The returned descriptor is a snapshot of the task state when the method returns and will not reflect any future changes.

Throws:

RejectedExecutionException - if the task manager is being shutdown and cannot accept new tasks.

AlreadyExecutingException - if a task with an equal TaskContext is already running in the task manager.

Since:

v7.13

removeTask

void removeTask(@Nonnull
                Long taskId)

Remove a task from the manager. The task will still continue to execute if it has not already completed.

Parameters:

taskId - the task identifier.

cancelTask

void cancelTask(@Nonnull
                Long taskId)
         throws IllegalStateException

Cancel a running task. If the task is not running this message is a no-op.

Parameters:

taskId - the task identifier.

Throws:

IllegalStateException - if the task is not cancellable

cancelTaskIfRunningLocally

void cancelTaskIfRunningLocally(@Nonnull
                                Long taskId)

Cancel a running task if it is running on this cluster node.

Parameters:

taskId - the task identifier.

isCancelled

boolean isCancelled(Long taskId)

Return true if this task has been cancelled.

Parameters:

taskId - the task identifier.

Returns:

true if this task has been cancelled

isCancellable

boolean isCancellable(@Nonnull
                      Long taskId)

Returns true if the task can be cancelled. This does not take into account if the task is actually running or not.

Parameters:

taskId - the task identifier.

Returns:

true if the task can be cancelled.

start

void start()

Start the task manager. Normally the task manager starts on construction, but if it is shutdown, you may need to restart it. If the task manager is not shutdown, does nothing.

shutdownAndWait

boolean shutdownAndWait(long timeout,
                        TimeUnit unit)

Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.

It will wait for at most timeout and then return true if the underlying execution threads are terminated completely.

Parameters:

timeout - the maximum time to wait for a graceful shutdown.

unit - the time unit of the timeout argument.

Returns:

true if the underlying execution threads have terminated completely.

shutdownNow

void shutdownNow()

Attempts to aggressively stop all actively executing tasks, halts the processing of waiting tasks.

waitUntilTaskCompletes

void waitUntilTaskCompletes(Long taskId)
                     throws ExecutionException,
                            InterruptedException

Wait for a specific task to complete.

Parameters:

taskId - Id of task to wait for

Throws:

ExecutionException

InterruptedException

awaitUntilActiveTasksComplete

boolean awaitUntilActiveTasksComplete(long seconds)

Waits on the TaskManager until all current active tasks are completed. Calling this method does not stop tasks being added.

Parameters:

seconds - the number of seconds to wait.

Returns:

true if all the active tasks are completed before the timeout, false otherwise.

hasTaskWithContext

boolean hasTaskWithContext(@Nonnull
                           TaskContext taskContext)

Returns true if the there are any tasks (submitted, running or finished) that have a task context that is EQUAL to the passed in taskContext.

Parameters:

taskContext - the specific task context (which implements equals() properly)

Returns:

true if there are any tasks with an equal task context

hasLiveTaskWithContext

boolean hasLiveTaskWithContext(@Nonnull
                               TaskContext taskContext)

Returns true if the there are live tasks (running or submitted) that have a task context that is EQUAL to the passed in taskContext.

Parameters:

taskContext - the specific task context (which implements equals() properly)

Returns:

true if there are any tasks with an equal task context

findFirstTask

TaskDescriptor<?> findFirstTask(@Nonnull
                                TaskMatcher matcher)

Find the first task that "matches" according to the passed matcher.

Parameters:

matcher - the condition used to find the task.

Returns:

the first task that "matches" according to the passed matcher. The descriptor returned is a snapshot of the task state when the method returns will not reflect any future changes. null will be returned when no matching task can be found.

findTasks

Collection<TaskDescriptor<?>> findTasks(@Nonnull
                                        TaskMatcher matcher)

Find all the tasks that "match" according to the passed matcher.

Parameters:

matcher - the condition used to find the task.

Returns:

the tasks that "match" according to the passed matcher. The descriptors returned are a snapshot of the task state when the method returns will not reflect any future changes. An empty collection is returned when no tasks are matched.