Package org.scijava.task

Interface Task

All Superinterfaces:

Cancelable, Named

All Known Implementing Classes:

DefaultTask

public interface Task
extends Cancelable, Named

A self-aware job which reports its status and progress as it runs. There are two ways to use a Task object: - A job can be run asynchronously by using run(Runnable), and can report its progression from within the Runnable. - A Task object can simply be used to report in a synchronous manner the progression of a piece of code. In the case of synchronous reporting, the job is considered started when start() is called and finished when finish() is called. A finished job can be finished either because it is done or because it has been cancelled. A cancel callback can be set with setCancelCallBack(Runnable). The runnable argument will be executed in the case of an external event requesting a cancellation of the task - typically, if a user clicks a cancel button on the GUI, task.cancel("User cancellation requested") will be called. As a result, the task implementors should run the callback. This callback can be used to make the task aware that a cancellation has been requested, and should proceed to stop its execution. See also TaskService, DefaultTask

Author:

Curtis Rueden, Nicolas Chiaruttini

Method Summary

Modifier and Type	Method	Description
default void	finish()	reports that the task is finished - synchronous job
default Runnable	getCancelCallBack()	Returns the current cancel callback runnable, This can be used to concatenate callbacks in order, for instance, to ask for a user confirmation before cancelling the task
long	getProgressMaximum()	Gets the number of steps the task performs in total.
long	getProgressValue()	Gets the step the task is currently performing.
String	getStatusMessage()	Gets a status message describing what the task is currently doing.
boolean	isDone()	Checks whether the task has completed.
default Logger	log()	Gets the logger for output produced while performing the task, such as the lines printed by an external process it runs.
void	run(Runnable r)	Starts running the task - asynchronous job
default void	setCancelCallBack(Runnable runnable)	If the task is cancelled (external call to Cancelable.cancel(String)), the input runnable argument should be executed by task implementors.
void	setProgressMaximum(long max)	Sets the total number of steps.
void	setProgressValue(long step)	Sets the current step.
void	setStatusMessage(String status)	Sets the status message.
default void	start()	reports that the task is started - synchronous job
void	waitFor()	Waits for the task to complete - asynchronous job

Methods inherited from interface org.scijava.Cancelable

cancel, getCancelReason, isCanceled

Methods inherited from interface org.scijava.Named

getName, setName

Method Detail

run

void run(Runnable r)

Starts running the task - asynchronous job

Throws:

IllegalStateException - if the task was already started.

waitFor

void waitFor()
      throws InterruptedException,
             ExecutionException

Waits for the task to complete - asynchronous job

Throws:

IllegalStateException - if run(java.lang.Runnable) has not been called yet.

InterruptedException - if the task is interrupted.

ExecutionException - if the task throws an exception while running.

start

default void start()

reports that the task is started - synchronous job

finish

default void finish()

reports that the task is finished - synchronous job

isDone

boolean isDone()

Checks whether the task has completed.

getStatusMessage

String getStatusMessage()

Gets a status message describing what the task is currently doing.

getProgressValue

long getProgressValue()

Gets the step the task is currently performing.

Returns:

A value between 0 and getProgressMaximum() inclusive.

See Also:

getProgressMaximum()

getProgressMaximum

long getProgressMaximum()

Gets the number of steps the task performs in total.

Returns:

Total number of steps the task will perform, or 0 if unknown.

See Also:

getProgressValue()

setStatusMessage

void setStatusMessage(String status)

Sets the status message. Called by task implementors.

Parameters:

status - The message to set.

See Also:

getStatusMessage()

setProgressValue

void setProgressValue(long step)

Sets the current step. Called by task implementors.

Parameters:

step - The step vaule to set.

See Also:

getProgressValue()

setProgressMaximum

void setProgressMaximum(long max)

Sets the total number of steps. Called by task implementors.

Parameters:

max - The step count to set.

See Also:

getProgressMaximum()

setCancelCallBack

default void setCancelCallBack(Runnable runnable)

If the task is cancelled (external call to Cancelable.cancel(String)), the input runnable argument should be executed by task implementors.

Parameters:

runnable - : should be executed if this task is cancelled through Cancelable.cancel(String)

getCancelCallBack

default Runnable getCancelCallBack()

Returns the current cancel callback runnable, This can be used to concatenate callbacks in order, for instance, to ask for a user confirmation before cancelling the task

log

default Logger log()

Gets the logger for output produced while performing the task, such as the lines printed by an external process it runs. Called by task implementors to emit output, and by interested parties (e.g. a UI showing the task) to listen for it via Logger.addLogListener(org.scijava.log.LogListener).

Task output is kept separate from the application log: messages logged here reach this logger's listeners only.

The default implementation returns a logger that discards everything.