Package org.testfx.util

Class WaitForAsyncUtils

  • public final class WaitForAsyncUtils
extends java.lang.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.
      private static long CONDITION_SLEEP_IN_MILLIS  
      private static java.util.Queue<java.lang.Throwable> EXCEPTIONS  
      private static java.util.concurrent.ExecutorService EXECUTOR_SERVICE  
      private static java.lang.String PAINT_COLLECTOR  
      static boolean printException
      If true any exceptions encountered during execution of the async methods will be printed to stderr.
      private static int SEMAPHORE_LOOPS_COUNT  
      private static long SEMAPHORE_SLEEP_IN_MILLIS  
      private static boolean TRACE_FETCH
      If true exceptions will be printed when they are fetched by a caller.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.util.concurrent.Future<java.lang.Void> async​(java.lang.Runnable runnable)
      Runs the given Runnable on a new Thread and returns a Future that is set on finish or error.
      static java.util.concurrent.Future<java.lang.Void> async​(java.lang.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> java.util.concurrent.Future<T> async​(java.util.concurrent.Callable<T> callable)
      Calls the given Callable on a new Thread and returns a Future that is set on finish or error.
      static <T> java.util.concurrent.Future<T> async​(java.util.concurrent.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 java.util.concurrent.Future<java.lang.Void> asyncFx​(java.lang.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> java.util.concurrent.Future<T> asyncFx​(java.util.concurrent.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.
      private static void blockFxThreadWithSemaphore()  
      private static boolean callConditionAndReturnResult​(java.util.concurrent.Callable<java.lang.Boolean> condition)  
      static void checkException()
      Checks if an exception in an async task occurred that has not been checked currently.
      private static void checkExceptionWrapped()
      Internal function that throws Exceptions.
      private static java.time.temporal.ChronoUnit chronoUnit​(java.util.concurrent.TimeUnit unit)  
      static void clearExceptions()
      Clears all unhandled exceptions.
      private static java.lang.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.
      private static void printException​(java.lang.Throwable e, java.lang.StackTraceElement[] trace)  
      private static java.lang.String printTrace​(java.lang.StackTraceElement[] st)
      Returns a String containing the printed stacktrace.
      private static void registerException​(java.lang.Throwable throwable)
      Used to add an exception on the stack.
      private static void runOnFxThread​(java.lang.Runnable runnable)  
      private static void setup()
      Needs to be called to setup WaitForAsyncUtils before the first use.
      static void sleep​(long duration, java.util.concurrent.TimeUnit timeUnit)
      Sleeps the current thread for the given duration.
      static void waitFor​(long timeout, java.util.concurrent.TimeUnit timeUnit, java.util.concurrent.Callable<java.lang.Boolean> condition)
      Waits for given Callable to return true otherwise times out with a TimeoutException.
      static <T> T waitFor​(long timeout, java.util.concurrent.TimeUnit timeUnit, java.util.concurrent.Future<T> future)
      Waits for given Future to be set and returns T, otherwise times out with a TimeoutException.
      static void waitFor​(long timeout, java.util.concurrent.TimeUnit timeUnit, javafx.beans.value.ObservableBooleanValue booleanValue)
      Waits for given ObservableBooleanValue to return true otherwise times out with a TimeoutException.
      static <T> T waitFor​(java.util.concurrent.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, java.lang.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, java.util.concurrent.Callable<T> callable)
      Calls the given Callable on a new Thread and waits millis milliseconds for it to finish.
      static void waitForAsyncFx​(long millis, java.lang.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, java.util.concurrent.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.
      private static <T> T waitForMillis​(long millis, java.util.concurrent.Future<T> future)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • CONDITION_SLEEP_IN_MILLIS

        private static final long CONDITION_SLEEP_IN_MILLIS
        See Also:
        Constant Field Values

      • SEMAPHORE_SLEEP_IN_MILLIS

        private static final long SEMAPHORE_SLEEP_IN_MILLIS
        See Also:
        Constant Field Values

      • EXECUTOR_SERVICE

        private static final java.util.concurrent.ExecutorService EXECUTOR_SERVICE

      • EXCEPTIONS

        private static final java.util.Queue<java.lang.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:
        Constant Field Values

    • Constructor Detail

      • WaitForAsyncUtils

        public WaitForAsyncUtils()

    • Method Detail

      • 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 java.util.concurrent.Future<java.lang.Void> async​(java.lang.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 java.util.concurrent.Future<java.lang.Void> async​(java.lang.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> java.util.concurrent.Future<T> async​(java.util.concurrent.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> java.util.concurrent.Future<T> async​(java.util.concurrent.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 java.util.concurrent.Future<java.lang.Void> asyncFx​(java.lang.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> java.util.concurrent.Future<T> asyncFx​(java.util.concurrent.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​(java.util.concurrent.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,
                            java.util.concurrent.TimeUnit timeUnit,
                            java.util.concurrent.Future<T> future)
                     throws java.util.concurrent.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:
        java.util.concurrent.TimeoutException - if the wait timed out

      • waitFor

        public static void waitFor​(long timeout,
                           java.util.concurrent.TimeUnit timeUnit,
                           java.util.concurrent.Callable<java.lang.Boolean> condition)
                    throws java.util.concurrent.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:
        java.util.concurrent.TimeoutException - if the wait timed out

      • waitFor

        public static void waitFor​(long timeout,
                           java.util.concurrent.TimeUnit timeUnit,
                           javafx.beans.value.ObservableBooleanValue booleanValue)
                    throws java.util.concurrent.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:
        java.util.concurrent.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,
                         java.util.concurrent.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,
                                java.lang.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,
                                 java.util.concurrent.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,
                                  java.lang.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,
                                   java.util.concurrent.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 java.lang.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:
        java.lang.Throwable - if an exception has occurred in an async task

      • clearExceptions

        public static void clearExceptions()
        Clears all unhandled exceptions.

      • registerException

        private static void registerException​(java.lang.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 java.lang.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,
                                   java.util.concurrent.Future<T> future)

      • runOnFxThread

        private static void runOnFxThread​(java.lang.Runnable runnable)

      • callConditionAndReturnResult

        private static boolean callConditionAndReturnResult​(java.util.concurrent.Callable<java.lang.Boolean> condition)

      • blockFxThreadWithSemaphore

        private static void blockFxThreadWithSemaphore()

      • printException

        private static void printException​(java.lang.Throwable e,
                                   java.lang.StackTraceElement[] trace)

      • printTrace

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

      • chronoUnit

        private static java.time.temporal.ChronoUnit chronoUnit​(java.util.concurrent.TimeUnit unit)