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