Class WaitForAsyncUtils
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 RuntimeException
s.
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Internally usedCallable
that handles all the async stuff.private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic boolean
If true any call to anasync
method will check for the occurrence of unhandled exceptions.static boolean
If true any call to anasync
method will check for the occurrence of unhandled exceptions in anyThread
.private static final long
private static final ExecutorService
private static final String
static boolean
If true any exceptions encountered during execution of theasync
methods will be printed to stderr.private static final int
private static final long
private static final boolean
If true exceptions will be printed when they are fetched by a caller. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Future
<T> static <T> Future
<T> static <T> Future
<T> private static void
private static boolean
callConditionAndReturnResult
(Callable<Boolean> condition) static void
Checks if an exception in an async task occurred that has not been checked currently.private static void
Internal function that throws Exceptions.private static ChronoUnit
chronoUnit
(TimeUnit unit) static void
Clears all unhandled exceptions.private static Throwable
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
(Throwable e, StackTraceElement[] trace) private static String
printTrace
(StackTraceElement[] st) Returns aString
containing the printed stacktrace.private static void
registerException
(Throwable throwable) Used to add an exception on the stack.private static void
runOnFxThread
(Runnable runnable) private static void
setup()
Needs to be called to setup WaitForAsyncUtils before the first use.static void
Sleeps the current thread for the given duration.static void
Waits for givenCallable
to return true otherwise times out with aTimeoutException
.static <T> T
static void
Waits for givenObservableBooleanValue
to return true otherwise times out with aTimeoutException
.static <T> T
Waits for the givenFuture
to be set and then returns the future result of typeT
.static void
waitForAsync
(long millis, Runnable runnable) Runs the givenRunnable
on a newThread
and waitsmillis
milliseconds for it to finish, otherwise times out with aTimeoutException
.static <T> T
waitForAsync
(long millis, Callable<T> callable) static void
waitForAsyncFx
(long millis, Runnable runnable) Runs the givenRunnable
on the JavaFX Application Thread at some unspecified time in the future and waitsmillis
milliseconds for it to finish, otherwise times out with aTimeoutException
.static <T> T
waitForAsyncFx
(long millis, Callable<T> callable) Calls the givenCallable
on the JavaFX Application Thread at some unspecified time in the future and waitsmillis
milliseconds for it to finish.static void
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 toattemptsCount
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, Future<T> future)
-
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
- See Also:
-
EXECUTOR_SERVICE
-
EXCEPTIONS
-
printException
public static boolean printExceptionIf true any exceptions encountered during execution of theasync
methods will be printed to stderr. The exceptions will be printed at the time they occur (not when fetched). -
autoCheckException
public static boolean autoCheckExceptionIf true any call to anasync
method will check for the occurrence of unhandled exceptions. -
checkAllExceptions
public static boolean checkAllExceptionsIf true any call to anasync
method will check for the occurrence of unhandled exceptions in anyThread
. -
TRACE_FETCH
private static final boolean TRACE_FETCHIf 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 flagcheckAllExceptions
. -
async
Runs the givenRunnable
on a newThread
and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Parameters:
runnable
- theRunnable
to run- Returns:
- the
Future
result of theRunnable
-
async
Runs the givenRunnable
on a newThread
and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Parameters:
runnable
- theRunnable
to runthrowExceptions
- whether or not to throw exceptions on the executing thread- Returns:
- the
Future
result of the runnable
-
async
Calls the givenCallable
on a newThread
and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Type Parameters:
T
- the return type of theCallable
- Parameters:
callable
- theCallable
to run- Returns:
- the
Future
result of theCallable
-
async
Calls the givenCallable
on a newThread
and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Type Parameters:
T
- the return type of theCallable
- Parameters:
callable
- theCallable
to runthrowExceptions
- whether or not to throw exceptions on the executing thread- Returns:
- the
Future
result of theCallable
-
asyncFx
Runs the givenRunnable
on the JavaFX Application Thread at some unspecified time in the future and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Parameters:
runnable
- theRunnable
to run- Returns:
- the
Future
result of theRunnable
-
asyncFx
Calls the givenCallable
on the JavaFX Application Thread at some unspecified time in the future and returns aFuture
that is set on finish or error.You need to evaluate the returned
Future
via (Future.get()
) for exceptions or call thecheckException()
method to handle exceptions after the task has finished.- Type Parameters:
T
- theCallable
type- Parameters:
callable
- theCallable
- Returns:
- the
Future
result of theCallable
-
waitFor
Waits for the givenFuture
to be set and then returns the future result of typeT
.- Type Parameters:
T
- the type of theFuture
- Parameters:
future
- theFuture
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 - Type Parameters:
T
- the type of theFuture
- Parameters:
timeout
- the timeout to wait fortimeUnit
- the time unittimeout
is infuture
- theFuture
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 givenCallable
to return true otherwise times out with aTimeoutException
. 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 fortimeUnit
- the time unittimeout
is incondition
- 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 givenObservableBooleanValue
to return true otherwise times out with aTimeoutException
.- Parameters:
timeout
- the timeout to wait fortimeUnit
- the time unittimeout
is inbooleanValue
- 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 toattemptsCount
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
Sleeps the current thread for the given duration.- Parameters:
duration
- the duration to sleeptimeUnit
- the time unitduration
is in
-
waitForAsync
Runs the givenRunnable
on a newThread
and waitsmillis
milliseconds for it to finish, otherwise times out with aTimeoutException
.- Parameters:
millis
- number of milliseconds to waitrunnable
- theRunnable
to run
-
waitForAsync
Calls the givenCallable
on a newThread
and waitsmillis
milliseconds for it to finish. If finished, returns the future result of typeT
, otherwise times out with aTimeoutException
.- Type Parameters:
T
- the type returned by theCallable
- Parameters:
millis
- number of milliseconds to waitcallable
- theCallable
to call- Returns:
- the result returned by the
Callable
-
waitForAsyncFx
Runs the givenRunnable
on the JavaFX Application Thread at some unspecified time in the future and waitsmillis
milliseconds for it to finish, otherwise times out with aTimeoutException
.- Parameters:
millis
- number of milliseconds to waitrunnable
- theRunnable
to run
-
waitForAsyncFx
Calls the givenCallable
on the JavaFX Application Thread at some unspecified time in the future and waitsmillis
milliseconds for it to finish. If finished, returnsT
otherwise times out with aTimeoutException
.- Type Parameters:
T
- the type returned by theCallable
- Parameters:
millis
- number of milliseconds to waitcallable
- theCallable
to call- Returns:
- the result returned by the
Callable
-
checkException
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
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
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
-
runOnFxThread
-
callConditionAndReturnResult
-
blockFxThreadWithSemaphore
private static void blockFxThreadWithSemaphore() -
printException
-
printTrace
Returns aString
containing the printed stacktrace.- Parameters:
st
- the stacktrace- Returns:
- a
String
containing the printed stacktrace
-
chronoUnit
-