Module org.testfx

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 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 java.lang.Object

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

Field Detail

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 Detail

WaitForAsyncUtils

public WaitForAsyncUtils()

Method Detail

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.