Summary

Invoking Animation control methods (play/start/stop/pause) on a thread other than the JavaFX Application Thread now delegates them to the FX thread so that these methods are always executed on the FX thread.

Problem

Invoking these methods on a thread other than the FX thread could result in unexpected states (and exceptions), as animations are not built for multithreading. JDK-8159048 chose to avoid this by throwing an exception if any of these methods were not invoked on the FX thread. As a result, user code stopped working and it was decided that that approach broke (behavioral) backwards compatibility too much. In this change, the changes made by JDK-8159048 were reverted in favor of a more backwards compatible approach.

Solution

These methods are modified so that they are always run on the FX thread. If they were not invoked from the FX thread, they are internally delegated to it. This solution avoids throwing an exception, thus user code can continue working. This solution still restricts cases where calling these methods from a background thread could work well. It's also possible that this change corrected user code in which these methods were mistakenly called on a background thread, without the user being aware of it. A future change could improve the multithread behavior of animations.

Specification

javafx.graphics/src/main/java/javafx/animation/Animation: Methods public void play(), public void stop(), public void pause(), public void playFrom(String), public void playFrom(Duration), and public void playFromStart() have the following doc change:

-     * Note: <ul>
-     * <li>{@code play()} is an asynchronous call, the {@code Animation} may not
-     * start immediately. </ul>
-     * <p>
-     * This method must be called on the JavaFX Application thread.
+     * Note: if this method is not called on the JavaFX Application Thread, it is delegated to it automatically.
+     * In this case, the call is asynchronous and may not happen immediately.
      *
-     * @throws IllegalStateException if this method is called on a thread
-     *                other than the JavaFX Application Thread, or if embedded in another animation,
+     * @throws IllegalStateException if embedded in another animation,
      *                such as {@link SequentialTransition} or {@link ParallelTransition}
      */

javafx.graphics/src/main/java/javafx/animation/AnimationTimer: Methods public void start(), public void stop() have the following doc change:

-     * This method must be called on the JavaFX Application thread.
-     *
-     * @throws IllegalStateException if this method is called on a thread
-     *                  other than the JavaFX Application Thread.
+     * Note: if this method is not called on the JavaFX Application Thread, it is delegated to it automatically.
+     * In this case, the call is asynchronous and may not happen immediately.
      */