Summary

Add a check to the Animation and AnimationTimer public methods to verify that these are called from the JavaFX Application thread, and update JavaDoc accordingly.

Problem

Currently the Animation (play(), pause(), and stop()) and AnimationTimer (play(), stop()) public methods don't perform any check to verify if they are called from the JavaFX Application thread.

However, all animations run on the FX Application Thread, and if the call is done from a different thread, unexpected errors appear (typically NPEs like the ones in JDK-8159048) without a clear explanation that allows the developer preventing those.

Solution

Add a check to the Animation and AnimationTimer public methods to verify that these are called from the JavaFX Application thread, and if the call is done from any other thread, throw an IllegalStateException with "Not on FX application thread" message.

Update the javadoc of the Animation and AnimationTimer classes and public methods to indicate that these run on the JavaFX Application Thread, and that these will throw and IllegalStateException if called from any other thread.

Specification

The following is added to the Animation and AnimationTimer javadoc:

/* ...
 * The animation runs on the JavaFX Application Thread.
 * ...
 */
public abstract class Animation {...}

/* ...
 * The animation timer runs on the JavaFX Application Thread.
 * ...
 */
public abstract class AnimationTimer {...}

The following is added to the public methods of Animation (play(), pause(), and stop()) and AnimationTimer (play(), stop()):

 /* ...
 * 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,...
 */
public void play() {
    Toolkit.getToolkit().checkFxUserThread();
     ...
}

 /* ...
 * 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,...
 */
public void pause() {
    Toolkit.getToolkit().checkFxUserThread();
     ...
}

 /* ...
 * 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,...
 */
public void stop() {
    Toolkit.getToolkit().checkFxUserThread();
     ...
}