org.threadly.concurrent.future

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:

ExecuteOnGetFutureTask, ImmediateFailureListenableFuture, ImmediateResultListenableFuture, ListenableFutureAdapterTask, ListenableFutureTask, ScheduledFutureDelegate, 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 and Description
static class	ListenableFuture.ListenerOptimizationStrategy Strategy to use for optimizing listener execution.

Method Summary

Modifier and Type	Method and Description
default void	addCallback(FutureCallback<? super T> callback) Add a FutureCallback to be called once the future has completed.
default void	addCallback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor) Add a FutureCallback to be called once the future has completed.
default void	addCallback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution) Add a FutureCallback to be called once the future has completed.
default void	addListener(java.lang.Runnable listener) Add a listener to be called once the future has completed.
default void	addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor) Add a listener to be called once the future has completed.
void	addListener(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>	flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper) Similar to map(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 to map(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 to map(Function, Executor), in that this will apply a mapper function once the applied to future completes.
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 <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.

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Method Detail

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 and ExceptionUtils.handleException(Throwable) will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please see throwMap(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 and ExceptionUtils.handleException(Throwable) will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please see throwMap(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 providing null 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 result

executor - Executor to invoke mapper function on, or null 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 and ExceptionUtils.handleException(Throwable) will be invoked. If you don't want mapped exceptions to be treated as unexpected / uncaught please see throwMap(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 providing null 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 see ListenableFuture.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 result

executor - Executor to invoke mapper function on, or null 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 the mapper function are handled. Please see map(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 a Pair so it can be checked for a maximum number of times like this:

 
   ListenableFuture<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;
          }
        });
 

You would then need to use throwMap(Function) in order to convert that Pair back into a ListenableFuture 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 the mapper function are handled. Please see map(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 see throwMap(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 providing null 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 result

executor - Executor to invoke mapper function on, or null 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 providing null 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 see ListenableFuture.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 result

executor - Executor to invoke mapper function on, or null 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(java.util.function.Function<? super T,ListenableFuture<R>> mapper)

Similar to map(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. Unlike map(Function), this will then unwrap a future provided from the function so that instead of having ListenableFuture<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 to map(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. Unlike map(Function, Executor), this will then unwrap a future provided from the function so that instead of having ListenableFuture<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 providing null 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 result

executor - Executor to invoke mapper function on, or null 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 to map(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. Unlike map(Function, Executor), this will then unwrap a future provided from the function so that instead of having ListenableFuture<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 providing null 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 see ListenableFuture.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 result

executor - Executor to invoke mapper function on, or null 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

addListener

default void addListener(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 addListener(Runnable, Executor).

Parameters:

listener - the listener to run when the computation is complete

addListener

default void addListener(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 complete

executor - Executor the listener should be ran on, or null

addListener

void addListener(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 see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.

Parameters:

listener - the listener to run when the computation is complete

executor - Executor the listener should be ran on, or null

optimizeExecution - true to avoid listener queuing for execution if already on the desired pool

Since:

5.10

addCallback

default void addCallback(FutureCallback<? super T> callback)

Add a FutureCallback 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.

Parameters:

callback - to be invoked when the computation is complete

Since:

1.2.0

addCallback

default void addCallback(FutureCallback<? super T> callback,
                         java.util.concurrent.Executor executor)

Add a FutureCallback 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.

Parameters:

callback - to be invoked when the computation is complete

executor - Executor the callback should be ran on, or null

Since:

1.2.0

addCallback

default void addCallback(FutureCallback<? super T> callback,
                         java.util.concurrent.Executor executor,
                         ListenableFuture.ListenerOptimizationStrategy optimizeExecution)

Add a FutureCallback 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 see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.

Parameters:

callback - to be invoked when the computation is complete

executor - Executor the callback should be ran on, or null

optimizeExecution - true to avoid listener queuing for execution if already on the desired pool

Since:

5.10