https://openjdk.java.net/projects/openjfx/javafx-graphics/: OpenJFX JavaFX
  • OpenJFX Mailing List 
/*
 * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javafx.concurrent;

import javafx.beans.property.ReadOnlyBooleanProperty;
import javafx.beans.property.ReadOnlyDoubleProperty;
import javafx.beans.property.ReadOnlyObjectProperty;
import javafx.beans.property.ReadOnlyStringProperty;


 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 Service.start() method is called), it is transitioned to State.SCHEDULED. Even Workers which are not technically scheduled, but started immediately (such as with FutureTask.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 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.



Since:JavaFX 2.0
/**
 * <p>
 *     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 {@link Task} and {@link 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.
 * </p>
 * <p>
 *     A Worker may or may not be reusable depending on the implementation. A
 *     {@link Task}, for example, is not reusable while a {@link Service} is.
 * </p>
 * <p>
 *     A Worker has a well defined life cycle. Every Worker begins in the
 *     {@link State#READY} state. When the Worker has been scheduled for work
 *     (for example, when a Service's {@link javafx.concurrent.Service#start()}
 *     method is called), it is transitioned to {@link State#SCHEDULED}. Even
 *     Workers which are not technically scheduled, but started immediately
 *     (such as with {@link javafx.concurrent.Task#run()}) will transition through
 *     the {@link State#SCHEDULED} on its way to the {@link State#RUNNING} state.
 * </p>
 * <p>
 *     When the Worker is actually performing its work, the state will have been
 *     transitioned to {@link State#RUNNING}. If the Worker completes normally,
 *     it will end in the {@link State#SUCCEEDED} state, and the result of the
 *     Worker will be set as the <code>value</code> property. If however an Exception
 *     occurs during the execution of the Worker, then the state will be set to
 *     {@link State#FAILED} and the <code>exception</code> property will be set
 *     to the Exception which occurred.
 * </p>
 * <p>
 *     At any time prior to the conclusion of the Worker (that is, if the state
 *     is not already {@link State#SUCCEEDED} or {@link State#FAILED}) the developer
 *     may invoke the {@link javafx.concurrent.Worker#cancel()} method. If called, the
 *     Worker will cease execution (if possible, including use of Thread.interrupt)
 *     and the state changed to {@link State#CANCELLED}.
 * </p>
 * <p>
 *     The only valid beginning state for a Worker is {@link State#READY}, and the
 *     valid ending states are {@link State#CANCELLED}, {@link State#SUCCEEDED},
 *     and {@link State#FAILED}. The <code>running</code> property is set to
 *     true when the state is either {@link State#SCHEDULED} or {@link State#RUNNING}.
 * </p>
 * <p>
 *     The Worker's progress can be monitored via three different properties,
 *     <code>totalWork</code>, <code>workDone</code>, and <code>progress</code>.
 *     These properties are set by the actual implementation of the Worker
 *     interface, but can be observed by anybody. The <code>workDone</code> is
 *     a number between -1 (meaning indeterminate progress) and
 *     <code>totalWork</code>, inclusive. When <code>workDone == totalWork</code>
 *     the <code>progress</code> will be 100% (or 1). <code>totalWork</code>
 *     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%.
 * </p>
 * <p>
 *     A Worker which is in the {@link State#READY} or {@link State#SCHEDULED} states
 *     will always have <code>workDone</code> and <code>progress</code> set to -1.
 *     A Worker which is in the {@link State#SUCCEEDED} state will always have
 *     <code>workDone == totalWork</code> and <code>progress == 1</code>. In any
 *     other state, the values for these properties may be any value in their
 *     respective valid ranges.
 * </p>
 * @since JavaFX 2.0
 */
public interface Worker<V> {
    

    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
/**
     * <p>
     *     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).
     * </p>
     * <p>
     *     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.
     * </p>
     * <p>
     *     A reusable Worker will transition from CANCELLED, SUCCEEDED or FAILED back to
     *     READY. From that point the normal state transitions are again followed.
     * </p>
     * @since JavaFX 2.0
     */
    public enum State {
        
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.

/**
         * 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.
         */
        READY,
        
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.

/**
         * 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.
         */
        SCHEDULED,
        
Indicates that this Worker is running. This is set just immediately
prior to the Worker actually doing its first bit of work.

/**
         * Indicates that this Worker is running. This is set just immediately
         * prior to the Worker actually doing its first bit of work.
         */
        RUNNING,
        
Indicates that this Worker has completed successfully, and that there
is a valid result ready to be read from the value property.

/**
         * Indicates that this Worker has completed successfully, and that there
         * is a valid result ready to be read from the <code>value</code> property.
         */
        SUCCEEDED,
        
Indicates that this Worker has been cancelled via the Worker.cancel() method. 
/**
         * Indicates that this Worker has been cancelled via the {@link #cancel()}
         * method.
         */
        CANCELLED,
        
Indicates that this Worker has failed, usually due to some unexpected
condition having occurred. The exception can be retrieved from the
exception property.

/**
         * Indicates that this Worker has failed, usually due to some unexpected
         * condition having occurred. The exception can be retrieved from the
         * <code>exception</code> property.
         */
        FAILED
    }

    
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
/**
     * 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.
     *
     * @return The current state of this Worker
     */
    public State getState();

    
Gets the ReadOnlyObjectProperty representing the current state.

Returns:The property representing the state
/**
     * Gets the ReadOnlyObjectProperty representing the current state.
     *
     * @return The property representing the state
     */
    public ReadOnlyObjectProperty<State> stateProperty();

    
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
/**
     * 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).
     *
     * @return the current value of this Worker
     */
    public V getValue();

    
Gets the ReadOnlyObjectProperty representing the value.

Returns:The property representing the current value
/**
     * Gets the ReadOnlyObjectProperty representing the value.
     *
     * @return The property representing the current value
     */
    public ReadOnlyObjectProperty<V> valueProperty();

    
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
/**
     * Indicates the exception which occurred while the Worker was running, if any.
     * If this property value is {@code null}, there is no known exception, even if
     * the status is FAILED. If this property is not {@code null}, it will most
     * likely contain an exception that describes the cause of failure.
     *
     * @return the exception, if one occurred
     */
    public Throwable getException();

    
Gets the ReadOnlyObjectProperty representing any exception which occurred.

Returns:the property representing the exception
/**
     * Gets the ReadOnlyObjectProperty representing any exception which occurred.
     *
     * @return the property representing the exception
     */
    public ReadOnlyObjectProperty<Throwable> exceptionProperty();

    
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.

See Also:
Returns:the amount of work done
/**
     * 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.
     *
     * @see #totalWorkProperty
     * @see #progressProperty
     * @return the amount of work done
     */
    public double getWorkDone();

    
Gets the ReadOnlyDoubleProperty representing the current progress.

Returns:The property representing the amount of work done
/**
     * Gets the ReadOnlyDoubleProperty representing the current progress.
     *
     * @return The property representing the amount of work done
     */
    public ReadOnlyDoubleProperty workDoneProperty();

    
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. 
See Also:
Returns:the total work to be done
/**
     * Indicates a maximum value for the {@link #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.
     *
     * @see #workDoneProperty
     * @see #progressProperty
     * @return the total work to be done
     */
    public double getTotalWork();

    
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
/**
     * 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.
     *
     * @return the property representing the total work to be done
     */
    public ReadOnlyDoubleProperty totalWorkProperty();

    
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.

See Also:
Returns:the current progress
/**
     * 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.
     *
     * @see #workDoneProperty
     * @see #totalWorkProperty
     * @return the current progress
     */
    public double getProgress();

    
Gets the ReadOnlyDoubleProperty representing the progress.

Returns:the property representing the progress
/**
     * Gets the ReadOnlyDoubleProperty representing the progress.
     *
     * @return the property representing the progress
     */
    public ReadOnlyDoubleProperty progressProperty();

    
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
/**
     * True if the state is either SCHEDULED or RUNNING. When binding a Worker to a
     * {@link 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.
     *
     * @return true if this Worker is running
     */
    public boolean isRunning();

    
Gets the ReadOnlyBooleanProperty representing whether the Worker is running.

Returns:the property representing whether the worker is running
/**
     * Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
     *
     * @return the property representing whether the worker is running
     */
    public ReadOnlyBooleanProperty runningProperty();

    
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
/**
     * Gets a message associated with the current state of this Worker. This may
     * be something such as "Processing image 1 of 3", for example.
     *
     * @return the current message
     */
    public String getMessage();

    
Gets the ReadOnlyStringProperty representing the message.

Returns:a property representing the current message
/**
     * Gets the ReadOnlyStringProperty representing the message.
     *
     * @return a property representing the current message
     */
    public ReadOnlyStringProperty messageProperty();

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

Returns:the current title
/**
     * An optional title that should be associated with this Worker.
     * This may be something such as "Modifying Images".
     *
     * @return the current title
     */
    public String getTitle();

    
Gets the ReadOnlyStringProperty representing the title.

Returns:the property representing the current title
/**
     * Gets the ReadOnlyStringProperty representing the title.
     *
     * @return the property representing the current title
     */
    public ReadOnlyStringProperty titleProperty();

    
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
/**
     * Terminates execution of this Worker. Calling this method will either
     * remove this Worker from the execution queue or stop execution.
     *
     * @return returns true if the cancel was successful
     */
    public boolean cancel();
}