Package org.testfx.util

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 Details

    • CONDITION_SLEEP_IN_MILLIS

      private static final long CONDITION_SLEEP_IN_MILLIS
      See Also:

    • SEMAPHORE_SLEEP_IN_MILLIS

      private static final long SEMAPHORE_SLEEP_IN_MILLIS
      See Also:

    • SEMAPHORE_LOOPS_COUNT

      private static final int SEMAPHORE_LOOPS_COUNT
      See Also:

    • PAINT_COLLECTOR

      private static final String PAINT_COLLECTOR
      See Also:

    • EXECUTOR_SERVICE

      private static final ExecutorService EXECUTOR_SERVICE

    • EXCEPTIONS

      private static final Queue<Throwable> EXCEPTIONS

    • 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.

    • TRACE_FETCH

      private static final boolean TRACE_FETCH
      If true exceptions will be printed when they are fetched by a caller. Even when they are handled properly. This field is mainly for development debug purposes.
      See Also:

  • Constructor Details

    • WaitForAsyncUtils

      public WaitForAsyncUtils()

  • Method Details

    • setup

      private static void setup()
      Needs to be called to setup WaitForAsyncUtils before the first use. Currently it installs/removes the handler for uncaught exceptions depending on the flag checkAllExceptions.

    • 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.

    • registerException

      private static void registerException(Throwable throwable)
      Used to add an exception on the stack. Used by the global exception handler.
      Parameters:
      throwable - the throwable to add on the local exception buffer.

    • checkExceptionWrapped

      private static void checkExceptionWrapped()
      Internal function that throws Exceptions. It does not require handling of the Exceptions.

    • getCheckException

      private static Throwable getCheckException()
      Pops an exception from the stack and adds an entry in the stack trace to notify the user that this is not the original place of the exception.
      Returns:
      the exception or null if none in stack

    • waitForMillis

      private static <T> T waitForMillis(long millis, Future<T> future)

    • runOnFxThread

      private static void runOnFxThread(Runnable runnable)

    • callConditionAndReturnResult

      private static boolean callConditionAndReturnResult(Callable<Boolean> condition)

    • blockFxThreadWithSemaphore

      private static void blockFxThreadWithSemaphore()

    • printException

      private static void printException(Throwable e, StackTraceElement[] trace)

    • printTrace

      private static String printTrace(StackTraceElement[] st)
      Returns a String containing the printed stacktrace.
      Parameters:
      st - the stacktrace
      Returns:
      a String containing the printed stacktrace

    • chronoUnit

      private static ChronoUnit chronoUnit(TimeUnit unit)