Class WaitForAsyncUtils

java.lang.Object
org.testfx.util.WaitForAsyncUtils
public final class WaitForAsyncUtils extends Object
Provides static methods for handling execution on different threads. The "Test Thread" is usually running on the main thread, while the GUI runs on the "FX Application Thread". Additionally, tasks may also be started on different asynchronous threads.

General Convention (Method Names)

  • async methods without a suffix refer to some unknown thread in a thread pool.
  • Methods ending with the suffix Fx refer to the "FX application thread".

Exception Handling

As exceptions on different threads are thrown the caller is usually not aware of these exceptions. Exceptions returned directly from this framework are wrapped in RuntimeExceptions.

There are two ways this class notifies the user of exceptions:

  • The returned Future.
  • The internal exception stack.

Usually exceptions are forwarded to the Future returned by the methods of this class. When the calling thread calls Future.get() on the Future any exceptions encountered during execution will be thrown. All waitFor methods acquire the value of the Future and accordingly throw the same exceptions.

The internal exception stack stores all unhandled exceptions thrown during direct calls to the async methods. As this class can not guarantee that exceptions in these methods are handled properly, it will internally store these exceptions. The exceptions will be in the stack, until they are handled somewhere in the application. If the field autoCheckException is set to true, any subsequent calls to one of the async methods will throw one of those exceptions.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static boolean
    autoCheckException
    If true any call to an async method will check for the occurrence of unhandled exceptions.
    static boolean
    checkAllExceptions
    If true any call to an async method will check for the occurrence of unhandled exceptions in any Thread.
    static boolean
    printException
    If true any exceptions encountered during execution of the async methods will be printed to stderr.

  • Constructor Summary

    Constructors
    Constructor
    Description
    WaitForAsyncUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static Future<Void>
    async(Runnable runnable)
    Runs the given Runnable on a new Thread and returns a Future that is set on finish or error.
    static Future<Void>
    async(Runnable runnable, boolean throwExceptions)
    Runs the given Runnable on a new Thread and returns a Future that is set on finish or error.
    static <T> Future<T>
    async(Callable<T> callable)
    Calls the given Callable on a new Thread and returns a Future that is set on finish or error.
    static <T> Future<T>
    async(Callable<T> callable, boolean throwExceptions)
    Calls the given Callable on a new Thread and returns a Future that is set on finish or error.
    static Future<Void>
    asyncFx(Runnable runnable)
    Runs the given Runnable on the JavaFX Application Thread at some unspecified time in the future and returns a Future that is set on finish or error.
    static <T> Future<T>
    asyncFx(Callable<T> callable)
    Calls the given Callable on the JavaFX Application Thread at some unspecified time in the future and returns a Future that is set on finish or error.
    static void
    checkException()
    Checks if an exception in an async task occurred that has not been checked currently.
    static void
    clearExceptions()
    Clears all unhandled exceptions.
    static void
    sleep(long duration, TimeUnit timeUnit)
    Sleeps the current thread for the given duration.
    static void
    waitFor(long timeout, TimeUnit timeUnit, Callable<Boolean> condition)
    Waits for given Callable to return true otherwise times out with a TimeoutException.
    static <T> T
    waitFor(long timeout, TimeUnit timeUnit, Future<T> future)
    Waits for given Future to be set and returns T, otherwise times out with a TimeoutException.
    static void
    waitFor(long timeout, TimeUnit timeUnit, javafx.beans.value.ObservableBooleanValue booleanValue)
    Waits for given ObservableBooleanValue to return true otherwise times out with a TimeoutException.
    static <T> T
    waitFor(Future<T> future)
    Waits for the given Future to be set and then returns the future result of type T.
    static void
    waitForAsync(long millis, Runnable runnable)
    Runs the given Runnable on a new Thread and waits millis milliseconds for it to finish, otherwise times out with a TimeoutException.
    static <T> T
    waitForAsync(long millis, Callable<T> callable)
    Calls the given Callable on a new Thread and waits millis milliseconds for it to finish.
    static void
    waitForAsyncFx(long millis, Runnable runnable)
    Runs the given Runnable on the JavaFX Application Thread at some unspecified time in the future and waits millis milliseconds for it to finish, otherwise times out with a TimeoutException.
    static <T> T
    waitForAsyncFx(long millis, Callable<T> callable)
    Calls the given Callable on the JavaFX Application Thread at some unspecified time in the future and waits millis milliseconds for it to finish.
    static void
    waitForFxEvents()
    Waits for the event queue of the "JavaFX Application Thread" to be completed, as well as any new events triggered in it.
    static void
    waitForFxEvents(int attemptsCount)
    Waits up to attemptsCount attempts for the event queue of the "JavaFX Application Thread" to be completed, as well as any new events triggered on it.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • printException

      public static boolean printException
      If true any exceptions encountered during execution of the async methods will be printed to stderr. The exceptions will be printed at the time they occur (not when fetched).

    • autoCheckException

      public static boolean autoCheckException
      If true any call to an async method will check for the occurrence of unhandled exceptions.

    • checkAllExceptions

      public static boolean checkAllExceptions
      If true any call to an async method will check for the occurrence of unhandled exceptions in any Thread.

  • Constructor Details

    • WaitForAsyncUtils

      public WaitForAsyncUtils()

  • Method Details

    • async

      public static Future<Void> async(Runnable runnable)
      Runs the given Runnable on a new Thread and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Parameters:
      runnable - the Runnable to run
      Returns:
      the Future result of the Runnable

    • async

      public static Future<Void> async(Runnable runnable, boolean throwExceptions)
      Runs the given Runnable on a new Thread and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Parameters:
      runnable - the Runnable to run
      throwExceptions - whether or not to throw exceptions on the executing thread
      Returns:
      the Future result of the runnable

    • async

      public static <T> Future<T> async(Callable<T> callable)
      Calls the given Callable on a new Thread and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Type Parameters:
      T - the return type of the Callable
      Parameters:
      callable - the Callable to run
      Returns:
      the Future result of the Callable

    • async

      public static <T> Future<T> async(Callable<T> callable, boolean throwExceptions)
      Calls the given Callable on a new Thread and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Type Parameters:
      T - the return type of the Callable
      Parameters:
      callable - the Callable to run
      throwExceptions - whether or not to throw exceptions on the executing thread
      Returns:
      the Future result of the Callable

    • asyncFx

      public static Future<Void> asyncFx(Runnable runnable)
      Runs the given Runnable on the JavaFX Application Thread at some unspecified time in the future and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Parameters:
      runnable - the Runnable to run
      Returns:
      the Future result of the Runnable

    • asyncFx

      public static <T> Future<T> asyncFx(Callable<T> callable)
      Calls the given Callable on the JavaFX Application Thread at some unspecified time in the future and returns a Future that is set on finish or error.

      You need to evaluate the returned Future via (Future.get()) for exceptions or call the checkException() method to handle exceptions after the task has finished.

      Type Parameters:
      T - the Callable type
      Parameters:
      callable - the Callable
      Returns:
      the Future result of the Callable

    • waitFor

      public static <T> T waitFor(Future<T> future)
      Waits for the given Future to be set and then returns the future result of type T.
      Type Parameters:
      T - the type of the Future
      Parameters:
      future - the Future to wait for to be set
      Returns:
      the result of the Future

    • waitFor

      public static <T> T waitFor(long timeout, TimeUnit timeUnit, Future<T> future) throws TimeoutException
      Waits for given Future to be set and returns T, otherwise times out with a TimeoutException.
      Type Parameters:
      T - the type of the Future
      Parameters:
      timeout - the timeout to wait for
      timeUnit - the time unit timeout is in
      future - the Future to wait for to be set
      Returns:
      the result of the Future
      Throws:
      TimeoutException - if the wait timed out

    • waitFor

      public static void waitFor(long timeout, TimeUnit timeUnit, Callable<Boolean> condition) throws TimeoutException
      Waits for given Callable to return true otherwise times out with a TimeoutException. The condition will be evaluated at least once. This method will wait for the last condition to finish after a timeout.
      Parameters:
      timeout - the timeout to wait for
      timeUnit - the time unit timeout is in
      condition - the condition to wait for to be true
      Throws:
      TimeoutException - if the wait timed out

    • waitFor

      public static void waitFor(long timeout, TimeUnit timeUnit, javafx.beans.value.ObservableBooleanValue booleanValue) throws TimeoutException
      Waits for given ObservableBooleanValue to return true otherwise times out with a TimeoutException.
      Parameters:
      timeout - the timeout to wait for
      timeUnit - the time unit timeout is in
      booleanValue - the observable
      Throws:
      TimeoutException - if the wait timed out

    • waitForFxEvents

      public static void waitForFxEvents()
      Waits for the event queue of the "JavaFX Application Thread" to be completed, as well as any new events triggered in it.

    • waitForFxEvents

      public static void waitForFxEvents(int attemptsCount)
      Waits up to attemptsCount attempts for the event queue of the "JavaFX Application Thread" to be completed, as well as any new events triggered on it.
      Parameters:
      attemptsCount - the number of attempts to try

    • sleep

      public static void sleep(long duration, TimeUnit timeUnit)
      Sleeps the current thread for the given duration.
      Parameters:
      duration - the duration to sleep
      timeUnit - the time unit duration is in

    • waitForAsync

      public static void waitForAsync(long millis, Runnable runnable)
      Runs the given Runnable on a new Thread and waits millis milliseconds for it to finish, otherwise times out with a TimeoutException.
      Parameters:
      millis - number of milliseconds to wait
      runnable - the Runnable to run

    • waitForAsync

      public static <T> T waitForAsync(long millis, Callable<T> callable)
      Calls the given Callable on a new Thread and waits millis milliseconds for it to finish. If finished, returns the future result of type T, otherwise times out with a TimeoutException.
      Type Parameters:
      T - the type returned by the Callable
      Parameters:
      millis - number of milliseconds to wait
      callable - the Callable to call
      Returns:
      the result returned by the Callable

    • waitForAsyncFx

      public static void waitForAsyncFx(long millis, Runnable runnable)
      Runs the given Runnable on the JavaFX Application Thread at some unspecified time in the future and waits millis milliseconds for it to finish, otherwise times out with a TimeoutException.
      Parameters:
      millis - number of milliseconds to wait
      runnable - the Runnable to run

    • waitForAsyncFx

      public static <T> T waitForAsyncFx(long millis, Callable<T> callable)
      Calls the given Callable on the JavaFX Application Thread at some unspecified time in the future and waits millis milliseconds for it to finish. If finished, returns T otherwise times out with a TimeoutException.
      Type Parameters:
      T - the type returned by the Callable
      Parameters:
      millis - number of milliseconds to wait
      callable - the Callable to call
      Returns:
      the result returned by the Callable

    • checkException

      public static void checkException() throws Throwable
      Checks if an exception in an async task occurred that has not been checked currently. If so, the first exception will be removed and thrown by this method.
      Throws:
      Throwable - if an exception has occurred in an async task

    • clearExceptions

      public static void clearExceptions()
      Clears all unhandled exceptions.