Interface ListenableFuture<T>
-
- Type Parameters:
T
- The result object type returned by this future
- All Superinterfaces:
java.util.concurrent.Future<T>
- All Known Subinterfaces:
ListenableRunnableFuture<T>
,ListenableScheduledFuture<T>
- All Known Implementing Classes:
CancelDebuggingListenableFuture
,ExecuteOnGetFutureTask
,ImmediateFailureListenableFuture
,ImmediateResultListenableFuture
,ListenableFutureAdapterTask
,ListenableFutureTask
,SettableListenableFuture
public interface ListenableFuture<T> extends java.util.concurrent.Future<T>
Future where you can add a listener which is called once the future has completed. The runnable will be called once the future completes either as a cancel, with result, or with an exception.- Since:
- 1.0.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ListenableFuture.ListenerOptimizationStrategy
Strategy to use for optimizing listener execution.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default ListenableFuture<T>
callback(FutureCallback<? super T> callback)
Add aFutureCallback
to be called once the future has completed.default ListenableFuture<T>
callback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor)
Add aFutureCallback
to be called once the future has completed.default ListenableFuture<T>
callback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aFutureCallback
to be called once the future has completed.default ListenableFuture<T>
failureCallback(java.util.function.Consumer<java.lang.Throwable> callback)
Add aConsumer
to be called once the future has completed.default ListenableFuture<T>
failureCallback(java.util.function.Consumer<java.lang.Throwable> callback, java.util.concurrent.Executor executor)
Add aConsumer
to be called once the future has completed.default ListenableFuture<T>
failureCallback(java.util.function.Consumer<java.lang.Throwable> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aConsumer
to be called once the future has completed.default <R> ListenableFuture<R>
flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper)
Similar tomap(Function)
, in that this will apply a mapper function once the applied to future completes.default <R> ListenableFuture<R>
flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor)
Similar tomap(Function, Executor)
, in that this will apply a mapper function once the applied to future completes.default <R> ListenableFuture<R>
flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tomap(Function, Executor)
, in that this will apply a mapper function once the applied to future completes.default <R> ListenableFuture<R>
flatMap(ListenableFuture<R> future)
Convenience function for mapping this future in with an existing future, ignoring the result of this current future.default <TT extends java.lang.Throwable>
ListenableFuture<T>flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper)
Similar tomapFailure(Class, Function)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable / failure into a result or another failure.default <TT extends java.lang.Throwable>
ListenableFuture<T>flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper, java.util.concurrent.Executor executor)
Similar tomapFailure(Class, Function, Executor)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable / failure into a result or another failure.default <TT extends java.lang.Throwable>
ListenableFuture<T>flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tomapFailure(Class, Function, Executor, ListenerOptimizationStrategy)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable into a result or another failure.java.lang.Throwable
getFailure()
Similar toFuture.get()
except instead of providing a result, this will provide a thrown exception ifisCompletedExceptionally()
returnstrue
.java.lang.Throwable
getFailure(long timeout, java.util.concurrent.TimeUnit unit)
Similar toFuture.get(long, TimeUnit)
except instead of providing a result, this will provide a thrown exception ifisCompletedExceptionally()
returnstrue
.java.lang.StackTraceElement[]
getRunningStackTrace()
A best effort to return the stack trace for for the executing thread of either this future, or a future which this depends on through the use ofmap(Function)
or similar functions.boolean
isCompletedExceptionally()
Returnstrue
if the future is both done and has completed with an error or was canceled.default ListenableFuture<T>
listener(java.lang.Runnable listener)
Add a listener to be called once the future has completed.default ListenableFuture<T>
listener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
Add a listener to be called once the future has completed.ListenableFuture<T>
listener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add a listener to be called once the future has completed.default <R> ListenableFuture<R>
map(java.util.function.Function<? super T,? extends R> mapper)
Transform this future's result into another result by applying the provided mapper function.default <R> ListenableFuture<R>
map(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor)
Transform this future's result into another result by applying the provided mapper function.default <R> ListenableFuture<R>
map(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Transform this future's result into another result by applying the provided mapper function.default <TT extends java.lang.Throwable>
ListenableFuture<T>mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper)
Similar tothrowMap(Function)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception).default <TT extends java.lang.Throwable>
ListenableFuture<T>mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper, java.util.concurrent.Executor executor)
Similar tothrowMap(Function, Executor)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception).default <TT extends java.lang.Throwable>
ListenableFuture<T>mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tothrowMap(Function, Executor, ListenerOptimizationStrategy)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception).default ListenableFuture<T>
resultCallback(java.util.function.Consumer<? super T> callback)
Add aConsumer
to be called once the future has completed.default ListenableFuture<T>
resultCallback(java.util.function.Consumer<? super T> callback, java.util.concurrent.Executor executor)
Add aConsumer
to be called once the future has completed.default ListenableFuture<T>
resultCallback(java.util.function.Consumer<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aConsumer
to be called once the future has completed.default <R> ListenableFuture<R>
throwMap(java.util.function.Function<? super T,? extends R> mapper)
Transform this future's result into another result by applying the provided mapper function.default <R> ListenableFuture<R>
throwMap(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor)
Transform this future's result into another result by applying the provided mapper function.default <R> ListenableFuture<R>
throwMap(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Transform this future's result into another result by applying the provided mapper function.
-
-
-
Method Detail
-
isCompletedExceptionally
boolean isCompletedExceptionally()
Returnstrue
if the future is both done and has completed with an error or was canceled. If this returnstrue
theThrowable
responsible for the error can be retrieved usinggetFailure()
;- Returns:
true
if this ListenableFuture completed by a thrown Exception or was canceled
-
getFailure
java.lang.Throwable getFailure() throws java.lang.InterruptedException
Similar toFuture.get()
except instead of providing a result, this will provide a thrown exception ifisCompletedExceptionally()
returnstrue
. If the future has not completed yet this function will block until completion. If the future completed normally, this will returnnull
.- Returns:
- Throwable thrown in computing the future or
null
if completed normally - Throws:
java.lang.InterruptedException
- If the current thread was interrupted while blocking
-
getFailure
java.lang.Throwable getFailure(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException
Similar toFuture.get(long, TimeUnit)
except instead of providing a result, this will provide a thrown exception ifisCompletedExceptionally()
returnstrue
. If the future has not completed yet this function will block until completion. If the future completed normally, this will returnnull
.- Parameters:
timeout
- The maximum time to waitunit
- The time unit of the timeout argument- Returns:
- Throwable thrown in computing the future or
null
if completed normally - Throws:
java.lang.InterruptedException
- If the current thread was interrupted while blockingjava.util.concurrent.TimeoutException
- If the timeout was reached before the future completed
-
map
default <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in. If the mapper function itself throws an Exception, then the returned future will result in the error thrown from the mapper andExceptionUtils.handleException(Throwable)
will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please seethrowMap(Function)
.This can be easily used to chain together a series of operations, happening async (or in calling thread if already complete) until the final result is actually needed.
map(Function, Executor)
can be used if transformation mapper is expensive and thus async execution is absolutely required.If the future is complete already, the function may be invoked on the invoking thread. If the future is not complete then the function will be invoked on the thread which completes the future (immediately after it completes).
If your function returns a future, consider using
flatMap(Function)
as an alternative.Example use:
public Integer countSomething(String value); public ListenableFuture<String> lookupSomething(); ListenableFuture<Integer> count = lookupSomething().map((s) -> countSomething(s));
- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures result- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.0
-
map
default <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in. If the mapper function itself throws an Exception, then the returned future will result in the error thrown from the mapper andExceptionUtils.handleException(Throwable)
will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please seethrowMap(Function, Executor)
.This can be easily used to chain together a series of operations, happening async until the final result is actually needed. Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
map(Function)
or providingnull
for the executor can allow more efficient operation.If your function returns a future, consider using
flatMap(Function, Executor)
as an alternative.- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.0
-
map
default <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in. If the mapper function itself throws an Exception, then the returned future will result in the error thrown from the mapper andExceptionUtils.handleException(Throwable)
will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please seethrowMap(Function, Executor, ListenerOptimizationStrategy)
.This can be easily used to chain together a series of operations, happening async until the final result is actually needed. Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
map(Function)
or providingnull
for the executor can allow more efficient operation.If your function returns a future, consider using
flatMap(Function, Executor)
as an alternative.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.10
-
throwMap
default <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in.This function differs from
map(Function)
only in how exceptions thrown from themapper
function are handled. Please seemap(Function)
for a general understanding for the behavior of this operation. This is to be used when the mapper function throwing an exception is EXPECTED. Used to avoid treating mapping an exception as an unexpected behavior.Say for example you wanted to use
FutureUtils.scheduleWhile()
to retry an operation as long as it kept throwing an exception. You might put the result and exception into aPair
so it can be checked for a maximum number of times like this:
You would then need to useListenableFuture<Pair<ResultType, RetryException>> exceptionConvertingLoop = FutureUtils.scheduleWhile(scheduler, retryDelayMillis, true, () -> { try { return new Pair<>(makeResultOrThrow(), null); } catch (RetryException e) { // we can't throw or we will break the loop return new Pair<>(null, e); } }, new Predicate<Pair<?, RetryException>>() { private int selfRetryCount = 0; public boolean test(Pair<?, RetryException> p) { return p.getLeft() == null && ++selfRetryCount <= maxRetryCount; } });
throwMap(Function)
in order to convert thatPair
back into aListenableFuture
with either a result, or the contained failure. For example:ListenableFuture<ResultType> resultFuture = exceptionConvertingLoop.throwMap((p) -> { if (p.getLeft() != null) { return p.getLeft(); } else { throw p.getRight(); } });
- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures result- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.11
-
throwMap
default <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in.This function differs from
map(Function, Executor)
only in how exceptions thrown from themapper
function are handled. Please seemap(Function, Executor)
for a general understanding for the behavior of this operation. This is to be used when the mapper function throwing an exception is EXPECTED. Used to avoid treating mapping an exception as an unexpected behavior. Please seethrowMap(Function)
for more usage examples.Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
throwMap(Function)
or providingnull
for the executor can allow more efficient operation.- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.11
-
throwMap
default <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Transform this future's result into another result by applying the provided mapper function. If this future completed in error, then the mapper will not be invoked, and instead the returned future will be completed in the same error state this future resulted in. If the mapper function itself throws an Exception, then the returned future will result in the error thrown from the mapper.This can be easily used to chain together a series of operations, happening async until the final result is actually needed. Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
throwMap(Function)
or providingnull
for the executor can allow more efficient operation.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Type Parameters:
R
- The type for the object returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.11
-
flatMap
default <R> ListenableFuture<R> flatMap(ListenableFuture<R> future)
Convenience function for mapping this future in with an existing future, ignoring the result of this current future. This is equivalent toflatMap((ignored) -> future)
, and conceptually the same asFutureUtils.makeFailurePropagatingCompleteFuture(Iterable)
with both futures being provided (though this allows us to capture the result of the provided future).Please be aware that
flatMap(futureProducer.get())
is NOT equivalent toflatMap((ignored) -> futureProducer.get())
. As the second version would delay starting the future generation until this future completes. By calling into this with a future you will be starting its execution immediately.- Type Parameters:
R
- The type of result returned from the provided future- Parameters:
future
- The future to flat mpa against this one- Returns:
- A new
ListenableFuture
that will complete when both this and the provided future does
-
flatMap
default <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper)
Similar tomap(Function)
, in that this will apply a mapper function once the applied to future completes. Once this future resolves it will provide the result into the provided function. Unlikemap(Function)
, this will then unwrap a future provided from the function so that instead of havingListenableFuture<ListenableFuture<R>>
you can simply extract the final value. The returned future will only resolve once the future of the provided function completes.If the future is complete already, the function may be invoked on the invoking thread. If the future is not complete then the function will be invoked on the thread which completes the future (immediately after it completes).
Example use:
public ListenableFuture<Integer> countSomething(String value); public ListenableFuture<String> lookupSomething(); ListenableFuture<Integer> count = lookupSomething().flatMap((s) -> countSomething(s));
- Type Parameters:
R
- The type for the object contained in the future which is returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures result- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.0
-
flatMap
default <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor)
Similar tomap(Function, Executor)
, in that this will apply a mapper function once the applied to future completes. Once this future resolves it will provide the result into the provided function. Unlikemap(Function, Executor)
, this will then unwrap a future provided from the function so that instead of havingListenableFuture<ListenableFuture<R>>
you can simply extract the final value. The returned future will only resolve once the future of the provided function completes.Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
flatMap(Function)
or providingnull
for the executor can allow more efficient operation.- Type Parameters:
R
- The type for the object contained in the future which is returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.0
-
flatMap
default <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tomap(Function, Executor)
, in that this will apply a mapper function once the applied to future completes. Once this future resolves it will provide the result into the provided function. Unlikemap(Function, Executor)
, this will then unwrap a future provided from the function so that instead of havingListenableFuture<ListenableFuture<R>>
you can simply extract the final value. The returned future will only resolve once the future of the provided function completes.Once the future completes the mapper function will be invoked on the executor (if provided). Because of that providing an executor can ensure this will never block. If an executor is not provided then the mapper may be invoked on the calling thread (if the future is already complete), or on the same thread which the future completes on. If the mapper function is very fast and cheap to run then
flatMap(Function)
or providingnull
for the executor can allow more efficient operation.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Type Parameters:
R
- The type for the object contained in the future which is returned from the mapper- Parameters:
mapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- A new
ListenableFuture
with the specified result type - Since:
- 5.10
-
mapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper)
Similar tothrowMap(Function)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception). If this future does resolve in a failure state, and that exception class matches the one provided here. The mapper function will then be provided that throwable, it can then map that throwable back into a result (perhaps anOptional
), or re-throw either the same or a different exception keep the future in a failure state. If the future completes with a normal result, this mapper will be ignored, and the result will be forwarded on without invoking this mapper.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- The mapper to convert a thrown exception to either a result or thrown exception- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
mapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper, java.util.concurrent.Executor executor)
Similar tothrowMap(Function, Executor)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception). If this future does resolve in a failure state, and that exception class matches the one provided here. The mapper function will then be provided that throwable, it can then map that throwable back into a result (perhaps anOptional
), or re-throw either the same or a different exception keep the future in a failure state. If the future completes with a normal result, this mapper will be ignored, and the result will be forwarded on without invoking this mapper.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- The mapper to convert a thrown exception to either a result or thrown exceptionexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
mapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tothrowMap(Function, Executor, ListenerOptimizationStrategy)
except this mapper will only be invoked when the future is in a failure state (from either the original computation or an earlier mapper throwing an exception). If this future does resolve in a failure state, and that exception class matches the one provided here. The mapper function will then be provided that throwable, it can then map that throwable back into a result perhaps anOptional
), or re-throw either the same or a different exception keep the future in a failure state. If the future completes with a normal result, this mapper will be ignored, and the result will be forwarded on without invoking this mapper.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- The mapper to convert a thrown exception to either a result or thrown exceptionexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
flatMapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper)
Similar tomapFailure(Class, Function)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable / failure into a result or another failure. The mapper function can return a Future that will (or may) provide a result, or it can provide a future that will result in the same or another failure. Similar tomapFailure(Class, Function)
the mapper can also throw an exception directly.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- Function to invoke in order to transform the futures result- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
flatMapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper, java.util.concurrent.Executor executor)
Similar tomapFailure(Class, Function, Executor)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable / failure into a result or another failure. The mapper function can return a Future that will (or may) provide a result, or it can provide a future that will result in the same or another failure. Similar tomapFailure(Class, Function, Executor)
the mapper can also throw an exception directly.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
flatMapFailure
default <TT extends java.lang.Throwable> ListenableFuture<T> flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Similar tomapFailure(Class, Function, Executor, ListenerOptimizationStrategy)
except that this mapper function returns aListenableFuture
if it needs to map the Throwable into a result or another failure. The mapper function can return a Future that will (or may) provide a result, or it can provide a future that will result in the same or another failure. Similar tomapFailure(Class, Function, Executor, ListenerOptimizationStrategy)
the mapper can also throw an exception directly.- Type Parameters:
TT
- The type of throwable that should be handled- Parameters:
throwableType
- The class referencing to the type of throwable this mapper handlesmapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, ornull
to invoke on this thread or future complete thread (depending on future state)optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- A
ListenableFuture
that will resolve after the mapper is considered - Since:
- 5.17
-
listener
default ListenableFuture<T> listener(java.lang.Runnable listener)
Add a listener to be called once the future has completed. If the future has already finished, this will be called immediately.The listener from this call will execute on the same thread the result was produced on, or on the adding thread if the future is already complete. If the runnable has high complexity, consider using
listener(Runnable, Executor)
.- Parameters:
listener
- the listener to run when the computation is complete- Returns:
- Exactly
this
instance to add more listeners or other functional operations - Since:
- 5.34
-
listener
default ListenableFuture<T> listener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
Add a listener to be called once the future has completed. If the future has already finished, this will be called immediately.If the provided
Executor
is null, the listener will execute on the thread which computed the original future (once it is done). If the future has already completed, the listener will execute immediately on the thread which is adding the listener.- Parameters:
listener
- the listener to run when the computation is completeexecutor
-Executor
the listener should be ran on, ornull
- Returns:
- Exactly
this
instance to add more listeners or other functional operations - Since:
- 5.34
-
listener
ListenableFuture<T> listener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add a listener to be called once the future has completed. If the future has already finished, this will be called immediately.If the provided
Executor
is null, the listener will execute on the thread which computed the original future (once it is done). If the future has already completed, the listener will execute immediately on the thread which is adding the listener.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Parameters:
listener
- the listener to run when the computation is completeexecutor
-Executor
the listener should be ran on, ornull
optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- Exactly
this
instance to add more listeners or other functional operations - Since:
- 5.34
-
callback
default ListenableFuture<T> callback(FutureCallback<? super T> callback)
Add aFutureCallback
to be called once the future has completed. If the future has already finished, this will be called immediately.The callback from this call will execute on the same thread the result was produced on, or on the adding thread if the future is already complete. If the callback has high complexity, consider passing an executor in for it to be called on.
If you only care about the success result case please see
resultCallback(Consumer)
or conversely if you only want to be invoked for failure cases please seefailureCallback(Consumer)
.- Parameters:
callback
- to be invoked when the computation is complete- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
callback
default ListenableFuture<T> callback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor)
Add aFutureCallback
to be called once the future has completed. If the future has already finished, this will be called immediately.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.If you only care about the success result case please see
resultCallback(Consumer, Executor)
or conversely if you only want to be invoked for failure cases please seefailureCallback(Consumer, Executor)
.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
callback
default ListenableFuture<T> callback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aFutureCallback
to be called once the future has completed. If the future has already finished, this will be called immediately.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.If you only care about the success result case please see
resultCallback(Consumer, Executor, ListenerOptimizationStrategy)
or conversely if you only want to be invoked for failure cases please seefailureCallback(Consumer, Executor, ListenerOptimizationStrategy)
.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
resultCallback
default ListenableFuture<T> resultCallback(java.util.function.Consumer<? super T> callback)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed without error, the result will be provided to theConsumer
, otherwise it will go un-invoked.The callback from this call will execute on the same thread the result was produced on, or on the adding thread if the future is already complete. If the callback has high complexity, consider passing an executor in for it to be called on.
- Parameters:
callback
- to be invoked when the computation is complete- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
resultCallback
default ListenableFuture<T> resultCallback(java.util.function.Consumer<? super T> callback, java.util.concurrent.Executor executor)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed without error, the result will be provided to theConsumer
, otherwise it will go un-invoked.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
resultCallback
default ListenableFuture<T> resultCallback(java.util.function.Consumer<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed without error, the result will be provided to theConsumer
, otherwise it will go un-invoked.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
failureCallback
default ListenableFuture<T> failureCallback(java.util.function.Consumer<java.lang.Throwable> callback)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed with an error, theThrowable
will be provided to theConsumer
, otherwise if no error occurred, the callback will go un-invoked.The callback from this call will execute on the same thread the result was produced on, or on the adding thread if the future is already complete. If the callback has high complexity, consider passing an executor in for it to be called on.
- Parameters:
callback
- to be invoked when the computation is complete- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
failureCallback
default ListenableFuture<T> failureCallback(java.util.function.Consumer<java.lang.Throwable> callback, java.util.concurrent.Executor executor)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed with an error, theThrowable
will be provided to theConsumer
, otherwise if no error occurred, the callback will go un-invoked.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
failureCallback
default ListenableFuture<T> failureCallback(java.util.function.Consumer<java.lang.Throwable> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
Add aConsumer
to be called once the future has completed. If the future has already finished, this will be called immediately. Assuming the future has completed with an error, theThrowable
will be provided to theConsumer
, otherwise if no error occurred, the callback will go un-invoked.If the provided
Executor
is null, the callback will execute on the thread which computed the original future (once it is done). If the future has already completed, the callback will execute immediately on the thread which is adding the callback.Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all
ListenableFuture
implementations may be able to do such an optimization. Please seeListenableFuture.ListenerOptimizationStrategy
javadocs for more specific details of what optimizations are available.- Parameters:
callback
- to be invoked when the computation is completeexecutor
-Executor
the callback should be ran on, ornull
optimizeExecution
-true
to avoid listener queuing for execution if already on the desired pool- Returns:
- Exactly
this
instance to add more callbacks or other functional operations - Since:
- 5.34
-
getRunningStackTrace
java.lang.StackTraceElement[] getRunningStackTrace()
A best effort to return the stack trace for for the executing thread of either this future, or a future which this depends on through the use ofmap(Function)
or similar functions. If there is no thread executing the future yet, or the future has already completed, then this will returnnull
.This is done without locking (though generating a stack trace still requires a JVM safe point), so the resulting stack trace is NOT guaranteed to be accurate. In most cases (particularly when blocking) this should be accurate though.
- Returns:
- The stack trace currently executing the future, or
null
if unavailable
-
-