A Worker is an object which performs some work in one or more background threads, and whose state is observable and available to JavaFX applications and is usable from the main JavaFX Application thread. This interface is primarily implemented by both Task and Service, providing a common API among both classes which makes it easier for libraries and frameworks to provide workers which work well when developing user interfaces.

A Worker may or may not be reusable depending on the implementation. A Task, for example, is not reusable while a Service is.

A Worker has a well defined life cycle. Every Worker begins in the State#READY state. When the Worker has been scheduled for work (for example, when a Service's javafx.concurrent.Service#start() method is called), it is transitioned to State#SCHEDULED. Even Workers which are not technically scheduled, but started immediately (such as with javafx.concurrent.Task#run()) will transition through the State#SCHEDULED on its way to the State#RUNNING state.

When the Worker is actually performing its work, the state will have been transitioned to State#RUNNING. If the Worker completes normally, it will end in the State#SUCCEEDED state, and the result of the Worker will be set as the value property. If however an Exception occurs during the execution of the Worker, then the state will be set to State#FAILED and the exception property will be set to the Exception which occurred.

At any time prior to the conclusion of the Worker (that is, if the state is not already State#SUCCEEDED or State#FAILED) the developer may invoke the javafx.concurrent.Worker#cancel() method. If called, the Worker will cease execution (if possible, including use of Thread.interrupt) and the state changed to State#CANCELLED.

The only valid beginning state for a Worker is State#READY, and the valid ending states are State#CANCELLED, State#SUCCEEDED, and State#FAILED. The running property is set to true when the state is either State#SCHEDULED or State#RUNNING.

The Worker's progress can be monitored via three different properties, totalWork, workDone, and progress. These properties are set by the actual implementation of the Worker interface, but can be observed by anybody. The workDone is a number between -1 (meaning indeterminate progress) and totalWork, inclusive. When workDone == totalWork the progress will be 100% (or 1). totalWork will be a number between -1 and Long.MAX_VALUE, inclusive. The progress will be either -1 (meaning indeterminate), or a value between 0 and 1, inclusive, representing 0% through 100%.

A Worker which is in the State#READY or State#SCHEDULED states will always have workDone and progress set to -1. A Worker which is in the State#SUCCEEDED state will always have workDone == totalWork and progress == 1. In any other state, the values for these properties may be any value in their respective valid ranges.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	Worker.State The state of a Worker.

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: returns true if the cancel was successful cancel() Terminates execution of this Worker.
public ReadOnlyObjectProperty<Throwable>	Returns: the property representing the exception exceptionProperty() Gets the ReadOnlyObjectProperty representing any exception which occurred.
public Throwable	Returns: the exception, if one occurred getException() Indicates the exception which occurred while the Worker was running, if any.
public String	Returns: the current message getMessage() Gets a message associated with the current state of this Worker.
public double	Returns: the current progress getProgress() Indicates the current progress of this Worker in terms of percent complete.
public Worker.State	Returns: The current state of this Worker getState() Specifies the current state of this Worker.
public String	Returns: the current title getTitle() An optional title that should be associated with this Worker.
public double	Returns: the total work to be done getTotalWork() Indicates a maximum value for the `workDoneProperty` property.
public V	Returns: the current value of this Worker getValue() Specifies the value, or result, of this Worker.
public double	Returns: the amount of work done getWorkDone() Indicates the current amount of work that has been completed.
public boolean	Returns: true if this Worker is running isRunning() True if the state is either SCHEDULED or RUNNING.
public ReadOnlyStringProperty	Returns: a property representing the current message messageProperty() Gets the ReadOnlyStringProperty representing the message.
public ReadOnlyDoubleProperty	Returns: the property representing the progress progressProperty() Gets the ReadOnlyDoubleProperty representing the progress.
public ReadOnlyBooleanProperty	Returns: the property representing whether the worker is running runningProperty() Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
public ReadOnlyObjectProperty<Worker.State>	Returns: The property representing the state stateProperty() Gets the ReadOnlyObjectProperty representing the current state.
public ReadOnlyStringProperty	Returns: the property representing the current title titleProperty() Gets the ReadOnlyStringProperty representing the title.
public ReadOnlyDoubleProperty	Returns: the property representing the total work to be done totalWorkProperty() Gets the ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.
public ReadOnlyObjectProperty<V>	Returns: The property representing the current value valueProperty() Gets the ReadOnlyObjectProperty representing the value.
public ReadOnlyDoubleProperty	Returns: The property representing the amount of work done workDoneProperty() Gets the ReadOnlyDoubleProperty representing the current progress.

Method Detail

cancel	back to summary
public boolean cancel() Terminates execution of this Worker. Calling this method will either remove this Worker from the execution queue or stop execution. Returns:boolean returns true if the cancel was successful

cancel

back to summary

public boolean cancel()

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

Returns:boolean: returns true if the cancel was successful

exceptionProperty	back to summary
public ReadOnlyObjectProperty<Throwable> exceptionProperty() Gets the ReadOnlyObjectProperty representing any exception which occurred. Returns:ReadOnlyObjectProperty<Throwable> the property representing the exception

exceptionProperty

back to summary

public ReadOnlyObjectProperty<Throwable> exceptionProperty()

Gets the ReadOnlyObjectProperty representing any exception which occurred.

Returns:ReadOnlyObjectProperty<Throwable>: the property representing the exception

getException back to summary

getException	back to summary
public Throwable getException() 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. Returns:Throwable the exception, if one occurred

public Throwable getException()

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.

Returns:Throwable: the exception, if one occurred

getMessage	back to summary
public String getMessage() Gets a message associated with the current state of this Worker. This may be something such as "Processing image 1 of 3", for example. Returns:String the current message

getMessage

back to summary

public String getMessage()

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

Returns:String: the current message

getProgress back to summary

getProgress	back to summary
public double getProgress() 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. Returns:double the current progress See Also `workDoneProperty`, `totalWorkProperty`

public double getProgress()

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.

Returns:double: the current progress
See Also: workDoneProperty, totalWorkProperty

getState	back to summary
public Worker.State getState() 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. Returns:Worker.State The current state of this Worker

getState

back to summary

public Worker.State getState()

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.

Returns:Worker.State: The current state of this Worker

getTitle	back to summary
public String getTitle() An optional title that should be associated with this Worker. This may be something such as "Modifying Images". Returns:String the current title

getTitle

back to summary

public String getTitle()

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

Returns:String: the current title

getTotalWork back to summary

getTotalWork	back to summary
public double getTotalWork() Indicates a maximum value for the `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 Double.MAX_VALUE. Returns:double the total work to be done See Also `workDoneProperty`, `progressProperty`

public double getTotalWork()

Indicates a maximum value for the 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 Double.MAX_VALUE.

Returns:double: the total work to be done
See Also: workDoneProperty, progressProperty

getValue	back to summary
public V getValue() 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). Returns:V the current value of this Worker

getValue

back to summary

public V getValue()

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).

Returns:V: the current value of this Worker

getWorkDone back to summary

getWorkDone	back to summary
public double getWorkDone() Indicates the current amount of work that has been completed. Zero or a positive value indicate progress toward completion. This variables 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. Returns:double the amount of work done See Also `totalWorkProperty`, `progressProperty`

public double getWorkDone()

Indicates the current amount of work that has been completed. Zero or a positive value indicate progress toward completion. This variables 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.

Returns:double: the amount of work done
See Also: totalWorkProperty, progressProperty

isRunning back to summary

isRunning	back to summary
public boolean isRunning() True if the state is either SCHEDULED or RUNNING. When binding a Worker to a `javafx.scene.control.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. Returns:boolean true if this Worker is running

public boolean isRunning()

True if the state is either SCHEDULED or RUNNING. When binding a Worker to a javafx.scene.control.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.

Returns:boolean: true if this Worker is running

messageProperty	back to summary
public ReadOnlyStringProperty messageProperty() Gets the ReadOnlyStringProperty representing the message. Returns:ReadOnlyStringProperty a property representing the current message

messageProperty

back to summary

public ReadOnlyStringProperty messageProperty()

Gets the ReadOnlyStringProperty representing the message.

Returns:ReadOnlyStringProperty: a property representing the current message

progressProperty	back to summary
public ReadOnlyDoubleProperty progressProperty() Gets the ReadOnlyDoubleProperty representing the progress. Returns:ReadOnlyDoubleProperty the property representing the progress

progressProperty

back to summary

public ReadOnlyDoubleProperty progressProperty()

Gets the ReadOnlyDoubleProperty representing the progress.

Returns:ReadOnlyDoubleProperty: the property representing the progress

runningProperty	back to summary
public ReadOnlyBooleanProperty runningProperty() Gets the ReadOnlyBooleanProperty representing whether the Worker is running. Returns:ReadOnlyBooleanProperty the property representing whether the worker is running

runningProperty

back to summary

public ReadOnlyBooleanProperty runningProperty()

Gets the ReadOnlyBooleanProperty representing whether the Worker is running.

Returns:ReadOnlyBooleanProperty: the property representing whether the worker is running

stateProperty	back to summary
public ReadOnlyObjectProperty<Worker.State> stateProperty() Gets the ReadOnlyObjectProperty representing the current state. Returns:ReadOnlyObjectProperty<Worker.State> The property representing the state

stateProperty

back to summary

public ReadOnlyObjectProperty<Worker.State> stateProperty()

Gets the ReadOnlyObjectProperty representing the current state.

Returns:ReadOnlyObjectProperty<Worker.State>: The property representing the state

titleProperty	back to summary
public ReadOnlyStringProperty titleProperty() Gets the ReadOnlyStringProperty representing the title. Returns:ReadOnlyStringProperty the property representing the current title

titleProperty

back to summary

public ReadOnlyStringProperty titleProperty()

Gets the ReadOnlyStringProperty representing the title.

Returns:ReadOnlyStringProperty: the property representing the current title

totalWorkProperty	back to summary
public ReadOnlyDoubleProperty totalWorkProperty() Gets the ReadOnlyDoubleProperty 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. Returns:ReadOnlyDoubleProperty the property representing the total work to be done

totalWorkProperty

back to summary

public ReadOnlyDoubleProperty totalWorkProperty()

Gets the ReadOnlyDoubleProperty 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.

Returns:ReadOnlyDoubleProperty: the property representing the total work to be done

valueProperty	back to summary
public ReadOnlyObjectProperty<V> valueProperty() Gets the ReadOnlyObjectProperty representing the value. Returns:ReadOnlyObjectProperty<V> The property representing the current value

valueProperty

back to summary

public ReadOnlyObjectProperty<V> valueProperty()

Gets the ReadOnlyObjectProperty representing the value.

Returns:ReadOnlyObjectProperty<V>: The property representing the current value

workDoneProperty	back to summary
public ReadOnlyDoubleProperty workDoneProperty() Gets the ReadOnlyDoubleProperty representing the current progress. Returns:ReadOnlyDoubleProperty The property representing the amount of work done

workDoneProperty

back to summary

public ReadOnlyDoubleProperty workDoneProperty()

Gets the ReadOnlyDoubleProperty representing the current progress.

Returns:ReadOnlyDoubleProperty: The property representing the amount of work done

javafx.concurrent back to summary

public final Enum Worker.State

Class Inheritance

extends Enum<Worker.State>

java.lang.Object
java.lang.Enum
javafx.concurrent.Worker.State

The state of a Worker. The state transitions in a Worker are very well defined. All Workers begin in the READY state. In some circumstances, a Worker might be scheduled for execution before it is actually executed. In such cases, it is sometimes useful to know when the Worker has been SCHEDULED separately from when it is RUNNING. However even in cases where the Worker is executed immediately, the Worker will temporarily enter the SCHEDULED state before entering the RUNNING state. That is, the transition is always from READY to SCHEDULED to RUNNING (unless of course the Worker in cancelled).

A Worker which runs but is never cancelled can only end up in one of two states, either SUCCEEDED or FAILED. It only enters FAILED if an exception was thrown during the execution of the Worker. A Worker may be cancelled when READY, SCHEDULED, or RUNNING, in which case the final status will be CANCELLED. When a Worker is cancelled in one of these circumstances it will transition immediately to the CANCELLED state.

A reusable Worker will transition from CANCELLED, SUCCEEDED or FAILED back to READY. From that point the normal state transitions are again followed.

Since: JavaFX 2.0

Field Summary

Modifier and Type	Field and Description
public static final Worker.State	CANCELLED Indicates that this Worker has been cancelled via the `cancel()` method.
public static final Worker.State	FAILED Indicates that this Worker has failed, usually due to some unexpected condition having occurred.
public static final Worker.State	READY Indicates that the Worker has not yet been executed and is ready to be executed, or that it has been reinitialized.
public static final Worker.State	RUNNING Indicates that this Worker is running.
public static final Worker.State	SCHEDULED Indicates that the Worker has been scheduled for execution, but that it is not currently running.
public static final Worker.State	SUCCEEDED Indicates that this Worker has completed successfully, and that there is a valid result ready to be read from the `value` property.

Constructor Summary

Access	Constructor and Description
private	State()

Method Summary

Modifier and Type	Method and Description
public static Worker.State	valueOf(String name)
public static Worker.State[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

CANCELLED	back to summary
public static final Worker.State CANCELLED Indicates that this Worker has been cancelled via the `cancel()` method.

FAILED	back to summary
public static final Worker.State FAILED Indicates that this Worker has failed, usually due to some unexpected condition having occurred. The exception can be retrieved from the `exception` property.

READY	back to summary
public static final Worker.State READY Indicates that the Worker has not yet been executed and is ready to be executed, or that it has been reinitialized. This is the default initial state of the Worker.

RUNNING	back to summary
public static final Worker.State RUNNING Indicates that this Worker is running. This is set just immediately prior to the Worker actually doing its first bit of work.

SCHEDULED	back to summary
public static final Worker.State SCHEDULED Indicates that the Worker has been scheduled for execution, but that it is not currently running. This might be because the Worker is waiting for a thread in a thread pool to become available before it can start running.

SUCCEEDED	back to summary
public static final Worker.State SUCCEEDED Indicates that this Worker has completed successfully, and that there is a valid result ready to be read from the `value` property.

Constructor Detail

State	back to summary
private State()

Method Detail

valueOf	back to summary
public static Worker.State valueOf(String name)

values	back to summary
public static Worker.State[] values()

public Interface Worker<V>

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum Worker.State

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail