Spec-Zone .ru
спецификации, руководства, описания, API
001/*
002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.concurrent;
027
028import javafx.beans.property.ReadOnlyBooleanProperty;
029import javafx.beans.property.ReadOnlyDoubleProperty;
030import javafx.beans.property.ReadOnlyObjectProperty;
031import javafx.beans.property.ReadOnlyStringProperty;
032
033/**
034 * <p>
035 *     A Worker is an object which performs some work in one or more background
036 *     threads, and who's state is observable and available to JavaFX applications
037 *     and is usable from the main JavaFX Application thread. This interface is
038 *     primarily implemented by both {@link Task} and {@link Service}, providing
039 *     a common API among both classes which makes it easier for libraries and
040 *     frameworks to provide workers which work well when developing user interfaces.
041 * </p>
042 * <p>
043 *     A Worker may or may not be reusable depending on the implementation. A
044 *     {@link Task}, for example, is not reusable while a {@link Service} is.
045 * </p>
046 * <p>
047 *     A Worker has a well defined life cycle. Every Worker begins in the
048 *     {@link State#READY} state. When the Worker has been scheduled for work
049 *     (for example, when a Service's {@link javafx.concurrent.Service#start()}
050 *     method is called), it is transitioned to {@link State#SCHEDULED}. Even
051 *     Workers which are not technically scheduled, but started immediately
052 *     (such as with {@link javafx.concurrent.Task#run()}) will transition through
053 *     the {@link State#SCHEDULED} on its way to the {@link State#RUNNING} state.
054 * </p>
055 * <p>
056 *     When the Worker is actually performing its work, the state will have been
057 *     transitioned to {@link State#RUNNING}. If the Worker completes normally,
058 *     it will end in the {@link State#SUCCEEDED} state, and the result of the
059 *     Worker will be set as the <code>value</code> property. If however an Exception
060 *     occurs during the execution of the Worker, then the state will be set to
061 *     {@link State#FAILED} and the <code>exception</code> property will be set
062 *     to the Exception which occurred.
063 * </p>
064 * <p>
065 *     At any time prior to the conclusion of the Worker (that is, if the state
066 *     is not already {@link State#SUCCEEDED} or {@link State#FAILED}) the developer
067 *     may invoke the {@link javafx.concurrent.Worker#cancel()} method. If called, the
068 *     Worker will cease execution (if possible, including use of Thread.interrupt)
069 *     and the state changed to {@link State#CANCELLED}.
070 * </p>
071 * <p>
072 *     The only valid beginning state for a Worker is {@link State#READY}, and the
073 *     valid ending states are {@link State#CANCELLED}, {@link State#SUCCEEDED},
074 *     and {@link State#FAILED}. The <code>running</code> property is set to
075 *     true when the state is either {@link State#SCHEDULED} or {@link State#RUNNING}.
076 * </p>
077 * <p>
078 *     The Worker's progress can be monitored via three different properties,
079 *     <code>totalWork</code>, <code>workDone</code>, and <code>progress</code>.
080 *     These properties are set by the actual implementation of the Worker
081 *     interface, but can be observed by anybody. The <code>workDone</code> is
082 *     a number between -1 (meaning indeterminate progress) and
083 *     <code>totalWork</code>, inclusive. When <code>workDone == totalWork</code>
084 *     the <code>progress</code> will be 100% (or 1). <code>totalWork</code>
085 *     will be a number between -1 and Long.MAX_VALUE, inclusive. The progress
086 *     will be either -1 (meaning indeterminate), or a value between 0 and 1, inclusive,
087 *     representing 0% through 100%.
088 * </p>
089 * <p>
090 *     A Worker which is in the {@link State#READY} or {@link State#SCHEDULED} states
091 *     will always have <code>workDone</code> and <code>progress</code> set to -1.
092 *     A Worker which is in the {@link State#SUCCEEDED} state will always have
093 *     <code>workDone == totalWork</code> and <code>progress == 1</code>. In any
094 *     other state, the values for these properties may be any value in their
095 *     respective valid ranges.
096 * </p>
097 */
098public interface Worker<V> {
099    /**
100     * <p>
101     *     The state of a Worker. The state transitions in a Worker are very well defined.
102     *     All Workers begin in the READY state. In some circumstances, a Worker might
103     *     be scheduled for execution before it is actually executed. In such cases,
104     *     it is sometimes useful to know when the Worker has been SCHEDULED separately
105     *     from when it is RUNNING. However even in cases where the Worker is executed
106     *     immediately, the Worker will temporarily enter the SCHEDULED state before
107     *     entering the RUNNING state. That is, the transition is always from
108     *     READY to SCHEDULED to RUNNING (unless of course the Worker in cancelled).
109     * </p>
110     * <p>
111     *     A Worker which runs but is never cancelled can only end up in one of two
112     *     states, either SUCCEEDED or FAILED. It only enters FAILED if an exception
113     *     was thrown during the execution of the Worker. A Worker may be cancelled when
114     *     READY, SCHEDULED, or RUNNING, in which case the final status will be CANCELLED.
115     *     When a Worker is cancelled in one of these circumstances it will transition
116     *     immediately to the CANCELLED state.
117     * </p>
118     * <p>
119     *     A reusable Worker will transition from CANCELLED, SUCCEEDED or FAILED back to
120     *     READY. From that point the normal state transitions are again followed.
121     * </p>
122     */
123    public enum State {
124        /**
125         * Indicates that the Worker has not yet been executed and is ready
126         * to be executed, or that it has been reinitialized. This is the
127         * default initial state of the Worker.
128         */
129        READY,
130        /**
131         * Indicates that the Worker has been scheduled for execution, but
132         * that it is not currently running. This might be because the
133         * Worker is waiting for a thread in a thread pool to become
134         * available before it can start running.
135         */
136        SCHEDULED,
137        /**
138         * Indicates that this Worker is running. This is set just immediately
139         * prior to the Worker actually doing its first bit of work.
140         */
141        RUNNING,
142        /**
143         * Indicates that this Worker has completed successfully, and that there
144         * is a valid result ready to be read from the <code>value</code> property.
145         */
146        SUCCEEDED,
147        /**
148         * Indicates that this Worker has been cancelled via the {@link #cancel()}
149         * method.
150         */
151        CANCELLED,
152        /**
153         * Indicates that this Worker has failed, usually due to some unexpected
154         * condition having occurred. The exception can be retrieved from the
155         * <code>exception</code> property.
156         */
157        FAILED
158    }
159
160    /**
161     * Specifies the current state of this Worker. The initial value is State.READY.
162     * A Task may be restarted, in which case it will progress from one of these
163     * end states (SUCCEEDED, CANCELLED, or FAILED) back to READY and then
164     * immediately to SCHEDULED and RUNNING. These state transitions may occur
165     * immediately one after the other, but will always occur in the prescribed order.
166     *
167     * @return The current state of this Worker
168     */
169    public State getState();
170
171    /**
172     * Gets the ReadOnlyObjectProperty representing the current state.
173     *
174     * @return The property representing the state
175     */
176    public ReadOnlyObjectProperty<State> stateProperty();
177
178    /**
179     * Specifies the value, or result, of this Worker. This is set upon entering
180     * the SUCCEEDED state, and cleared (set to null) if the Worker is reinitialized
181     * (that is, if the Worker is a reusable Worker and is reset or restarted).
182     *
183     * @return the current value of this Worker
184     */
185    public V getValue();
186
187    /**
188     * Gets the ReadOnlyObjectProperty representing the value.
189     *
190     * @return The property representing the current value
191     */
192    public ReadOnlyObjectProperty<V> valueProperty();
193
194    /**
195     * Indicates the exception which occurred while the Worker was running, if any.
196     * If this property value is {@code null}, there is no known exception, even if
197     * the status is FAILED. If this property is not {@code null}, it will most
198     * likely contain an exception that describes the cause of failure.
199     *
200     * @return the exception, if one occurred
201     */
202    public Throwable getException();
203
204    /**
205     * Gets the ReadOnlyObjectProperty representing any exception which occurred.
206     *
207     * @return the property representing the exception
208     */
209    public ReadOnlyObjectProperty<Throwable> exceptionProperty();
210
211    /**
212     * Indicates the current amount of work that has been completed. Zero or a
213     * positive value indicate progress toward completion. This variables value
214     * may or may not change from its default value depending on the specific
215     * Worker implementation. A value of -1 means that the current amount of work
216     * done cannot be determined (ie: it is indeterminate). The value of
217     * this property is always less than or equal to totalWork.
218     *
219     * @see #totalWorkProperty
220     * @see #progressProperty
221     * @return the amount of work done
222     */
223    public double getWorkDone();
224
225    /**
226     * Gets the ReadOnlyDoubleProperty representing the current progress.
227     *
228     * @return The property representing the amount of work done
229     */
230    public ReadOnlyDoubleProperty workDoneProperty();
231
232    /**
233     * Indicates a maximum value for the {@link #workDoneProperty} property. The
234     * totalWork will either be -1 (indicating that the amount of work
235     * to do is indeterminate), or it will be a non-zero value less than or
236     * equal to Double.MAX_VALUE.
237     *
238     * @see #workDoneProperty
239     * @see #progressProperty
240     * @return the total work to be done
241     */
242    public double getTotalWork();
243
244    /**
245     * Gets the ReadOnlyDoubleProperty representing the maximum amount of work
246     * that needs to be done. These "work units" have meaning to the Worker
247     * implementation, such as the number of bytes that need to be downloaded
248     * or the number of images to process or some other such metric.
249     *
250     * @return the property representing the total work to be done
251     */
252    public ReadOnlyDoubleProperty totalWorkProperty();
253
254    /**
255     * Indicates the current progress of this Worker in terms of percent complete.
256     * A value between zero and one indicates progress toward completion. A value
257     * of -1 means that the current progress cannot be determined (that is, it is
258     * indeterminate). This property may or may not change from its default value
259     * of -1 depending on the specific Worker implementation.
260     *
261     * @see #workDoneProperty
262     * @see #totalWorkProperty
263     * @return the current progress
264     */
265    public double getProgress();
266
267    /**
268     * Gets the ReadOnlyDoubleProperty representing the progress.
269     *
270     * @return the property representing the progress
271     */
272    public ReadOnlyDoubleProperty progressProperty();
273
274    /**
275     * True if the state is either SCHEDULED or RUNNING. When binding a Worker to a
276     * {@link javafx.scene.control.ProgressIndicator}, you will typically bind the visibility
277     * of the ProgressIndicator to the Worker's running property, and the progress of the
278     * ProgressIndicator to the Worker's progress property.
279     *
280     * @return true if this Worker is running
281     */
282    public boolean isRunning();
283
284    /**
285     * Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
286     *
287     * @return the property representing whether the worker is running
288     */
289    public ReadOnlyBooleanProperty runningProperty();
290
291    /**
292     * Gets a message associated with the current state of this Worker. This may
293     * be something such as "Processing image 1 of 3", for example.
294     *
295     * @return the current message
296     */
297    public String getMessage();
298
299    /**
300     * Gets the ReadOnlyStringProperty representing the message.
301     *
302     * @return a property representing the current message
303     */
304    public ReadOnlyStringProperty messageProperty();
305
306    /**
307     * An optional title that should be associated with this Worker.
308     * This may be something such as "Modifying Images".
309     *
310     * @return the current title
311     */
312    public String getTitle();
313
314    /**
315     * Gets the ReadOnlyStringProperty representing the title.
316     *
317     * @return the property representing the current title
318     */
319    public ReadOnlyStringProperty titleProperty();
320
321    /**
322     * Terminates execution of this Worker. Calling this method will either
323     * remove this Worker from the execution queue or stop execution.
324     *
325     * @return returns true if the cancel was successful
326     */
327    public boolean cancel();
328}