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.