javafx.concurrent

Class Task<V>

java.lang.Object

java.util.concurrent.FutureTask<V>

javafx.concurrent.Task<V>

All Implemented Interfaces:

java.lang.Runnable, java.util.concurrent.Future<V>, java.util.concurrent.RunnableFuture<V>, Worker<V>

public abstract class Task<V>
extends java.util.concurrent.FutureTask<V>
implements Worker<V>

A fully observable implementation of a FutureTask. Tasks exposes additional state and observable properties useful for programming asynchronous tasks in JavaFX, as defined in the Worker interface. An implementation of Task must override the call() method. This method is invoked on the background thread. Any state which is used in this method must be safe to read and write from a background thread. For example, manipulating a live scene graph from this method is unsafe and will result in runtime exceptions.

Tasks are flexible and extremely useful for the encapsulation of "work". Because Service is designed to execute a Task, any Tasks defined by the application or library code can easily be used with a Service. Likewise, since Task extends from FutureTask, it is very easy and natural to use a Task with the java concurrency Executor API. Finally, since a Task is Runnable, you can also call it directly (by invoking the FutureTask.run() method) from another background thread. This allows for composition of work, or pass it to a new Thread constructed and executed manually.

Although ExecutorService defines several methods which take a Runnable, you should generally limit yourself to using the execute method inherited from Executor.

As with FutureTask, a Task is a one-shot class and cannot be reused. See Service for a reusable Worker.

Because the Task is designed for use with JavaFX GUI applications, it ensures that every change to its public properties, as well as change notifications for state, errors, and for event handlers, all occur on the main JavaFX application thread. Accessing these properties from a background thread (including the call() method) will result in runtime exceptions being raised.

It is strongly encouraged that all Tasks be initialized with immutable state upon which the Task will operate. This should be done by providing a Task constructor which takes the parameters necessary for execution of the Task. Immutable state makes it easy and safe to use from any thread and ensures correctness in the presence of multiple threads.

Property Summary

Properties

Type	Property and Description
ReadOnlyObjectProperty<java.lang.Throwable>	exception Gets the ReadOnlyObjectProperty representing any exception which occurred.
ReadOnlyStringProperty	message Gets the ReadOnlyStringProperty representing the message.
ReadOnlyDoubleProperty	progress Gets the ReadOnlyLongProperty representing the progress.
ReadOnlyBooleanProperty	running Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
ReadOnlyObjectProperty<Worker.State>	state Gets the ReadOnlyObjectProperty representing the current state.
ReadOnlyStringProperty	title Gets the ReadOnlyStringProperty representing the title.
ReadOnlyDoubleProperty	totalWork Gets the ReadOnlyLongProperty representing the maximum amount of work that needs to be done.
ReadOnlyObjectProperty<V>	value Gets the ReadOnlyObjectProperty representing the value.
ReadOnlyDoubleProperty	workDone Gets the ReadOnlyLongProperty representing the current progress.

Nested Class Summary

Nested classes/interfaces inherited from interface javafx.concurrent.Worker

Worker.State

Constructor Summary

Constructors

Constructor and Description
Task() Creates a new Task.

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract V	call() Invoked when the Task is executed, the call method must be overridden and implemented by subclasses.
boolean	cancel() Terminates execution of this Worker.
boolean	cancel(boolean mayInterruptIfRunning)
ReadOnlyObjectProperty<java.lang.Throwable>	exceptionProperty() Gets the ReadOnlyObjectProperty representing any exception which occurred.
java.lang.Throwable	getException() Indicates the exception which occurred while the Worker was running, if any.
java.lang.String	getMessage() Gets a message associated with the current state of this Worker.
double	getProgress() Indicates the current progress of this Worker in terms of percent complete.
Worker.State	getState() Specifies the current state of this Worker.
java.lang.String	getTitle() An optional title that should be associated with this Worker.
double	getTotalWork() Indicates a maximum value for the Worker.workDoneProperty() property.
V	getValue() Specifies the value, or result, of this Worker.
double	getWorkDone() Indicates the current amount of work that has been completed.
boolean	isRunning() True if the state is either SCHEDULED or RUNNING.
ReadOnlyStringProperty	messageProperty() Gets the ReadOnlyStringProperty representing the message.
ReadOnlyDoubleProperty	progressProperty() Gets the ReadOnlyLongProperty representing the progress.
ReadOnlyBooleanProperty	runningProperty() Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
ReadOnlyObjectProperty<Worker.State>	stateProperty() Gets the ReadOnlyObjectProperty representing the current state.
ReadOnlyStringProperty	titleProperty() Gets the ReadOnlyStringProperty representing the title.
ReadOnlyDoubleProperty	totalWorkProperty() Gets the ReadOnlyLongProperty representing the maximum amount of work that needs to be done.
protected void	updateMessage(java.lang.String message) Updates the message property.
protected void	updateProgress(long workDone, long max) Updates the workDone, totalWork, and progress properties.
protected void	updateTitle(java.lang.String title) Updates the title property.
ReadOnlyObjectProperty<V>	valueProperty() Gets the ReadOnlyObjectProperty representing the value.
ReadOnlyDoubleProperty	workDoneProperty() Gets the ReadOnlyLongProperty representing the current progress.

Methods inherited from class java.util.concurrent.FutureTask

done, get, get, isCancelled, isDone, run, runAndReset, set, setException

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Property Detail

state

Specified by:

stateProperty in interface Worker<V>

Returns:

See Also:

getState()

value

Specified by:

valueProperty in interface Worker<V>

Returns:

See Also:

getValue()

exception

Specified by:

exceptionProperty in interface Worker<V>

Returns:

See Also:

getException()

workDone

Specified by:

workDoneProperty in interface Worker<V>

Returns:

See Also:

getWorkDone()

totalWork

Specified by:

totalWorkProperty in interface Worker<V>

Returns:

See Also:

getTotalWork()

progress

Specified by:

progressProperty in interface Worker<V>

Returns:

See Also:

getProgress()

running

Specified by:

runningProperty in interface Worker<V>

Returns:

See Also:

isRunning()

message

Specified by:

messageProperty in interface Worker<V>

Returns:

See Also:

getMessage()

title

Specified by:

titleProperty in interface Worker<V>

Returns:

See Also:

getTitle()

Constructor Detail

Task

public Task()

Creates a new Task.

Method Detail

call

protected abstract V call()
                   throws java.lang.Exception

Invoked when the Task is executed, the call method must be overridden and implemented by subclasses. The call method actually performs the background thread logic. Only the updateProgress, updateMessage, and updateTitle methods of Task may be called from code within this method. Any other interaction with the Task from the background thread will result in runtime exceptions.

Returns:

The result of the background work, if any.

Throws:

java.lang.Exception

getState

public final Worker.State getState()

Description copied from interface: Worker

Specifies the current state of this Worker. The initial value is State.READY. A Task may be restarted, in which case it will progress from one of these end states (SUCCEEDED, CANCELLED, or FAILED) back to READY and then immediately to SCHEDULED and RUNNING. These state transitions may occur immediately one after the other, but will always occur in the prescribed order.

Specified by:

getState in interface Worker<V>

stateProperty

public final ReadOnlyObjectProperty<Worker.State> stateProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing the current state.

Specified by:

stateProperty in interface Worker<V>

Returns:

See Also:

getState()

getValue

public final V getValue()

Description copied from interface: Worker

Specifies the value, or result, of this Worker. This is set upon entering the SUCCEEDED state, and cleared (set to null) if the Worker is reinitialized (that is, if the Worker is a reusable Worker and is reset or restarted).

Specified by:

getValue in interface Worker<V>

valueProperty

public final ReadOnlyObjectProperty<V> valueProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing the value.

Specified by:

valueProperty in interface Worker<V>

Returns:

See Also:

getValue()

getException

public final java.lang.Throwable getException()

Description copied from interface: Worker

Indicates the exception which occurred while the Worker was running, if any. If this property value is null, there is no known exception, even if the status is FAILED. If this property is not null, it will most likely contain an exception that describes the cause of failure.

Specified by:

getException in interface Worker<V>

exceptionProperty

public final ReadOnlyObjectProperty<java.lang.Throwable> exceptionProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing any exception which occurred.

Specified by:

exceptionProperty in interface Worker<V>

Returns:

See Also:

getException()

getWorkDone

public final double getWorkDone()

Description copied from interface: Worker

Indicates the current amount of work that has been completed. Zero or a positive value indicate progress toward completion. This variable's value may or may not change from its default value depending on the specific Worker implementation. A value of -1 means that the current amount of work done cannot be determined (ie: it is indeterminate). The value of this property is always less than or equal to totalWork.

Specified by:

getWorkDone in interface Worker<V>

See Also:

Worker.totalWorkProperty(), Worker.progressProperty()

workDoneProperty

public final ReadOnlyDoubleProperty workDoneProperty()

Description copied from interface: Worker

Gets the ReadOnlyLongProperty representing the current progress.

Specified by:

workDoneProperty in interface Worker<V>

Returns:

See Also:

getWorkDone()

getTotalWork

public final double getTotalWork()

Description copied from interface: Worker

Indicates a maximum value for the Worker.workDoneProperty() property. The totalWork will either be -1 (indicating that the amount of work to do is indeterminate), or it will be a non-zero value less than or equal to Long.MAX_VALUE.

Specified by:

getTotalWork in interface Worker<V>

See Also:

Worker.workDoneProperty(), Worker.progressProperty()

totalWorkProperty

public final ReadOnlyDoubleProperty totalWorkProperty()

Description copied from interface: Worker

Gets the ReadOnlyLongProperty representing the maximum amount of work that needs to be done. These "work units" have meaning to the Worker implementation, such as the number of bytes that need to be downloaded or the number of images to process or some other such metric.

Specified by:

totalWorkProperty in interface Worker<V>

Returns:

See Also:

getTotalWork()

getProgress

public final double getProgress()

Description copied from interface: Worker

Indicates the current progress of this Worker in terms of percent complete. A value between zero and one indicates progress toward completion. A value of -1 means that the current progress cannot be determined (that is, it is indeterminate). This property may or may not change from its default value of -1 depending on the specific Worker implementation.

Specified by:

getProgress in interface Worker<V>

See Also:

Worker.workDoneProperty(), Worker.totalWorkProperty()

progressProperty

public final ReadOnlyDoubleProperty progressProperty()

Description copied from interface: Worker

Gets the ReadOnlyLongProperty representing the progress.

Specified by:

progressProperty in interface Worker<V>

Returns:

See Also:

getProgress()

isRunning

public final boolean isRunning()

Description copied from interface: Worker

True if the state is either SCHEDULED or RUNNING. When binding a Worker to a ProgressIndicator, you will typically bind the visibility of the ProgressIndicator to the Worker's running property, and the progress of the ProgressIndicator to the Worker's progress property.

Specified by:

isRunning in interface Worker<V>

runningProperty

public final ReadOnlyBooleanProperty runningProperty()

Description copied from interface: Worker

Gets the ReadOnlyBooleanProperty representing whether the Worker is running.

Specified by:

runningProperty in interface Worker<V>

Returns:

See Also:

isRunning()

getMessage

public final java.lang.String getMessage()

Description copied from interface: Worker

Gets a message associated with the current state of this Worker. This may be something such as "Processing image 1 of 3", for example.

Specified by:

getMessage in interface Worker<V>

Returns:

messageProperty

public final ReadOnlyStringProperty messageProperty()

Description copied from interface: Worker

Gets the ReadOnlyStringProperty representing the message.

Specified by:

messageProperty in interface Worker<V>

Returns:

See Also:

getMessage()

getTitle

public final java.lang.String getTitle()

Description copied from interface: Worker

An optional title that should be associated with this Worker. This may be something such as "Modifying Images".

Specified by:

getTitle in interface Worker<V>

Returns:

titleProperty

public final ReadOnlyStringProperty titleProperty()

Description copied from interface: Worker

Gets the ReadOnlyStringProperty representing the title.

Specified by:

titleProperty in interface Worker<V>

Returns:

See Also:

getTitle()

cancel

public final boolean cancel()

Description copied from interface: Worker

Terminates execution of this Worker. Calling this method will either remove this Worker from the execution queue or stop execution.

Specified by:

cancel in interface Worker<V>

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Specified by:

cancel in interface java.util.concurrent.Future<V>

Overrides:

cancel in class java.util.concurrent.FutureTask<V>

updateProgress

protected void updateProgress(long workDone,
                  long max)

Updates the workDone, totalWork, and progress properties. Calls to updateProgress are coalesced and run later on the FX application thread, and calls to updateProgress, even from the FX Application thread, may not necessarily result in immediate updates to these properties, and intermediate workDone values may be coalesced to save on event notifications. max becomes the new value for totalWork.

This method is safe to be called from any thread.

Parameters:

workDone - A value from -1 up to max. If the value is greater than max, an illegal argument exception is thrown. If the value passed is -1, then the resulting percent done will be -1 (thus, indeterminate).

max - A value from -1 to Long.MAX_VALUE. Any value outside this range results in an IllegalArgumentException.

updateMessage

protected void updateMessage(java.lang.String message)

Updates the message property. Calls to updateMessage are coalesced and run later on the FX application thread, so calls to updateMessage, even from the FX Application thread, may not necessarily result in immediate updates to this property, and intermediate message values may be coalesced to save on event notifications.

This method is safe to be called from any thread.

Parameters:

message - the new message

updateTitle

protected void updateTitle(java.lang.String title)

Updates the title property. Calls to updateTitle are coalesced and run later on the FX application thread, so calls to updateTitle, even from the FX Application thread, may not necessarily result in immediate updates to this property, and intermediate title values may be coalesced to save on event notifications.

This method is safe to be called from any thread.

Parameters:

title - the new title