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