Module javafx.graphics
Package javafx.concurrent

# Interface Worker<V>

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 enum`
  `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 the `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 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> stateProperty
    Gets the ReadOnlyObjectProperty representing the current state.
    See Also:
      - `getState()`
      - `stateProperty()`

  - ### value

    ReadOnlyObjectProperty<V> valueProperty
    Gets the ReadOnlyObjectProperty representing the value.
    See Also:
      - `getValue()`
      - `valueProperty()`

  - ### exception

    ReadOnlyObjectProperty<Throwable> exceptionProperty
    Gets the ReadOnlyObjectProperty representing any exception which occurred.
    See Also:
      - `getException()`
      - `exceptionProperty()`

  - ### workDone

    ReadOnlyDoubleProperty workDoneProperty
    Gets the ReadOnlyDoubleProperty representing the current progress.
    See Also:
      - `getWorkDone()`
      - `workDoneProperty()`

  - ### totalWork

    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()`
      - `totalWorkProperty()`

  - ### progress

    ReadOnlyDoubleProperty progressProperty
    Gets the ReadOnlyDoubleProperty representing the progress.
    See Also:
      - `getProgress()`
      - `progressProperty()`

  - ### running

    ReadOnlyBooleanProperty runningProperty
    Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
    See Also:
      - `isRunning()`
      - `runningProperty()`

  - ### message

    ReadOnlyStringProperty messageProperty
    Gets the ReadOnlyStringProperty representing the message.
    See Also:
      - `getMessage()`
      - `messageProperty()`

  - ### title

    ReadOnlyStringProperty titleProperty
    Gets the ReadOnlyStringProperty representing the title.
    See Also:
      - `getTitle()`
      - `titleProperty()`

- ## 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.
    Returns:
      The property representing the 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.
    Returns:
      The property representing the current value
    See Also:
      - `getValue()`

  - ### getException

    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:
      the exception, if one occurred

  - ### exceptionProperty

    ReadOnlyObjectProperty<Throwable> exceptionProperty()
    Gets the ReadOnlyObjectProperty representing any exception which occurred.
    Returns:
      the property representing the exception
    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.
    Returns:
      The property representing the amount of work done
    See Also:
      - `getWorkDone()`

  - ### getTotalWork

    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:
      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.
    Returns:
      the property representing the total work to be done
    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.
    Returns:
      the property representing the progress
    See Also:
      - `getProgress()`

  - ### isRunning

    boolean isRunning()
    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.
    Returns:
      true if this Worker is running

  - ### runningProperty

    ReadOnlyBooleanProperty runningProperty()
    Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
    Returns:
      the property 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.
    Returns:
      a property representing the current 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.
    Returns:
      the property representing the current 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