@Unstable public class WaitForAsyncUtils extends Object
General convention:
async
without a suffix refers to an unknown thread in a ThreadPool
Fx
refers 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:
Usually exceptions are forwarded to the Future
returned by the methods
of this class. When the calling thread calls the getter of 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.
Modifier and Type | Field and Description |
---|---|
static boolean |
autoCheckException
If true any call to the
async methods will check for
unhandled exceptions. |
static boolean |
printException
If true any exceptions encountered during execution of the
async methods will be printed to stderr. |
Constructor and Description |
---|
WaitForAsyncUtils() |
Modifier and Type | Method and Description |
---|---|
static <T> Future<T> |
async(Callable<T> callable)
|
static <T> Future<T> |
async(Callable<T> callable,
boolean throwExceptions)
|
static Future<Void> |
async(Runnable runnable)
|
static Future<Void> |
async(Runnable runnable,
boolean throwExceptions)
|
static <T> Future<T> |
asyncFx(Callable<T> callable)
|
static Future<Void> |
asyncFx(Runnable runnable)
|
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 |
sleepWithException(long duration,
TimeUnit timeUnit)
Sleeps the current thread for the given duration.
|
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 |
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)
|
static void |
waitFor(long timeout,
TimeUnit timeUnit,
ObservableBooleanValue booleanValue)
Waits for given
ObservableBooleanValue to return true otherwise
times out with a TimeoutException . |
static <T> T |
waitForAsync(long millis,
Callable<T> callable)
|
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 |
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 |
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 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. |
public static boolean printException
async
methods will be printed to stderr.public static boolean autoCheckException
async
methods will check for
unhandled exceptions.public static Future<Void> async(Runnable runnable)
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.
runnable
- the runnable to runFuture
result of the runnablepublic static Future<Void> async(Runnable runnable, boolean throwExceptions)
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.
runnable
- the runnable to runthrowExceptions
- whether or not to throw exceptions on the executing
threadFuture
result of the runnablepublic static <T> Future<T> async(Callable<T> callable)
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.
T
- the return type of the callablecallable
- the callable to runFuture
result of the callablepublic static <T> Future<T> async(Callable<T> callable, boolean throwExceptions)
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.
T
- the return type of the callablecallable
- the callable to runthrowExceptions
- whether or not to throw exceptions on the executing
threadFuture
result of the callablepublic static Future<Void> asyncFx(Runnable runnable)
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.
runnable
- the runnable to runFuture
result of the runnablepublic static <T> Future<T> asyncFx(Callable<T> callable)
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.
T
- the callable typecallable
- the callablepublic static <T> T waitFor(Future<T> future)
Future
to be set and then returns the
future result of type T
.T
- the type of the futurefuture
- the future to wait for to be setpublic static <T> T waitFor(long timeout, TimeUnit timeUnit, Future<T> future) throws TimeoutException
T
- the type of the futuretimeout
- the timeout to wait fortimeUnit
- the time unit timeout
is infuture
- the future to wait for to be setTimeoutException
- if the wait timed outpublic static void waitFor(long timeout, TimeUnit timeUnit, Callable<Boolean> condition) throws TimeoutException
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.timeout
- the timeout to wait fortimeUnit
- the time unit timeout
is incondition
- the condition to wait for to be trueTimeoutException
- if the wait timed outpublic static void waitFor(long timeout, TimeUnit timeUnit, ObservableBooleanValue booleanValue) throws TimeoutException
ObservableBooleanValue
to return true otherwise
times out with a TimeoutException
.timeout
- the timeout to wait fortimeUnit
- the time unit timeout
is inbooleanValue
- the observableTimeoutException
- if the wait timed outpublic static void waitForFxEvents()
public static void waitForFxEvents(int attemptsCount)
attemptsCount
attempts for the event queue of the
JavaFX Application Thread to be completed, as well as any new events
triggered on it.attemptsCount
- the number of attempts to trypublic static void sleep(long duration, TimeUnit timeUnit)
duration
- the duration to sleeptimeUnit
- the time unit duration
is inpublic static void sleepWithException(long duration, TimeUnit timeUnit) throws InterruptedException
duration
- the duration to sleeptimeUnit
- the time unit duration
is inInterruptedException
- if any thread has interrupted the current thread. The interrupted
status of the current thread is cleared when this exception is thrown.public static void waitForAsync(long millis, Runnable runnable)
Runnable
on a new Thread
and waits millis
milliseconds for it to finish, otherwise times out with a TimeoutException
.millis
- number of milliseconds to waitrunnable
- the runnable to runpublic static <T> T waitForAsync(long millis, Callable<T> callable)
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
.T
- the type returned by the callablemillis
- number of milliseconds to waitcallable
- the callable to callpublic static void waitForAsyncFx(long millis, Runnable runnable)
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
.millis
- number of milliseconds to waitrunnable
- the runnable to runpublic static <T> T waitForAsyncFx(long millis, Callable<T> callable)
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
.T
- the type returned by the callablemillis
- number of milliseconds to waitcallable
- the callable to callpublic static void checkException() throws Throwable
Throwable
- if an exception has occurred in an async taskpublic static void clearExceptions()