T
- The result object type returned by this futurepublic interface ListenableFuture<T>
extends java.util.concurrent.Future<T>
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. |
void |
addListener(java.lang.Runnable listener)
Add a listener to be called once the future has completed.
|
void |
addListener(java.lang.Runnable listener,
java.util.concurrent.Executor executor)
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> |
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)
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));
R
- The type for the object returned from the mappermapper
- Function to invoke in order to transform the futures resultListenableFuture
with the specified result typedefault <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper, java.util.concurrent.Executor 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.
R
- The type for the object returned from the mappermapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, or null
to invoke on this thread or future complete thread (depending on future state)ListenableFuture
with the specified result typedefault <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper)
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 flatMap(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));
R
- The type for the object contained in the future which is returned from the mappermapper
- Function to invoke in order to transform the futures resultListenableFuture
with the specified result typedefault <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor)
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 flatMap(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.
R
- The type for the object contained in the future which is returned from the mappermapper
- Function to invoke in order to transform the futures resultexecutor
- Executor to invoke mapper function on, or null
to invoke on this thread or future complete thread (depending on future state)ListenableFuture
with the specified result typevoid addListener(java.lang.Runnable listener)
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)
.
listener
- the listener to run when the computation is completevoid addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
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.
listener
- the listener to run when the computation is completeexecutor
- Executor
the listener should be ran on, or null
default void addCallback(FutureCallback<? super T> callback)
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.
callback
- to be invoked when the computation is completedefault void addCallback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor)
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.
callback
- to be invoked when the computation is completeexecutor
- Executor
the callback should be ran on, or null