1 /*
   2  * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javafx.concurrent;
  27 
  28 import javafx.application.Platform;
  29 import javafx.beans.property.BooleanProperty;
  30 import javafx.beans.property.DoubleProperty;
  31 import javafx.beans.property.ObjectProperty;
  32 import javafx.beans.property.ReadOnlyBooleanProperty;
  33 import javafx.beans.property.ReadOnlyDoubleProperty;
  34 import javafx.beans.property.ReadOnlyObjectProperty;
  35 import javafx.beans.property.ReadOnlyStringProperty;
  36 import javafx.beans.property.SimpleBooleanProperty;
  37 import javafx.beans.property.SimpleDoubleProperty;
  38 import javafx.beans.property.SimpleObjectProperty;
  39 import javafx.beans.property.SimpleStringProperty;
  40 import javafx.beans.property.StringProperty;
  41 import javafx.event.Event;
  42 import javafx.event.EventDispatchChain;
  43 import javafx.event.EventHandler;
  44 import javafx.event.EventTarget;
  45 import javafx.event.EventType;
  46 import java.util.concurrent.Callable;
  47 import java.util.concurrent.FutureTask;
  48 import java.util.concurrent.atomic.AtomicReference;
  49 import static javafx.concurrent.WorkerStateEvent.WORKER_STATE_CANCELLED;
  50 import static javafx.concurrent.WorkerStateEvent.WORKER_STATE_FAILED;
  51 import static javafx.concurrent.WorkerStateEvent.WORKER_STATE_RUNNING;
  52 import static javafx.concurrent.WorkerStateEvent.WORKER_STATE_SCHEDULED;
  53 import static javafx.concurrent.WorkerStateEvent.WORKER_STATE_SUCCEEDED;
  54 
  55 /**
  56  * <p>
  57  *     A fully observable implementation of a {@link FutureTask}. Tasks exposes
  58  *     additional state and observable properties useful for programming asynchronous
  59  *     tasks in JavaFX, as defined in the {@link Worker} interface. An implementation
  60  *     of Task must override the {@link javafx.concurrent.Task#call()} method. This method
  61  *     is invoked on the background thread. Any state which is used in this method
  62  *     must be safe to read and write from a background thread. For example, manipulating
  63  *     a live scene graph from this method is unsafe and will result in runtime
  64  *     exceptions.
  65  * </p>
  66  * <p>
  67  *     Tasks are flexible and extremely useful for the encapsulation of "work". Because
  68  *     {@link Service} is designed to execute a Task, any Tasks defined by the application
  69  *     or library code can easily be used with a Service. Likewise, since Task extends
  70  *     from FutureTask, it is very easy and natural to use a Task with the java concurrency
  71  *     {@link java.util.concurrent.Executor} API. Since a Task is Runnable, you
  72  *     can also call it directly (by invoking the {@link javafx.concurrent.Task#run()} method)
  73  *     from another background thread. This allows for composition of work, or pass it to
  74  *     a new Thread constructed and executed manually. Finally, since you can
  75  *     manually create a new Thread, passing it a Runnable, it is possible to use
  76  *     the following idiom:
  77  *     <pre><code>
  78  *         Thread th = new Thread(task);
  79  *         th.setDaemon(true);
  80  *         th.start();
  81  *     </code></pre>
  82  *     Note that this code sets the daemon flag of the Thread to true. If you
  83  *     want a background thread to prevent the VM from existing after the last
  84  *     stage is closed, then you would want daemon to be false. However, if
  85  *     you want the background threads to simply terminate after all the
  86  *     stages are closed, then you must set daemon to true.
  87  * </p>
  88  * <p>
  89  *     Although {@link java.util.concurrent.ExecutorService} defines several methods which
  90  *     take a Runnable, you should generally limit yourself to using the <code>execute</code>
  91  *     method inherited from {@link java.util.concurrent.Executor}.
  92  * </p>
  93  * <p>
  94  *     As with FutureTask, a Task is a one-shot class and cannot be reused. See {@link Service}
  95  *     for a reusable {@link Worker}.
  96  * </p>
  97  * <p>
  98  *     Because the Task is designed for use with JavaFX GUI applications, it ensures
  99  *     that every change to its public properties, as well as change notifications
 100  *     for state, errors, and for event handlers, all occur on the main JavaFX application
 101  *     thread. Accessing these properties from a background thread (including the
 102  *     {@link #call()} method) will result in runtime exceptions being raised. The only exception
 103  *     to this, is when initially configuring a Task, which may safely be done
 104  *     from any thread. However, once the Task has been initialized and
 105  *     started, it may only thereafter be used from the FX thread (except for those methods clearly
 106  *     marked as being appropriate for the subclass to invoke from the background thread).
 107  * </p>
 108  * <p>
 109  *     It is <strong>strongly encouraged</strong> that all Tasks be initialized with
 110  *     immutable state upon which the Task will operate. This should be done by providing
 111  *     a Task constructor which takes the parameters necessary for execution of the Task.
 112  *     Immutable state makes it easy and safe to use from any thread and ensures
 113  *     correctness in the presence of multiple threads.
 114  * </p>
 115  * <p>
 116  *     In Java there is no reliable way to "kill" a thread in process. However,
 117  *     when <code>cancel</code> is called on a Task, it is important that
 118  *     the Task stop processing. A "run-away" Task might continue processing
 119  *     and updating the message, text, and progress properties even after the
 120  *     Task has been cancelled! In Java, cancelling a Task is a cooperative
 121  *     endeavor. The user of the Task will request that it be cancelled, and
 122  *     the author of the Task must check whether is has been cancelled within
 123  *     the body of the <code>call</code> method. There are two ways this can
 124  *     be done. First, the Task author may check the isCancelled method,
 125  *     inherited from <code>FutureTask</code>, to see whether the Task has
 126  *     been cancelled. Second, if the Task implementation makes use of any
 127  *     blocking calls (such as NIO InterruptibleChannels or Thread.sleep) and
 128  *     the task is cancelled while in such a blocking call, an
 129  *     InterruptedException is thrown. Task implementations which have blocking
 130  *     calls should recognize that an interrupted thread may be the signal for
 131  *     a cancelled task and should double check the isCancelled method to ensure
 132  *     that the InterruptedException was thrown due to the cancellation of the
 133  *     Task.
 134  * </p>
 135  * <h2>Examples</h2>
 136  * <p>
 137  *     The following set of examples demonstrate some of the most common uses of
 138  *     Tasks.
 139  * </p>
 140  *
 141  * <h3>A Simple Loop</h3>
 142  *
 143  * <p>
 144  *     The first example is a simple loop that does nothing particularly useful,
 145  *     but demonstrates the fundamental aspects of writing a Task correctly. This
 146  *     example will simply loop and print to standard out on each loop iteration.
 147  *     When it completes, it returns the number of times it iterated.
 148  * </p>
 149  *
 150  * <pre><code>
 151  *     Task&lt;Integer&gt; task = new Task&lt;Integer&gt;() {
 152  *         &#64;Override protected Integer call() throws Exception {
 153  *             int iterations;
 154  *             for (iterations = 0; iterations &lt; 100000; iterations++) {
 155  *                 if (isCancelled()) {
 156  *                     break;
 157  *                 }
 158  *                 System.out.println("Iteration " + iterations);
 159  *             }
 160  *             return iterations;
 161  *         }
 162  *     };
 163  * </code></pre>
 164  *
 165  * <p>
 166  *     First, we define what type of value is returned from this Task. In this
 167  *     case, we want to return the number of times we iterated, so we will
 168  *     specify the Task to be of type Integer by using generics. Then, within
 169  *     the implementation of the <code>call</code> method, we iterate from
 170  *     0 to 100000. On each iteration, we check to see whether this Task has
 171  *     been cancelled. If it has been, then we break out of the loop and return
 172  *     the number of times we iterated. Otherwise a message is printed to
 173  *     the console and the iteration count increased and we continue looping.
 174  * </p>
 175  *
 176  * <p>
 177  *     Checking for isCancelled() in the loop body is critical, otherwise the
 178  *     developer may cancel the task, but the task will continue running
 179  *     and updating both the progress and returning the incorrect result
 180  *     from the end of the <code>call</code> method. A correct implementation
 181  *     of a Task will always check for cancellation.
 182  * </p>
 183  *
 184  * <h3>A Simple Loop With Progress Notification</h3>
 185  *
 186  * <p>
 187  *     Similar to the previous example, except this time we will modify the
 188  *     progress of the Task in each iteration. Note that we have a choice
 189  *     to make in the case of cancellation. Do we want to set the progress back
 190  *     to -1 (indeterminate) when the Task is cancelled, or do we want to leave
 191  *     the progress where it was at? In this case, lets leave the progress alone
 192  *     and only update the message on cancellation, though updating the
 193  *     progress after cancellation is a perfectly valid choice.
 194  * </p>
 195  *
 196  * <pre><code>
 197  *     Task&lt;Integer&gt; task = new Task&lt;Integer&gt;() {
 198  *         &#64;Override protected Integer call() throws Exception {
 199  *             int iterations;
 200  *             for (iterations = 0; iterations &lt; 10000000; iterations++) {
 201  *                 if (isCancelled()) {
 202  *                     updateMessage("Cancelled");
 203  *                     break;
 204  *                 }
 205  *                 updateMessage("Iteration " + iterations);
 206  *                 updateProgress(iterations, 10000000);
 207  *             }
 208  *             return iterations;
 209  *         }
 210  *     };
 211  * </code></pre>
 212  *
 213  * <p>
 214  *     As before, within the for loop we check whether the Task has been
 215  *     cancelled. If it has been cancelled, we will update the Task's
 216  *     message to indicate that it has been cancelled, and then break as
 217  *     before. If the Task has not been cancelled, then we will update its
 218  *     message to indicate the current iteration and then update the
 219  *     progress to indicate the current progress.
 220  * </p>
 221  *
 222  * <h3>A Simple Loop With Progress Notification And Blocking Calls</h3>
 223  *
 224  * <p>
 225  *     This example adds to the previous examples a blocking call. Because a
 226  *     blocking call may thrown an InterruptedException, and because an
 227  *     InterruptedException may occur as a result of the Task being cancelled,
 228  *     we need to be sure to handle the InterruptedException and check on the
 229  *     cancel state.
 230  * </p>
 231  *
 232  * <pre><code>
 233  *     Task&lt;Integer&gt; task = new Task&lt;Integer&gt;() {
 234  *         &#64;Override protected Integer call() throws Exception {
 235  *             int iterations;
 236  *             for (iterations = 0; iterations &lt; 1000; iterations++) {
 237  *                 if (isCancelled()) {
 238  *                     updateMessage("Cancelled");
 239  *                     break;
 240  *                 }
 241  *                 updateMessage("Iteration " + iterations);
 242  *                 updateProgress(iterations, 1000);
 243  *
 244  *                 // Now block the thread for a short time, but be sure
 245  *                 // to check the interrupted exception for cancellation!
 246  *                 try {
 247  *                     Thread.sleep(100);
 248  *                 } catch (InterruptedException interrupted) {
 249  *                     if (isCancelled()) {
 250  *                         updateMessage("Cancelled");
 251  *                         break;
 252  *                     }
 253  *                 }
 254  *             }
 255  *             return iterations;
 256  *         }
 257  *     };
 258  * </code></pre>
 259  *
 260  * <p>
 261  *     Here we have added to the body of the loop a <code>Thread.sleep</code>
 262  *     call. Since this is a blocking call, I have to handle the potential
 263  *     InterruptedException. Within the catch block, I will check whether
 264  *     the Task has been cancelled, and if so, update the message accordingly
 265  *     and break out of the loop.
 266  * </p>
 267  *
 268  * <h3>A Task Which Takes Parameters</h3>
 269  *
 270  * <p>
 271  *     Most Tasks require some parameters in order to do useful work. For
 272  *     example, a DeleteRecordTask needs the object or primary key to delete
 273  *     from the database. A ReadFileTask needs the URI of the file to be read.
 274  *     Because Tasks operate on a background thread, care must be taken to
 275  *     make sure the body of the <code>call</code> method does not read or
 276  *     modify any shared state. There are two techniques most useful for
 277  *     doing this: using final variables, and passing variables to a Task
 278  *     during construction.
 279  * </p>
 280  *
 281  * <p>
 282  *     When using a Task as an anonymous class, the most natural way to pass
 283  *     parameters to the Task is by using final variables. In this example,
 284  *     we pass to the Task the total number of times the Task should iterate.
 285  * </p>
 286  *
 287  * <pre><code>
 288  *     final int totalIterations = 9000000;
 289  *     Task&lt;Integer&gt; task = new Task&lt;Integer&gt;() {
 290  *         &#64;Override protected Integer call() throws Exception {
 291  *             int iterations;
 292  *             for (iterations = 0; iterations &lt; totalIterations; iterations++) {
 293  *                 if (isCancelled()) {
 294  *                     updateMessage("Cancelled");
 295  *                     break;
 296  *                 }
 297  *                 updateMessage("Iteration " + iterations);
 298  *                 updateProgress(iterations, totalIterations);
 299  *             }
 300  *             return iterations;
 301  *         }
 302  *     };
 303  * </code></pre>
 304  *
 305  * <p>
 306  *     Since <code>totalIterations</code> is final, the <code>call</code>
 307  *     method can safely read it and refer to it from a background thread.
 308  * </p>
 309  *
 310  * <p>
 311  *     When writing Task libraries (as opposed to specific-use implementations),
 312  *     we need to use a different technique. In this case, I will create an
 313  *     IteratingTask which performs the same work as above. This time, since
 314  *     the IteratingTask is defined in its own file, it will need to have
 315  *     parameters passed to it in its constructor. These parameters are
 316  *     assigned to final variables.
 317  * </p>
 318  *
 319  * <pre><code>
 320  *     public class IteratingTask extends Task&lt;Integer&gt; {
 321  *         private final int totalIterations;
 322  *
 323  *         public IteratingTask(int totalIterations) {
 324  *             this.totalIterations = totalIterations;
 325  *         }
 326  *
 327  *         &#64;Override protected Integer call() throws Exception {
 328  *             int iterations = 0;
 329  *             for (iterations = 0; iterations &lt; totalIterations; iterations++) {
 330  *                 if (isCancelled()) {
 331  *                     updateMessage("Cancelled");
 332  *                     break;
 333  *                 }
 334  *                 updateMessage("Iteration " + iterations);
 335  *                 updateProgress(iterations, totalIterations);
 336  *             }
 337  *             return iterations;
 338  *         }
 339  *     }
 340  * </code></pre>
 341  *
 342  * <p>And then when used:</p>
 343  *
 344  * <pre><code>
 345  *     IteratingTask task = new IteratingTask(8000000);
 346  * </code></pre>
 347  *
 348  * <p>In this way, parameters are passed to the IteratingTask in a safe
 349  * manner, and again, are final. Thus, the <code>call</code> method can
 350  * safely read this state from a background thread.</p>
 351  *
 352  * <p>WARNING: Do not pass mutable state to a Task and then operate on it
 353  * from a background thread. Doing so may introduce race conditions. In
 354  * particular, suppose you had a SaveCustomerTask which took a Customer
 355  * in its constructor. Although the SaveCustomerTask may have a final
 356  * reference to the Customer, if the Customer object is mutable, then it
 357  * is possible that both the SaveCustomerTask and some other application code
 358  * will be reading or modifying the state of the Customer from different
 359  * threads. Be very careful in such cases, that while a mutable object such
 360  * as this Customer is being used from a background thread, that it is
 361  * not being used also from another thread. In particular, if the background
 362  * thread is reading data from the database and updating the Customer object,
 363  * and the Customer object is bound to scene graph nodes (such as UI
 364  * controls), then there could be a violation of threading rules! For such
 365  * cases, modify the Customer object from the FX Application Thread rather
 366  * than from the background thread.</p>
 367  *
 368  * <pre><code>
 369  *     public class UpdateCustomerTask extends Task&lt;Customer&gt; {
 370  *         private final Customer customer;
 371  *
 372  *         public UpdateCustomerTask(Customer customer) {
 373  *             this.customer = customer;
 374  *         }
 375  *
 376  *         &#64;Override protected Customer call() throws Exception {
 377  *             // pseudo-code:
 378  *             //   query the database
 379  *             //   read the values
 380  *
 381  *             // Now update the customer
 382  *             Platform.runLater(new Runnable() {
 383  *                 &#64;Override public void run() {
 384  *                     customer.setF setFirstName(rs.getString("FirstName"));
 385  *                     // etc
 386  *                 }
 387  *             });
 388  *
 389  *             return customer;
 390  *         }
 391  *     }
 392  * </code></pre>
 393  *
 394  * <h3>A Task Which Returns No Value</h3>
 395  *
 396  * <p>
 397  *     Many, if not most, Tasks should return a value upon completion. For
 398  *     CRUD Tasks, one would expect that a "Create" Task would return the newly
 399  *     created object or primary key, a "Read" Task would return the read
 400  *     object, an "Update" task would return the number of records updated,
 401  *     and a "Delete" task would return the number of records deleted.
 402  * </p>
 403  *
 404  * <p>
 405  *     However sometimes there just isn't anything truly useful to return.
 406  *     For example, I might have a Task which writes to a file. Task has built
 407  *     into it a mechanism for indicating whether it has succeeded or failed
 408  *     along with the number of bytes written (the progress), and thus there is
 409  *     nothing really for me to return. In such a case, you can use the Void
 410  *     type. This is a special type in the Java language which can only be
 411  *     assigned the value of <code>null</code>. You would use it as follows:
 412  * </p>
 413  *
 414  * <pre><code>
 415  *     final String filePath = "/foo.txt";
 416  *     final String contents = "Some contents";
 417  *     Task&lt;Void&gt; task = new Task&lt;Void&gt;() {
 418  *         &#64;Override protected Void call() throws Exception {
 419  *             File file = new File(filePath);
 420  *             FileOutputStream out = new FileOutputStream(file);
 421  *             // ... and other code to write the contents ...
 422  *
 423  *             // Return null at the end of a Task of type Void
 424  *             return null;
 425  *         }
 426  *     };
 427  * </code></pre>
 428  *
 429  * <h3>A Task Which Returns An ObservableList</h3>
 430  *
 431  * <p>Because the ListView, TableView, and other UI controls and scene graph
 432  * nodes make use of ObservableList, it is common to want to create and return
 433  * an ObservableList from a Task. When you do not care to display intermediate
 434  * values, the easiest way to correctly write such a Task is simply to
 435  * construct an ObservableList within the <code>call</code> method, and then
 436  * return it at the conclusion of the Task.</p>
 437  *
 438  * <pre><code>
 439  *     Task&lt;ObservableList&lt;Rectangle&gt;&gt; task = new Task&lt;ObservableList&lt;Rectangle&gt;&gt;() {
 440  *         &#64;Override protected ObservableList&lt;Rectangle&gt; call() throws Exception {
 441  *             updateMessage("Creating Rectangles");
 442  *             ObservableList&lt;Rectangle&gt; results = FXCollections.observableArrayList();
 443  *             for (int i=0; i<100; i++) {
 444  *                 if (isCancelled()) break;
 445  *                 Rectangle r = new Rectangle(10, 10);
 446  *                 r.setX(10 * i);
 447  *                 results.add(r);
 448  *                 updateProgress(i, 100);
 449  *             }
 450  *             return results;
 451  *         }
 452  *     };
 453  * </code></pre>
 454  *
 455  * <p>In the above example, we are going to create 100 rectangles and return
 456  * them from this task. An ObservableList is created within the
 457  * <code>call</code> method, populated, and then returned.</p>
 458  *
 459  * <h3>A Task Which Returns Partial Results</h3>
 460  *
 461  * <p>Sometimes you want to create a Task which will return partial results.
 462  * Perhaps you are building a complex scene graph and want to show the
 463  * scene graph as it is being constructed. Or perhaps you are reading a large
 464  * amount of data over the network and want to display the entries in a
 465  * TableView as the data is arriving. In such cases, there is some shared state
 466  * available both to the FX Application Thread and the background thread.
 467  * Great care must be taken to <strong>never update shared state from any
 468  * thread other than the FX Application Thread</strong>.</p>
 469  *
 470  * <p>The easiest way to do this is to take advantage of the {@link #updateValue(Object)} method.
 471  * This method may be called repeatedly from the background thread. Updates are coalesced to
 472  * prevent saturation of the FX event queue. This means you can call it as frequently as
 473  * you like from the background thread but only the most recent set is ultimately set.</p>
 474  *
 475  * <pre><code>
 476  *     Task&lt;Long&gt; task = new Task&lt;Long&gt;() {
 477  *         &#64;Override protected Long call() throws Exception {
 478  *             long a=0;
 479  *             long b=1;
 480  *             for (long i = 0; i &lt; Long.MAX_VALUE; i++){
 481  *                 updateValue(a);
 482  *                 a += b;
 483  *                 b = a - b;
 484  *             }
 485  *             return a;
 486  *         }
 487  *     };
 488  * </code></pre>
 489  *
 490  * <p>Another way to do this is to expose a new property on the Task
 491  * which will represent the partial result. Then make sure to use
 492  * <code>Platform.runLater</code> when updating the partial result.</p>
 493  *
 494  * <pre><code>
 495  *     Task&lt;Long&gt; task = new Task&lt;Long&gt;() {
 496  *         &#64;Override protected Long call() throws Exception {
 497  *             long a=0;
 498  *             long b=1;
 499  *             for (long i = 0; i &lt; Long.MAX_VALUE; i++){
 500  *                 final long v = a;
 501  *                 Platform.runLater(new Runnable() {
 502  *                     &#64;Override public void run() {
 503  *                         updateValue(v);
 504  *                     }
 505  *                 }
 506  *                 a += b;
 507  *                 b = a - b;
 508  *             }
 509  *             return a;
 510  *         }
 511  *     };
 512  * </code></pre>
 513  *
 514  * <p>Suppose instead of updating a single value, you want to populate an ObservableList
 515  * with results as they are obtained. One approach is to expose a new property on the Task
 516  * which will represent the partial result. Then make sure to use
 517  * <code>Platform.runLater</code> when adding new items to the partial
 518  * result.</p>
 519  *
 520  * <pre><code>
 521  *     public class PartialResultsTask extends Task&lt;ObservableList&lt;Rectangle&gt;&gt; {
 522  *         // Uses Java 7 diamond operator
 523  *         private ReadOnlyObjectWrapper<ObservableList<Rectangle>> partialResults =
 524  *                 new ReadOnlyObjectWrapper<>(this, "partialResults",
 525  *                         FXCollections.observableArrayList(new ArrayList<Rectangle>()));
 526  *
 527  *         public final ObservableList<Rectangle> getPartialResults() { return partialResults.get(); }
 528  *         public final ReadOnlyObjectProperty<ObservableList<Rectangle>> partialResultsProperty() {
 529  *             return partialResults.getReadOnlyProperty();
 530  *         }
 531  *
 532  *         &#64;Override protected ObservableList<Rectangle> call() throws Exception {
 533  *             updateMessage("Creating Rectangles...");
 534  *             for (int i=0; i<100; i++) {
 535  *                 if (isCancelled()) break;
 536  *                 final Rectangle r = new Rectangle(10, 10);
 537  *                 r.setX(10 * i);
 538  *                 Platform.runLater(new Runnable() {
 539  *                     &#64;Override public void run() {
 540  *                         partialResults.get().add(r);
 541  *                     }
 542  *                 });
 543  *                 updateProgress(i, 100);
 544  *             }
 545  *             return partialResults.get();
 546  *         }
 547  *     }
 548  * </code></pre>
 549  *
 550  * <h3>A Task Which Modifies The Scene Graph</h3>
 551  *
 552  * <p>Generally, Tasks should not interact directly with the UI. Doing so
 553  * creates a tight coupling between a specific Task implementation and a
 554  * specific part of your UI. However, when you do want to create such a
 555  * coupling, you must ensure that you use <code>Platform.runLater</code>
 556  * so that any modifications of the scene graph occur on the
 557  * FX Application Thread.</p>
 558  *
 559  * <pre><code>
 560  *     final Group group = new Group();
 561  *     Task&lt;Void&gt; task = new Task&lt;Void&gt;() {
 562  *         &#64;Override protected Void call() throws Exception {
 563  *             for (int i=0; i<100; i++) {
 564  *                 if (isCancelled()) break;
 565  *                 final Rectangle r = new Rectangle(10, 10);
 566  *                 r.setX(10 * i);
 567  *                 Platform.runLater(new Runnable() {
 568  *                     &#64;Override public void run() {
 569  *                         group.getChildren().add(r);
 570  *                     }
 571  *                 });
 572  *             }
 573  *             return null;
 574  *         }
 575  *     };
 576  * </code></pre>
 577  *
 578  * <h3>Reacting To State Changes Generically</h3>
 579  *
 580  * <p>Sometimes you may want to write a Task which updates its progress,
 581  * message, text, or in some other way reacts whenever a state change
 582  * happens on the Task. For example, you may want to change the status
 583  * message on the Task on Failure, Success, Running, or Cancelled state changes.
 584  * </p>
 585  * <pre><code>
 586  *     Task&lt;Integer&gt; task = new Task&lt;Integer&gt;() {
 587  *         &#64;Override protected Integer call() throws Exception {
 588  *             int iterations = 0;
 589  *             for (iterations = 0; iterations &lt; 100000; iterations++) {
 590  *                 if (isCancelled()) {
 591  *                     break;
 592  *                 }
 593  *                 System.out.println("Iteration " + iterations);
 594  *             }
 595  *             return iterations;
 596  *         }
 597  *
 598  *         &#64;Override protected void succeeded() {
 599  *             super.succeeded();
 600  *             updateMessage("Done!");
 601  *         }
 602  *
 603  *         &#64;Override protected void cancelled() {
 604  *             super.cancelled();
 605  *             updateMessage("Cancelled!");
 606  *         }
 607  *
 608  *         &#64;Override protected void failed() {
 609  *             super.failed();
 610  *             updateMessage("Failed!");
 611  *         }
 612  *     };
 613  * </code></pre>
 614  * @since JavaFX 2.0
 615  */
 616 public abstract class Task<V> extends FutureTask<V> implements Worker<V>, EventTarget {
 617     /**
 618      * Used to send workDone updates in a thread-safe manner from the subclass
 619      * to the FX application thread and workDone related properties. AtomicReference
 620      * is used so as to coalesce updates such that we don't flood the event queue.
 621      */
 622     private AtomicReference<ProgressUpdate> progressUpdate = new AtomicReference<>();
 623 
 624     /**
 625      * Used to send message updates in a thread-safe manner from the subclass
 626      * to the FX application thread. AtomicReference is used so as to coalesce
 627      * updates such that we don't flood the event queue.
 628      */
 629     private AtomicReference<String> messageUpdate = new AtomicReference<>();
 630 
 631     /**
 632      * Used to send title updates in a thread-safe manner from the subclass
 633      * to the FX application thread. AtomicReference is used so as to coalesce
 634      * updates such that we don't flood the event queue.
 635      */
 636     private AtomicReference<String> titleUpdate = new AtomicReference<>();
 637 
 638     /**
 639      * Used to send value updates in a thread-safe manner from the subclass
 640      * to the FX application thread. AtomicReference is used so as to coalesce
 641      * updates such that we don't flood the event queue.
 642      */
 643     private AtomicReference<V> valueUpdate = new AtomicReference<>();
 644 
 645     /**
 646      * This is used so we have a thread-safe way to ask whether the task was
 647      * started in the checkThread() method.
 648      */
 649     private volatile boolean started = false;
 650 
 651     /**
 652      * Creates a new Task.
 653      */
 654     public Task() {
 655         this(new TaskCallable<V>());
 656     }
 657 
 658     /**
 659      * This bit of construction trickery is necessary because otherwise there is
 660      * no way for the main constructor to both create the callable and maintain
 661      * a reference to it, which is necessary because an anonymous callable construction
 662      * cannot reference the implicit "this". We leverage an internal Callable
 663      * so that all the pre-built semantics around cancel and so forth are
 664      * handled correctly.
 665      *
 666      * @param callableAdapter non-null implementation of the
 667      *                        TaskCallable adapter
 668      */
 669     private Task(final TaskCallable<V> callableAdapter) {
 670         super(callableAdapter);
 671         callableAdapter.task = this;
 672     }
 673 
 674     /**
 675      * Invoked when the Task is executed, the call method must be overridden and
 676      * implemented by subclasses. The call method actually performs the
 677      * background thread logic. Only the updateProgress, updateMessage, updateValue and
 678      * updateTitle methods of Task may be called from code within this method.
 679      * Any other interaction with the Task from the background thread will result
 680      * in runtime exceptions.
 681      *
 682      * @return The result of the background work, if any.
 683      * @throws Exception an unhandled exception which occurred during the
 684      *         background operation
 685      */
 686     protected abstract V call() throws Exception;
 687 
 688     private ObjectProperty<State> state = new SimpleObjectProperty<>(this, "state", State.READY);
 689     final void setState(State value) { // package access for the Service
 690         checkThread();
 691         final State s = getState();
 692         if (s != State.CANCELLED) {
 693             this.state.set(value);
 694             // Make sure the running flag is set
 695             setRunning(value == State.SCHEDULED || value == State.RUNNING);
 696 
 697             // Invoke the event handlers, and then call the protected methods.
 698             switch (state.get()) {
 699                 case CANCELLED:
 700                     fireEvent(new WorkerStateEvent(this, WORKER_STATE_CANCELLED));
 701                     cancelled();
 702                     break;
 703                 case FAILED:
 704                     fireEvent(new WorkerStateEvent(this, WORKER_STATE_FAILED));
 705                     failed();
 706                     break;
 707                 case READY:
 708                     // This even can never meaningfully occur, because the
 709                     // Task begins life as ready and can never go back to it!
 710                     break;
 711                 case RUNNING:
 712                     fireEvent(new WorkerStateEvent(this, WORKER_STATE_RUNNING));
 713                     running();
 714                     break;
 715                 case SCHEDULED:
 716                     fireEvent(new WorkerStateEvent(this, WORKER_STATE_SCHEDULED));
 717                     scheduled();
 718                     break;
 719                 case SUCCEEDED:
 720                     fireEvent(new WorkerStateEvent(this, WORKER_STATE_SUCCEEDED));
 721                     succeeded();
 722                     break;
 723                 default: throw new AssertionError("Should be unreachable");
 724             }
 725         }
 726     }
 727     @Override public final State getState() { checkThread(); return state.get(); }
 728     @Override public final ReadOnlyObjectProperty<State> stateProperty() { checkThread(); return state; }
 729 
 730     /**
 731      * The onSchedule event handler is called whenever the Task state
 732      * transitions to the SCHEDULED state.
 733      *
 734      * @return the onScheduled event handler property
 735      * @since JavaFX 2.1
 736      */
 737     public final ObjectProperty<EventHandler<WorkerStateEvent>> onScheduledProperty() {
 738         checkThread();
 739         return getEventHelper().onScheduledProperty();
 740     }
 741 
 742     /**
 743      * The onSchedule event handler is called whenever the Task state
 744      * transitions to the SCHEDULED state.
 745      *
 746      * @return the onScheduled event handler, if any
 747      * @since JavaFX 2.1
 748      */
 749     public final EventHandler<WorkerStateEvent> getOnScheduled() {
 750         checkThread();
 751         return eventHelper == null ? null : eventHelper.getOnScheduled();
 752     }
 753 
 754     /**
 755      * The onSchedule event handler is called whenever the Task state
 756      * transitions to the SCHEDULED state.
 757      *
 758      * @param value the event handler, can be null to clear it
 759      * @since JavaFX 2.1
 760      */
 761     public final void setOnScheduled(EventHandler<WorkerStateEvent> value) {
 762         checkThread();
 763         getEventHelper().setOnScheduled(value);
 764     }
 765 
 766     /**
 767      * A protected convenience method for subclasses, called whenever the
 768      * state of the Task has transitioned to the SCHEDULED state.
 769      * This method is invoked on the FX Application Thread after the Task has been fully transitioned to
 770      * the new state.
 771      * @since JavaFX 2.1
 772      */
 773     protected void scheduled() { }
 774 
 775     /**
 776      * The onRunning event handler is called whenever the Task state
 777      * transitions to the RUNNING state.
 778      *
 779      * @return the onRunning event handler property
 780      * @since JavaFX 2.1
 781      */
 782     public final ObjectProperty<EventHandler<WorkerStateEvent>> onRunningProperty() {
 783         checkThread();
 784         return getEventHelper().onRunningProperty();
 785     }
 786 
 787     /**
 788      * The onRunning event handler is called whenever the Task state
 789      * transitions to the RUNNING state.
 790      *
 791      * @return the onRunning event handler, if any
 792      * @since JavaFX 2.1
 793      */
 794     public final EventHandler<WorkerStateEvent> getOnRunning() {
 795         checkThread();
 796         return eventHelper == null ? null : eventHelper.getOnRunning();
 797     }
 798 
 799     /**
 800      * The onRunning event handler is called whenever the Task state
 801      * transitions to the RUNNING state.
 802      *
 803      * @param value the event handler, can be null to clear it
 804      * @since JavaFX 2.1
 805      */
 806     public final void setOnRunning(EventHandler<WorkerStateEvent> value) {
 807         checkThread();
 808         getEventHelper().setOnRunning(value);
 809     }
 810 
 811     /**
 812      * A protected convenience method for subclasses, called whenever the
 813      * state of the Task has transitioned to the RUNNING state.
 814      * This method is invoked on the FX Application Thread after the Task has been fully transitioned to
 815      * the new state.
 816      * @since JavaFX 2.1
 817      */
 818     protected void running() { }
 819 
 820     /**
 821      * The onSucceeded event handler is called whenever the Task state
 822      * transitions to the SUCCEEDED state.
 823      *
 824      * @return the onSucceeded event handler property
 825      * @since JavaFX 2.1
 826      */
 827     public final ObjectProperty<EventHandler<WorkerStateEvent>> onSucceededProperty() {
 828         checkThread();
 829         return getEventHelper().onSucceededProperty();
 830     }
 831 
 832     /**
 833      * The onSucceeded event handler is called whenever the Task state
 834      * transitions to the SUCCEEDED state.
 835      *
 836      * @return the onSucceeded event handler, if any
 837      * @since JavaFX 2.1
 838      */
 839     public final EventHandler<WorkerStateEvent> getOnSucceeded() {
 840         checkThread();
 841         return eventHelper == null ? null : eventHelper.getOnSucceeded();
 842     }
 843 
 844     /**
 845      * The onSucceeded event handler is called whenever the Task state
 846      * transitions to the SUCCEEDED state.
 847      *
 848      * @param value the event handler, can be null to clear it
 849      * @since JavaFX 2.1
 850      */
 851     public final void setOnSucceeded(EventHandler<WorkerStateEvent> value) {
 852         checkThread();
 853         getEventHelper().setOnSucceeded(value);
 854     }
 855 
 856     /**
 857      * A protected convenience method for subclasses, called whenever the
 858      * state of the Task has transitioned to the SUCCEEDED state.
 859      * This method is invoked on the FX Application Thread after the Task has been fully transitioned to
 860      * the new state.
 861      * @since JavaFX 2.1
 862      */
 863     protected void succeeded() { }
 864 
 865     /**
 866      * The onCancelled event handler is called whenever the Task state
 867      * transitions to the CANCELLED state.
 868      *
 869      * @return the onCancelled event handler property
 870      * @since JavaFX 2.1
 871      */
 872     public final ObjectProperty<EventHandler<WorkerStateEvent>> onCancelledProperty() {
 873         checkThread();
 874         return getEventHelper().onCancelledProperty();
 875     }
 876 
 877     /**
 878      * The onCancelled event handler is called whenever the Task state
 879      * transitions to the CANCELLED state.
 880      *
 881      * @return the onCancelled event handler, if any
 882      * @since JavaFX 2.1
 883      */
 884     public final EventHandler<WorkerStateEvent> getOnCancelled() {
 885         checkThread();
 886         return eventHelper == null ? null : eventHelper.getOnCancelled();
 887     }
 888 
 889     /**
 890      * The onCancelled event handler is called whenever the Task state
 891      * transitions to the CANCELLED state.
 892      *
 893      * @param value the event handler, can be null to clear it
 894      * @since JavaFX 2.1
 895      */
 896     public final void setOnCancelled(EventHandler<WorkerStateEvent> value) {
 897         checkThread();
 898         getEventHelper().setOnCancelled(value);
 899     }
 900 
 901     /**
 902      * A protected convenience method for subclasses, called whenever the
 903      * state of the Task has transitioned to the CANCELLED state.
 904      * This method is invoked on the FX Application Thread after the Task has been fully transitioned to
 905      * the new state.
 906      * @since JavaFX 2.1
 907      */
 908     protected void cancelled() { }
 909 
 910     /**
 911      * The onFailed event handler is called whenever the Task state
 912      * transitions to the FAILED state.
 913      *
 914      * @return the onFailed event handler property
 915      * @since JavaFX 2.1
 916      */
 917     public final ObjectProperty<EventHandler<WorkerStateEvent>> onFailedProperty() {
 918         checkThread();
 919         return getEventHelper().onFailedProperty();
 920     }
 921 
 922     /**
 923      * The onFailed event handler is called whenever the Task state
 924      * transitions to the FAILED state.
 925      *
 926      * @return the onFailed event handler, if any
 927      * @since JavaFX 2.1
 928      */
 929     public final EventHandler<WorkerStateEvent> getOnFailed() {
 930         checkThread();
 931         return eventHelper == null ? null : eventHelper.getOnFailed();
 932     }
 933 
 934     /**
 935      * The onFailed event handler is called whenever the Task state
 936      * transitions to the FAILED state.
 937      *
 938      * @param value the event handler, can be null to clear it
 939      * @since JavaFX 2.1
 940      */
 941     public final void setOnFailed(EventHandler<WorkerStateEvent> value) {
 942         checkThread();
 943         getEventHelper().setOnFailed(value);
 944     }
 945 
 946     /**
 947      * A protected convenience method for subclasses, called whenever the
 948      * state of the Task has transitioned to the FAILED state.
 949      * This method is invoked on the FX Application Thread after the Task has been fully transitioned to
 950      * the new state.
 951      * @since JavaFX 2.1
 952      */
 953     protected void failed() { }
 954 
 955     private final ObjectProperty<V> value = new SimpleObjectProperty<>(this, "value");
 956     private void setValue(V v) { checkThread(); value.set(v); }
 957     @Override public final V getValue() { checkThread(); return value.get(); }
 958     @Override public final ReadOnlyObjectProperty<V> valueProperty() { checkThread(); return value; }
 959 
 960     private final ObjectProperty<Throwable> exception = new SimpleObjectProperty<>(this, "exception");
 961     private void _setException(Throwable value) { checkThread(); exception.set(value); }
 962     @Override public final Throwable getException() { checkThread(); return exception.get(); }
 963     @Override public final ReadOnlyObjectProperty<Throwable> exceptionProperty() { checkThread(); return exception; }
 964 
 965     private final DoubleProperty workDone = new SimpleDoubleProperty(this, "workDone", -1);
 966     private void setWorkDone(double value) { checkThread(); workDone.set(value); }
 967     @Override public final double getWorkDone() { checkThread(); return workDone.get(); }
 968     @Override public final ReadOnlyDoubleProperty workDoneProperty() { checkThread(); return workDone; }
 969 
 970     private final DoubleProperty totalWork = new SimpleDoubleProperty(this, "totalWork", -1);
 971     private void setTotalWork(double value) { checkThread(); totalWork.set(value); }
 972     @Override public final double getTotalWork() { checkThread(); return totalWork.get(); }
 973     @Override public final ReadOnlyDoubleProperty totalWorkProperty() { checkThread(); return totalWork; }
 974 
 975     private final DoubleProperty progress = new SimpleDoubleProperty(this, "progress", -1);
 976     private void setProgress(double value) { checkThread(); progress.set(value); }
 977     @Override public final double getProgress() { checkThread(); return progress.get(); }
 978     @Override public final ReadOnlyDoubleProperty progressProperty() { checkThread(); return progress; }
 979 
 980     private final BooleanProperty running = new SimpleBooleanProperty(this, "running", false);
 981     private void setRunning(boolean value) { checkThread(); running.set(value); }
 982     @Override public final boolean isRunning() { checkThread(); return running.get(); }
 983     @Override public final ReadOnlyBooleanProperty runningProperty() { checkThread(); return running; }
 984 
 985     private final StringProperty message = new SimpleStringProperty(this, "message", "");
 986     @Override public final String getMessage() { checkThread(); return message.get(); }
 987     @Override public final ReadOnlyStringProperty messageProperty() { checkThread(); return message; }
 988 
 989     private final StringProperty title = new SimpleStringProperty(this, "title", "");
 990     @Override public final String getTitle() { checkThread(); return title.get(); }
 991     @Override public final ReadOnlyStringProperty titleProperty() { checkThread(); return title; }
 992 
 993     @Override public final boolean cancel() {
 994         return cancel(true);
 995     }
 996 
 997     @Override public boolean cancel(boolean mayInterruptIfRunning) {
 998         // Delegate to the super implementation to actually attempt to cancel this thing
 999         boolean flag = super.cancel(mayInterruptIfRunning);
1000         // If cancel succeeded (according to the semantics of the Future cancel method),
1001         // then we need to make sure the State flag is set appropriately
1002         if (flag) {
1003             // If this method was called on the FX application thread, then we can
1004             // just update the state directly and this will make sure that after
1005             // the cancel method was called, the state will be set correctly
1006             // (otherwise it would be indeterminate). However if the cancel method was
1007             // called off the FX app thread, then we must use runLater, and the
1008             // state flag will not be readable immediately after this call. However,
1009             // that would be the case anyway since these properties are not thread-safe.
1010             if (isFxApplicationThread()) {
1011                 setState(State.CANCELLED);
1012             } else {
1013                 runLater(() -> setState(State.CANCELLED));
1014             }
1015         }
1016         // return the flag
1017         return flag;
1018     }
1019 
1020     /**
1021      * Updates the <code>workDone</code>, <code>totalWork</code>,
1022      * and <code>progress</code> properties. Calls to updateProgress
1023      * are coalesced and run later on the FX application thread, and calls
1024      * to updateProgress, even from the FX Application thread, may not
1025      * necessarily result in immediate updates to these properties, and
1026      * intermediate workDone values may be coalesced to save on event
1027      * notifications. <code>max</code> becomes the new value for
1028      * <code>totalWork</code>.
1029      * <p>
1030      *     <em>This method is safe to be called from any thread.</em>
1031      * </p>
1032      *
1033      * @param workDone A value from Long.MIN_VALUE up to max. If the value is greater
1034      *                 than max, then it will be clamped at max.
1035      *                 If the value passed is negative then the resulting percent
1036      *                 done will be -1 (thus, indeterminate).
1037      * @param max A value from Long.MIN_VALUE to Long.MAX_VALUE.
1038      * @see #updateProgress(double, double)
1039      */
1040     protected void updateProgress(long workDone, long max) {
1041         updateProgress((double)workDone, (double)max);
1042     }
1043 
1044     /**
1045      * Updates the <code>workDone</code>, <code>totalWork</code>,
1046      * and <code>progress</code> properties. Calls to updateProgress
1047      * are coalesced and run later on the FX application thread, and calls
1048      * to updateProgress, even from the FX Application thread, may not
1049      * necessarily result in immediate updates to these properties, and
1050      * intermediate workDone values may be coalesced to save on event
1051      * notifications. <code>max</code> becomes the new value for
1052      * <code>totalWork</code>.
1053      * <p>
1054      *     <em>This method is safe to be called from any thread.</em>
1055      * </p>
1056      *
1057      * @param workDone A value from Double.MIN_VALUE up to max. If the value is greater
1058      *                 than max, then it will be clamped at max.
1059      *                 If the value passed is negative, or Infinity, or NaN,
1060      *                 then the resulting percentDone will be -1 (thus, indeterminate).
1061      * @param max A value from Double.MIN_VALUE to Double.MAX_VALUE. Infinity and NaN are treated as -1.
1062      * @since JavaFX 2.2
1063      */
1064     protected void updateProgress(double workDone, double max) {
1065         // Adjust Infinity / NaN to be -1 for both workDone and max.
1066         if (Double.isInfinite(workDone) || Double.isNaN(workDone)) {
1067             workDone = -1;
1068         }
1069 
1070         if (Double.isInfinite(max) || Double.isNaN(max)) {
1071             max = -1;
1072         }
1073 
1074         if (workDone < 0) {
1075             workDone = -1;
1076         }
1077 
1078         if (max < 0) {
1079             max = -1;
1080         }
1081 
1082         // Clamp the workDone if necessary so as not to exceed max
1083         if (workDone > max) {
1084             workDone = max;
1085         }
1086 
1087         if (isFxApplicationThread()) {
1088             _updateProgress(workDone, max);
1089         } else if (progressUpdate.getAndSet(new ProgressUpdate(workDone, max)) == null) {
1090             runLater(() -> {
1091                 final ProgressUpdate update = progressUpdate.getAndSet(null);
1092                 _updateProgress(update.workDone, update.totalWork);
1093             });
1094         }
1095     }
1096 
1097     private void _updateProgress(double workDone, double max) {
1098         setTotalWork(max);
1099         setWorkDone(workDone);
1100         if (workDone == -1) {
1101             setProgress(-1);
1102         } else {
1103             setProgress(workDone / max);
1104         }
1105     }
1106 
1107     /**
1108      * Updates the <code>message</code> property. Calls to updateMessage
1109      * are coalesced and run later on the FX application thread, so calls
1110      * to updateMessage, even from the FX Application thread, may not
1111      * necessarily result in immediate updates to this property, and
1112      * intermediate message values may be coalesced to save on event
1113      * notifications.
1114      * <p>
1115      *     <em>This method is safe to be called from any thread.</em>
1116      * </p>
1117      *
1118      * @param message the new message
1119      */
1120     protected void updateMessage(String message) {
1121         if (isFxApplicationThread()) {
1122             this.message.set(message);
1123         } else {
1124             // As with the workDone, it might be that the background thread
1125             // will update this message quite frequently, and we need
1126             // to throttle the updates so as not to completely clobber
1127             // the event dispatching system.
1128             if (messageUpdate.getAndSet(message) == null) {
1129                 runLater(new Runnable() {
1130                     @Override public void run() {
1131                         final String message = messageUpdate.getAndSet(null);
1132                         Task.this.message.set(message);
1133                     }
1134                 });
1135             }
1136         }
1137     }
1138 
1139     /**
1140      * Updates the <code>title</code> property. Calls to updateTitle
1141      * are coalesced and run later on the FX application thread, so calls
1142      * to updateTitle, even from the FX Application thread, may not
1143      * necessarily result in immediate updates to this property, and
1144      * intermediate title values may be coalesced to save on event
1145      * notifications.
1146      * <p>
1147      *     <em>This method is safe to be called from any thread.</em>
1148      * </p>
1149      *
1150      * @param title the new title
1151      */
1152     protected void updateTitle(String title) {
1153         if (isFxApplicationThread()) {
1154             this.title.set(title);
1155         } else {
1156             // As with the workDone, it might be that the background thread
1157             // will update this title quite frequently, and we need
1158             // to throttle the updates so as not to completely clobber
1159             // the event dispatching system.
1160             if (titleUpdate.getAndSet(title) == null) {
1161                 runLater(new Runnable() {
1162                     @Override public void run() {
1163                         final String title = titleUpdate.getAndSet(null);
1164                         Task.this.title.set(title);
1165                     }
1166                 });
1167             }
1168         }
1169     }
1170 
1171     /**
1172      * Updates the <code>value</code> property. Calls to updateValue
1173      * are coalesced and run later on the FX application thread, so calls
1174      * to updateValue, even from the FX Application thread, may not
1175      * necessarily result in immediate updates to this property, and
1176      * intermediate values may be coalesced to save on event
1177      * notifications.
1178      * <p>
1179      *     <em>This method is safe to be called from any thread.</em>
1180      * </p>
1181      *
1182      * @param value the new value
1183      * @since JavaFX 8.0
1184      */
1185     protected void updateValue(V value) {
1186         if (isFxApplicationThread()) {
1187             this.value.set(value);
1188         } else {
1189             // As with the workDone, it might be that the background thread
1190             // will update this value quite frequently, and we need
1191             // to throttle the updates so as not to completely clobber
1192             // the event dispatching system.
1193             if (valueUpdate.getAndSet(value) == null) {
1194                 runLater(() -> Task.this.value.set(valueUpdate.getAndSet(null)));
1195             }
1196         }
1197     }
1198 
1199     /*
1200      * IMPLEMENTATION
1201      */
1202     private void checkThread() {
1203         if (started && !isFxApplicationThread()) {
1204             throw new IllegalStateException("Task must only be used from the FX Application Thread");
1205         }
1206     }
1207 
1208     // This method exists for the sake of testing, so I can subclass and override
1209     // this method in the test and not actually use Platform.runLater.
1210     void runLater(Runnable r) {
1211         Platform.runLater(r);
1212     }
1213 
1214     // This method exists for the sake of testing, so I can subclass and override
1215     // this method in the test and not actually use Platform.isFxApplicationThread.
1216     boolean isFxApplicationThread() {
1217         return Platform.isFxApplicationThread();
1218     }
1219 
1220     /***************************************************************************
1221      *                                                                         *
1222      *                         Event Dispatch                                  *
1223      *                                                                         *
1224      **************************************************************************/
1225 
1226     private EventHelper eventHelper = null;
1227     private EventHelper getEventHelper() {
1228         if (eventHelper == null) {
1229             eventHelper = new EventHelper(this);
1230         }
1231         return eventHelper;
1232     }
1233 
1234     /**
1235      * Registers an event handler to this task. Any event filters are first
1236      * processed, then the specified onFoo event handlers, and finally any
1237      * event handlers registered by this method. As with other events
1238      * in the scene graph, if an event is consumed, it will not continue
1239      * dispatching.
1240      *
1241      * @param <T> the specific event class of the handler
1242      * @param eventType the type of the events to receive by the handler
1243      * @param eventHandler the handler to register
1244      * @throws NullPointerException if the event type or handler is null
1245      * @since JavaFX 2.1
1246      */
1247     public final <T extends Event> void addEventHandler(
1248             final EventType<T> eventType,
1249             final EventHandler<? super T> eventHandler) {
1250         checkThread();
1251         getEventHelper().addEventHandler(eventType, eventHandler);
1252     }
1253 
1254     /**
1255      * Unregisters a previously registered event handler from this task. One
1256      * handler might have been registered for different event types, so the
1257      * caller needs to specify the particular event type from which to
1258      * unregister the handler.
1259      *
1260      * @param <T> the specific event class of the handler
1261      * @param eventType the event type from which to unregister
1262      * @param eventHandler the handler to unregister
1263      * @throws NullPointerException if the event type or handler is null
1264      * @since JavaFX 2.1
1265      */
1266     public final <T extends Event> void removeEventHandler(
1267             final EventType<T> eventType,
1268             final EventHandler<? super T> eventHandler) {
1269         checkThread();
1270         getEventHelper().removeEventHandler(eventType, eventHandler);
1271     }
1272 
1273     /**
1274      * Registers an event filter to this task. Registered event filters get
1275      * an event before any associated event handlers.
1276      *
1277      * @param <T> the specific event class of the filter
1278      * @param eventType the type of the events to receive by the filter
1279      * @param eventFilter the filter to register
1280      * @throws NullPointerException if the event type or filter is null
1281      * @since JavaFX 2.1
1282      */
1283     public final <T extends Event> void addEventFilter(
1284             final EventType<T> eventType,
1285             final EventHandler<? super T> eventFilter) {
1286         checkThread();
1287         getEventHelper().addEventFilter(eventType, eventFilter);
1288     }
1289 
1290     /**
1291      * Unregisters a previously registered event filter from this task. One
1292      * filter might have been registered for different event types, so the
1293      * caller needs to specify the particular event type from which to
1294      * unregister the filter.
1295      *
1296      * @param <T> the specific event class of the filter
1297      * @param eventType the event type from which to unregister
1298      * @param eventFilter the filter to unregister
1299      * @throws NullPointerException if the event type or filter is null
1300      * @since JavaFX 2.1
1301      */
1302     public final <T extends Event> void removeEventFilter(
1303             final EventType<T> eventType,
1304             final EventHandler<? super T> eventFilter) {
1305         checkThread();
1306         getEventHelper().removeEventFilter(eventType, eventFilter);
1307     }
1308 
1309     /**
1310      * Sets the handler to use for this event type. There can only be one such
1311      * handler specified at a time. This handler is guaranteed to be called
1312      * first. This is used for registering the user-defined onFoo event
1313      * handlers.
1314      *
1315      * @param <T> the specific event class of the handler
1316      * @param eventType the event type to associate with the given eventHandler
1317      * @param eventHandler the handler to register, or null to unregister
1318      * @throws NullPointerException if the event type is null
1319      * @since JavaFX 2.1
1320      */
1321     protected final <T extends Event> void setEventHandler(
1322             final EventType<T> eventType,
1323             final EventHandler<? super T> eventHandler) {
1324         checkThread();
1325         getEventHelper().setEventHandler(eventType, eventHandler);
1326     }
1327 
1328     /**
1329      * Fires the specified event. Any event filter encountered will
1330      * be notified and can consume the event. If not consumed by the filters,
1331      * the event handlers on this task are notified. If these don't consume the
1332      * event either, then all event handlers are called and can consume the
1333      * event.
1334      * <p>
1335      * This method must be called on the FX user thread.
1336      *
1337      * @param event the event to fire
1338      * @since JavaFX 2.1
1339      */
1340     public final void fireEvent(Event event) {
1341         checkThread();
1342         getEventHelper().fireEvent(event);
1343     }
1344 
1345     @Override
1346     public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
1347         checkThread();
1348         return getEventHelper().buildEventDispatchChain(tail);
1349     }
1350 
1351     /**
1352      * A struct like class that contains the last workDone update information.
1353      * What we do when updateProgress is called, is we create a new ProgressUpdate
1354      * object and store it. If it was null, then we fire off a new Runnable
1355      * using RunLater, which will eventually read the latest and set it to null
1356      * atomically. If it was not null, then we simply update it.
1357      */
1358     private static final class ProgressUpdate {
1359         private final double workDone;
1360         private final double totalWork;
1361 
1362         private ProgressUpdate(double p, double m) {
1363             this.workDone = p;
1364             this.totalWork = m;
1365         }
1366     }
1367 
1368     /**
1369      *  TaskCallable actually implements the Callable contract as defined for
1370      *  the FutureTask class, and is necessary so as to allow us to intercept
1371      *  the call() operation to update state on the Task as appropriate.
1372      * @param <V>
1373      */
1374     private static final class TaskCallable<V> implements Callable<V> {
1375         /**
1376          * The Task that is going to use this TaskCallable
1377          */
1378         private Task<V> task;
1379 
1380         /**
1381          * Create a TaskCallable. The concurrent and other fields MUST be set
1382          * immediately after creation.
1383          */
1384         private TaskCallable() { }
1385 
1386         /**
1387          * Invoked by the system when it is time to run the client code. This
1388          * implementation is where we modify the state and other properties
1389          * and from which we invoke the events.
1390          *
1391          * @return The result of the Task call method
1392          * @throws Exception any exception which occurred
1393          */
1394         @Override public V call() throws Exception {
1395             // If the Task is sent to an ExecutorService for execution, then we
1396             // will need to make sure that we transition first to the SCHEDULED
1397             // state before then transitioning to the RUNNING state. If the
1398             // Task was executed by a Service, then it will have already been
1399             // in the SCHEDULED state and setting it again here has no negative
1400             // effect. But we must ensure that SCHEDULED is visited before RUNNING
1401             // in all cases so that developer code can be consistent.
1402             task.started = true;
1403             task.runLater(() -> {
1404                 task.setState(State.SCHEDULED);
1405                 task.setState(State.RUNNING);
1406             });
1407             // Go ahead and delegate to the wrapped callable
1408             try {
1409                 final V result = task.call();
1410                 if (!task.isCancelled()) {
1411                     // If it was not cancelled, then we take the return
1412                     // value and set it as the result.
1413                     task.runLater(() -> {
1414                         // The result must be set first, so that when the
1415                         // SUCCEEDED flag is set, the value will be available
1416                         // The alternative is not the case, because you
1417                         // can assume if the result is set, it has
1418                         // succeeded.
1419                         task.updateValue(result);
1420                         task.setState(State.SUCCEEDED);
1421                     });
1422                     return result;
1423                 } else {
1424                     // Since cancelled Future/FutureTask doesn't return any value,
1425                     // the returned value is going to be trashed, so we can jus return null
1426                     return null;
1427                 }
1428             } catch (final Throwable th) {
1429                 // Be sure to set the state after setting the cause of failure
1430                 // so that developers handling the state change events have a
1431                 // throwable to inspect when they get the FAILED state. Note
1432                 // that the other way around is not important -- when a developer
1433                 // observes the causeOfFailure is set to a non-null value, even
1434                 // though the state has not yet been updated, he can infer that
1435                 // it will be FAILED because it can be nothing other than FAILED
1436                 // in that circumstance.
1437                 task.runLater(() -> {
1438                     task._setException(th);
1439                     task.setState(State.FAILED);
1440                 });
1441                 // Some error occurred during the call (it might be
1442                 // an exception (either runtime or checked), or it might
1443                 // be an error. In any case, we capture the throwable,
1444                 // record it as the causeOfFailure, and then rethrow. However
1445                 // since the Callable interface requires that we throw an
1446                 // Exception (not Throwable), we have to wrap the exception
1447                 // if it is not already one.
1448                 if (th instanceof Exception) {
1449                     throw (Exception) th;
1450                 } else {
1451                     throw new Exception(th);
1452                 }
1453             }
1454         }
1455     }
1456 }