- All Known Implementing Classes:
ScheduledService
,Service
,Task
public interface Worker<V>
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
Worker.State.READY
state. When the Worker has been scheduled for work
(for example, when a Service's Service.start()
method is called), it is transitioned to Worker.State.SCHEDULED
. Even
Workers which are not technically scheduled, but started immediately
(such as with FutureTask.run()
) will transition through
the Worker.State.SCHEDULED
on its way to the Worker.State.RUNNING
state.
When the Worker is actually performing its work, the state will have been
transitioned to Worker.State.RUNNING
. If the Worker completes normally,
it will end in the Worker.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
Worker.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 Worker.State.SUCCEEDED
or Worker.State.FAILED
) the developer
may invoke the cancel()
method. If called, the
Worker will cease execution (if possible, including use of Thread.interrupt)
and the state changed to Worker.State.CANCELLED
.
The only valid beginning state for a Worker is Worker.State.READY
, and the
valid ending states are Worker.State.CANCELLED
, Worker.State.SUCCEEDED
,
and Worker.State.FAILED
. The running
property is set to
true when the state is either Worker.State.SCHEDULED
or Worker.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 Worker.State.READY
or Worker.State.SCHEDULED
states
will always have workDone
and progress
set to -1.
A Worker which is in the Worker.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.
- Since:
- JavaFX 2.0
-
Property Summary
Properties Type Property Description ReadOnlyObjectProperty<Throwable>
exception
Gets the ReadOnlyObjectProperty representing any exception which occurred.ReadOnlyStringProperty
message
Gets the ReadOnlyStringProperty representing the message.ReadOnlyDoubleProperty
progress
Gets the ReadOnlyDoubleProperty 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 ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.ReadOnlyObjectProperty<V>
value
Gets the ReadOnlyObjectProperty representing the value.ReadOnlyDoubleProperty
workDone
Gets the ReadOnlyDoubleProperty representing the current progress. -
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Worker.State
The state of a Worker. -
Method Summary
Modifier and Type Method Description boolean
cancel()
Terminates execution of this Worker.ReadOnlyObjectProperty<Throwable>
exceptionProperty()
Gets the ReadOnlyObjectProperty representing any exception which occurred.Throwable
getException()
Indicates the exception which occurred while the Worker was running, if any.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.String
getTitle()
An optional title that should be associated with this Worker.double
getTotalWork()
Indicates a maximum value for theworkDoneProperty()
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 ReadOnlyDoubleProperty 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 ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.ReadOnlyObjectProperty<V>
valueProperty()
Gets the ReadOnlyObjectProperty representing the value.ReadOnlyDoubleProperty
workDoneProperty()
Gets the ReadOnlyDoubleProperty representing the current progress.
-
Property Details
-
state
ReadOnlyObjectProperty<Worker.State> statePropertyGets the ReadOnlyObjectProperty representing the current state.- See Also:
getState()
-
value
ReadOnlyObjectProperty<V> valuePropertyGets the ReadOnlyObjectProperty representing the value.- See Also:
getValue()
-
exception
ReadOnlyObjectProperty<Throwable> exceptionPropertyGets the ReadOnlyObjectProperty representing any exception which occurred.- See Also:
getException()
-
workDone
ReadOnlyDoubleProperty workDonePropertyGets the ReadOnlyDoubleProperty representing the current progress.- See Also:
getWorkDone()
-
totalWork
ReadOnlyDoubleProperty totalWorkPropertyGets 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.- See Also:
getTotalWork()
-
progress
ReadOnlyDoubleProperty progressPropertyGets the ReadOnlyDoubleProperty representing the progress.- See Also:
getProgress()
-
running
ReadOnlyBooleanProperty runningPropertyGets the ReadOnlyBooleanProperty representing whether the Worker is running.- See Also:
isRunning()
-
message
ReadOnlyStringProperty messagePropertyGets the ReadOnlyStringProperty representing the message.- See Also:
getMessage()
-
title
ReadOnlyStringProperty titlePropertyGets the ReadOnlyStringProperty representing the title.- See Also:
getTitle()
-
-
Method Details
-
getState
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:
- The current state of this Worker
-
stateProperty
ReadOnlyObjectProperty<Worker.State> stateProperty()Gets the ReadOnlyObjectProperty representing the current state.- See Also:
getState()
-
getValue
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:
- the current value of this Worker
-
valueProperty
ReadOnlyObjectProperty<V> valueProperty()Gets the ReadOnlyObjectProperty representing the value.- See Also:
getValue()
-
getException
Throwable getException()Indicates the exception which occurred while the Worker was running, if any. If this property value isnull
, there is no known exception, even if the status is FAILED. If this property is notnull
, it will most likely contain an exception that describes the cause of failure.- Returns:
- the exception, if one occurred
-
exceptionProperty
ReadOnlyObjectProperty<Throwable> exceptionProperty()Gets the ReadOnlyObjectProperty representing any exception which occurred.- See Also:
getException()
-
getWorkDone
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:
- the amount of work done
- See Also:
totalWorkProperty()
,progressProperty()
-
workDoneProperty
ReadOnlyDoubleProperty workDoneProperty()Gets the ReadOnlyDoubleProperty representing the current progress.- See Also:
getWorkDone()
-
getTotalWork
double getTotalWork()Indicates a maximum value for theworkDoneProperty()
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:
- the total work to be done
- See Also:
workDoneProperty()
,progressProperty()
-
totalWorkProperty
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.- See Also:
getTotalWork()
-
getProgress
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:
- the current progress
- See Also:
workDoneProperty()
,totalWorkProperty()
-
progressProperty
ReadOnlyDoubleProperty progressProperty()Gets the ReadOnlyDoubleProperty representing the progress.- See Also:
getProgress()
-
isRunning
boolean isRunning()True if the state is either SCHEDULED or RUNNING. When binding a Worker to aProgressIndicator
, 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:
- true if this Worker is running
-
runningProperty
ReadOnlyBooleanProperty runningProperty()Gets the ReadOnlyBooleanProperty representing whether the Worker is running.- See Also:
isRunning()
-
getMessage
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:
- the current message
-
messageProperty
ReadOnlyStringProperty messageProperty()Gets the ReadOnlyStringProperty representing the message.- See Also:
getMessage()
-
getTitle
String getTitle()An optional title that should be associated with this Worker. This may be something such as "Modifying Images".- Returns:
- the current title
-
titleProperty
ReadOnlyStringProperty titleProperty()Gets the ReadOnlyStringProperty representing the title.- See Also:
getTitle()
-
cancel
boolean cancel()Terminates execution of this Worker. Calling this method will either remove this Worker from the execution queue or stop execution.- Returns:
- returns true if the cancel was successful
-