SettableListenableFuture (threadly 6.3 API)

java.lang.Object
- org.threadly.concurrent.future.SettableListenableFuture<T>

Type Parameters:

T - The result object type returned by this future

All Implemented Interfaces:

java.util.concurrent.Future<T>, FutureCallback<T>, ListenableFuture<T>
```
public class SettableListenableFuture<T>
extends java.lang.Object
implements ListenableFuture<T>, FutureCallback<T>
```
This class is designed to be a helper when returning a single result asynchronously. This is particularly useful if this result is produced over multiple threads (and thus the scheduler returned future is not useful).

Since:

1.2.0

Nested Class Summary
- Nested classes/interfaces inherited from interface org.threadly.concurrent.future.ListenableFuture
  ListenableFuture.ListenerOptimizationStrategy

Constructor Summary

Constructors
Constructor and Description
`SettableListenableFuture()` Constructs a new `SettableListenableFuture`.
`SettableListenableFuture(boolean throwIfAlreadyComplete)` Constructs a new `SettableListenableFuture`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ListenableFuture<T>`	`callback(FutureCallback<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize)` Add a `FutureCallback` to be called once the future has completed.
`boolean`	`cancel(boolean interruptThread)`
`void`	`clearResult()` Clears the stored result from this set future.
`ListenableFuture<T>`	`failureCallback(java.util.function.Consumer<java.lang.Throwable> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize)` Add a `Consumer` to be called once the future has completed.
`<R> ListenableFuture<R>`	`flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper)` Similar to `ListenableFuture.map(Function)`, in that this will apply a mapper function once the applied to future completes.
`<R> ListenableFuture<R>`	`flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor)` Similar to `ListenableFuture.map(Function, Executor)`, in that this will apply a mapper function once the applied to future completes.
`<R> ListenableFuture<R>`	`flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution)` Similar to `ListenableFuture.map(Function, Executor)`, in that this will apply a mapper function once the applied to future completes.
`<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.
`<TT extends java.lang.Throwable> ListenableFuture<T>`	`flatMapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,ListenableFuture<T>> mapper)` Similar to `ListenableFuture.mapFailure(Class, Function)` except that this mapper function returns a `ListenableFuture` if it needs to map the Throwable / failure into a result or another failure.
`<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 to `ListenableFuture.mapFailure(Class, Function, Executor)` except that this mapper function returns a `ListenableFuture` if it needs to map the Throwable / failure into a result or another failure.
`<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 to `ListenableFuture.mapFailure(Class, Function, Executor, ListenerOptimizationStrategy)` except that this mapper function returns a `ListenableFuture` if it needs to map the Throwable into a result or another failure.
`T`	`get()`
`T`	`get(long timeout, java.util.concurrent.TimeUnit unit)`
`java.lang.Throwable`	`getFailure()` Similar to `Future.get()` except instead of providing a result, this will provide a thrown exception if `ListenableFuture.isCompletedExceptionally()` returns `true`.
`java.lang.Throwable`	`getFailure(long timeout, java.util.concurrent.TimeUnit unit)` Similar to `Future.get(long, TimeUnit)` except instead of providing a result, this will provide a thrown exception if `ListenableFuture.isCompletedExceptionally()` returns `true`.
`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 of `ListenableFuture.map(Function)` or similar functions.
`void`	`handleFailure(java.lang.Throwable t)` This call defers to `setFailure(Throwable)`.
`void`	`handleResult(T result)` This call defers to `setResult(Object)`.
`boolean`	`isCancelled()`
`boolean`	`isCompletedExceptionally()` Returns `true` if the future is both done and has completed with an error or was canceled.
`boolean`	`isDone()`
`ListenableFuture<T>`	`listener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize)` Add a listener to be called once the future has completed.
`<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.
`<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.
`<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.
`<TT extends java.lang.Throwable> ListenableFuture<T>`	`mapFailure(java.lang.Class<TT> throwableType, java.util.function.Function<? super TT,? extends T> mapper)` Similar to `ListenableFuture.throwMap(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).
`<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 to `ListenableFuture.throwMap(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).
`<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 to `ListenableFuture.throwMap(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).
`ListenableFuture<T>`	`resultCallback(java.util.function.Consumer<? super T> callback, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize)` Add a `Consumer` to be called once the future has completed.
`boolean`	`setFailure(java.lang.Throwable failure)` Call to indicate this future is done, and provide the occurred failure.
`boolean`	`setResult(T result)` Call to indicate this future is done, and provide the given result.
`void`	`setRunningThread(java.lang.Thread thread)` Optional call to set the thread internally that will be generating the result for this future.
`<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.
`<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.
`<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 class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.threadly.concurrent.future.ListenableFuture
callback, callback, failureCallback, failureCallback, flatMap, flatMap, flatMap, flatMap, flatMapFailure, flatMapFailure, flatMapFailure, listener, listener, map, map, map, mapFailure, mapFailure, mapFailure, resultCallback, resultCallback, throwMap, throwMap, throwMap

- Constructor Detail
  - SettableListenableFuture
```
public SettableListenableFuture()
```
    Constructs a new SettableListenableFuture. You can return this immediately and provide a result to the object later when it is ready.
    This defaults in the behavior since version 1.2.0 where if the future has completed (either by cancel(boolean), setResult(Object), or setFailure(Throwable)), any additional attempts to setResult(Object) or setFailure(Throwable) will result in a IllegalStateException being thrown.
  - SettableListenableFuture
```
public SettableListenableFuture(boolean throwIfAlreadyComplete)
```
    Constructs a new SettableListenableFuture. You can return this immediately and provide a result to the object later when it is ready.
    This constructor allows you to control the behavior when results are attempt to be set after the future has already completed (either by cancel(boolean), setResult(Object), or setFailure(Throwable)).
    If true, any additional attempts to setResult(Object) or setFailure(Throwable) will result in a IllegalStateException being thrown.
    If false, additional attempts to set a result will just be silently ignored.
    
    Parameters:
    
    throwIfAlreadyComplete - Defines the behavior when result or failure is set on a completed future
- Method Detail
  - listener
```
public ListenableFuture<T> listener(java.lang.Runnable listener,
                                    java.util.concurrent.Executor executor,
                                    ListenableFuture.ListenerOptimizationStrategy optimize)
```
    Description copied from interface: ListenableFuture
    
    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.
    
    Specified by:
    
    listener in interface ListenableFuture<T>
    
    Parameters:
    
    listener - the listener to run when the computation is complete
    
    executor - Executor the listener should be ran on, or null
    
    optimize - 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
  - callback
```
public ListenableFuture<T> callback(FutureCallback<? super T> callback,
                                    java.util.concurrent.Executor executor,
                                    ListenableFuture.ListenerOptimizationStrategy optimize)
```
    Description copied from interface: ListenableFuture
    
    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.
    If you only care about the success result case please see ListenableFuture.resultCallback(Consumer, Executor, ListenerOptimizationStrategy) or conversely if you only want to be invoked for failure cases please see ListenableFuture.failureCallback(Consumer, Executor, ListenerOptimizationStrategy).
    
    Specified by:
    
    callback in interface ListenableFuture<T>
    
    Parameters:
    
    callback - to be invoked when the computation is complete
    
    executor - Executor the callback should be ran on, or null
    
    optimize - 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
  - resultCallback
```
public ListenableFuture<T> resultCallback(java.util.function.Consumer<? super T> callback,
                                          java.util.concurrent.Executor executor,
                                          ListenableFuture.ListenerOptimizationStrategy optimize)
```
    Description copied from interface: ListenableFuture
    
    Add a Consumer 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 the Consumer, 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 see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.
    
    Specified by:
    
    resultCallback in interface ListenableFuture<T>
    
    Parameters:
    
    callback - to be invoked when the computation is complete
    
    executor - Executor the callback should be ran on, or null
    
    optimize - 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
  - failureCallback
```
public ListenableFuture<T> failureCallback(java.util.function.Consumer<java.lang.Throwable> callback,
                                           java.util.concurrent.Executor executor,
                                           ListenableFuture.ListenerOptimizationStrategy optimize)
```
    Description copied from interface: ListenableFuture
    
    Add a Consumer 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, the Throwable will be provided to the Consumer, 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 see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.
    
    Specified by:
    
    failureCallback in interface ListenableFuture<T>
    
    Parameters:
    
    callback - to be invoked when the computation is complete
    
    executor - Executor the callback should be ran on, or null
    
    optimize - 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
  - handleResult
```
public void handleResult(T result)
```
    This call defers to setResult(Object). It is implemented so that you can construct this, return it immediately, but only later provide this as a callback to another ListenableFuture implementation.
    This should never be invoked by the implementor, this should only be invoked by other ListenableFuture's through the use of providing this to ListenableFuture.callback(FutureCallback).
    If this is being used to chain together ListenableFuture's, setResult(Object)/setFailure(Throwable) should never be called manually (or an exception will occur).
    
    Specified by:
    
    handleResult in interface FutureCallback<T>
    
    Parameters:
    
    result - Result object to provide to the future to be returned from get() call
  - handleFailure
```
public void handleFailure(java.lang.Throwable t)
```
    This call defers to setFailure(Throwable). It is implemented so that you can construct this, return it immediately, but only later provide this as a callback to another ListenableFuture implementation. If the parent chained future was canceled this implementation will attempt to cancel the future as well.
    This should never be invoked by the implementor, this should only be invoked by other ListenableFuture's through the use of providing this to ListenableFuture.callback(FutureCallback).
    If this is being used to chain together ListenableFuture's, setResult(Object)/setFailure(Throwable) should never be called manually (or an exception will occur).
    
    Specified by:
    
    handleFailure in interface FutureCallback<T>
    
    Parameters:
    
    t - Throwable to be provided as the cause from the ExecutionException thrown from get() call
  - setResult
```
public boolean setResult(T result)
```
    Call to indicate this future is done, and provide the given result. It is expected that only this or setFailure(Throwable) are called.
    If future has already completed and constructed with SettableListenableFuture() or true provided to SettableListenableFuture(boolean) this will throw an IllegalStateException. If complete but constructed with a false this result will be ignored.
    
    Parameters:
    
    result - result to provide for get() call, can be null
    
    Returns:
    
    true if the result was set (ie future did not complete in failure or cancel}
  - setFailure
```
public boolean setFailure(java.lang.Throwable failure)
```
    Call to indicate this future is done, and provide the occurred failure. It is expected that only this or setResult(Object) are called, and only called once. If the provided failure is null, a new Exception will be created so that something is always provided in the ExecutionException on calls to get().
    If future has already completed and constructed with SettableListenableFuture() or true provided to SettableListenableFuture(boolean) this will throw an IllegalStateException. If complete but constructed with a false this failure result will be ignored.
    
    Parameters:
    
    failure - Throwable that caused failure during computation.
    
    Returns:
    
    true if the failure was set (ie future did not complete with result or cancel}
  - setRunningThread
```
public void setRunningThread(java.lang.Thread thread)
```
    Optional call to set the thread internally that will be generating the result for this future. Setting this thread allows it so that if a cancel(boolean) call is invoked with true, we can send an interrupt to this thread.
    The reference to this thread will be cleared after this future has completed (thus allowing it to be garbage collected).
    
    Parameters:
    
    thread - Thread that is generating the result for this future
  - cancel
```
public boolean cancel(boolean interruptThread)
```
    Specified by:
    
    cancel in interface java.util.concurrent.Future<T>
  - isCancelled
```
public boolean isCancelled()
```
    Specified by:
    
    isCancelled in interface java.util.concurrent.Future<T>
  - clearResult
```
public void clearResult()
```
    Clears the stored result from this set future. This allows the result to be available for garbage collection. After this call, future calls to get() will throw an IllegalStateException. So it is critical that this is only called after you are sure no future calls to get the result on this future will be attempted.
    The design of this is so that if you want to chain ListenableFuture's together, you can clear the results of old ones after their result has been consumed. This is really only useful in very specific instances.
  - isDone
```
public boolean isDone()
```
    Specified by:
    
    isDone in interface java.util.concurrent.Future<T>
  - isCompletedExceptionally
```
public boolean isCompletedExceptionally()
```
    Description copied from interface: ListenableFuture
    
    Returns true if the future is both done and has completed with an error or was canceled. If this returns true the Throwable responsible for the error can be retrieved using ListenableFuture.getFailure();
    
    Specified by:
    
    isCompletedExceptionally in interface ListenableFuture<T>
    
    Returns:
    
    true if this ListenableFuture completed by a thrown Exception or was canceled
  - get
```
public T get()
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException
```
    Specified by:
    
    get in interface java.util.concurrent.Future<T>
    
    Throws:
    
    java.lang.InterruptedException
    
    java.util.concurrent.ExecutionException
  - get
```
public T get(long timeout,
             java.util.concurrent.TimeUnit unit)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException
```
    Specified by:
    
    get in interface java.util.concurrent.Future<T>
    
    Throws:
    
    java.lang.InterruptedException
    
    java.util.concurrent.ExecutionException
    
    java.util.concurrent.TimeoutException
  - getFailure
```
public java.lang.Throwable getFailure()
                               throws java.lang.InterruptedException
```
    Description copied from interface: ListenableFuture
    
    Similar to Future.get() except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true. If the future has not completed yet this function will block until completion. If the future completed normally, this will return null.
    
    Specified by:
    
    getFailure in interface ListenableFuture<T>
    
    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
```
public java.lang.Throwable getFailure(long timeout,
                                      java.util.concurrent.TimeUnit unit)
                               throws java.lang.InterruptedException,
                                      java.util.concurrent.TimeoutException
```
    Description copied from interface: ListenableFuture
    
    Similar to Future.get(long, TimeUnit) except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true. If the future has not completed yet this function will block until completion. If the future completed normally, this will return null.
    
    Specified by:
    
    getFailure in interface ListenableFuture<T>
    
    Parameters:
    
    timeout - The maximum time to wait
    
    unit - 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 blocking
    
    java.util.concurrent.TimeoutException - If the timeout was reached before the future completed
  - getRunningStackTrace
```
public java.lang.StackTraceElement[] getRunningStackTrace()
```
    Description copied from interface: ListenableFuture
    
    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 of ListenableFuture.map(Function) or similar functions. If there is no thread executing the future yet, or the future has already completed, then this will return null.
    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.
    
    Specified by:
    
    getRunningStackTrace in interface ListenableFuture<T>
    
    Returns:
    
    The stack trace currently executing the future, or null if unavailable
  - map
```
public <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper)
```
    Description copied from interface: ListenableFuture
    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 ListenableFuture.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. ListenableFuture.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 ListenableFuture.flatMap(Function) as an alternative.
    Example use:
```
 
   public Integer countSomething(String value);
   
   public ListenableFuture<String> lookupSomething();
   
   ListenableFuture<Integer> count = lookupSomething().map((s) -> countSomething(s));
 
```
    Specified by:
    
    map in interface ListenableFuture<T>
    
    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
  - map
```
public <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper,
                                   java.util.concurrent.Executor executor)
```
    Description copied from interface: ListenableFuture
    
    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 ListenableFuture.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 ListenableFuture.map(Function) or providing null for the executor can allow more efficient operation.
    If your function returns a future, consider using ListenableFuture.flatMap(Function, Executor) as an alternative.
    
    Specified by:
    
    map in interface ListenableFuture<T>
    
    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
  - map
```
public <R> ListenableFuture<R> map(java.util.function.Function<? super T,? extends R> mapper,
                                   java.util.concurrent.Executor executor,
                                   ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
```
    Description copied from interface: ListenableFuture
    
    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 ListenableFuture.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 ListenableFuture.map(Function) or providing null for the executor can allow more efficient operation.
    If your function returns a future, consider using ListenableFuture.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.
    
    Specified by:
    
    map in interface ListenableFuture<T>
    
    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
  - throwMap
```
public <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper)
```
    Description copied from interface: ListenableFuture
    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 ListenableFuture.map(Function) only in how exceptions thrown from the mapper function are handled. Please see ListenableFuture.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 ListenableFuture.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();
       }
     });
 
```
    Specified by:
    
    throwMap in interface ListenableFuture<T>
    
    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
  - throwMap
```
public <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper,
                                        java.util.concurrent.Executor executor)
```
    Description copied from interface: ListenableFuture
    
    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 ListenableFuture.map(Function, Executor) only in how exceptions thrown from the mapper function are handled. Please see ListenableFuture.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 ListenableFuture.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 ListenableFuture.throwMap(Function) or providing null for the executor can allow more efficient operation.
    
    Specified by:
    
    throwMap in interface ListenableFuture<T>
    
    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
  - throwMap
```
public <R> ListenableFuture<R> throwMap(java.util.function.Function<? super T,? extends R> mapper,
                                        java.util.concurrent.Executor executor,
                                        ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
```
    Description copied from interface: ListenableFuture
    
    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 ListenableFuture.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.
    
    Specified by:
    
    throwMap in interface ListenableFuture<T>
    
    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
  - flatMap
```
public <R> ListenableFuture<R> flatMap(ListenableFuture<R> future)
```
    Description copied from interface: ListenableFuture
    
    Convenience function for mapping this future in with an existing future, ignoring the result of this current future. This is equivalent to flatMap((ignored) -> future), and conceptually the same as FutureUtils.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 to flatMap((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.
    
    Specified by:
    
    flatMap in interface ListenableFuture<T>
    
    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
```
public <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper)
```
    Description copied from interface: ListenableFuture
    Similar to ListenableFuture.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 ListenableFuture.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));
 
```
    Specified by:
    
    flatMap in interface ListenableFuture<T>
    
    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
  - flatMap
```
public <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper,
                                       java.util.concurrent.Executor executor)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.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 ListenableFuture.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 ListenableFuture.flatMap(Function) or providing null for the executor can allow more efficient operation.
    
    Specified by:
    
    flatMap in interface ListenableFuture<T>
    
    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
  - flatMap
```
public <R> ListenableFuture<R> flatMap(java.util.function.Function<? super T,ListenableFuture<R>> mapper,
                                       java.util.concurrent.Executor executor,
                                       ListenableFuture.ListenerOptimizationStrategy optimizeExecution)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.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 ListenableFuture.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 ListenableFuture.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.
    
    Specified by:
    
    flatMap in interface ListenableFuture<T>
    
    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
  - mapFailure
```
public <TT extends java.lang.Throwable> ListenableFuture<T> mapFailure(java.lang.Class<TT> throwableType,
                                                                       java.util.function.Function<? super TT,? extends T> mapper)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.throwMap(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 an Optional), 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.
    
    Specified by:
    
    mapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    mapper - 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
  - mapFailure
```
public <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)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.throwMap(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 an Optional), 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.
    
    Specified by:
    
    mapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    mapper - The mapper to convert a thrown exception to either a result or thrown exception
    
    executor - Executor to invoke mapper function on, or null to invoke on this thread or future complete thread (depending on future state)
    
    Returns:
    
    A ListenableFuture that will resolve after the mapper is considered
  - mapFailure
```
public <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)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.throwMap(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 an Optional), 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.
    
    Specified by:
    
    mapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    mapper - The mapper to convert a thrown exception to either a result or thrown exception
    
    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 ListenableFuture that will resolve after the mapper is considered
  - flatMapFailure
```
public <TT extends java.lang.Throwable> ListenableFuture<T> flatMapFailure(java.lang.Class<TT> throwableType,
                                                                           java.util.function.Function<? super TT,ListenableFuture<T>> mapper)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.mapFailure(Class, Function) except that this mapper function returns a ListenableFuture 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 to ListenableFuture.mapFailure(Class, Function) the mapper can also throw an exception directly.
    
    Specified by:
    
    flatMapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    mapper - Function to invoke in order to transform the futures result
    
    Returns:
    
    A ListenableFuture that will resolve after the mapper is considered
  - flatMapFailure
```
public <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)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.mapFailure(Class, Function, Executor) except that this mapper function returns a ListenableFuture 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 to ListenableFuture.mapFailure(Class, Function, Executor) the mapper can also throw an exception directly.
    
    Specified by:
    
    flatMapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    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 ListenableFuture that will resolve after the mapper is considered
  - flatMapFailure
```
public <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)
```
    Description copied from interface: ListenableFuture
    
    Similar to ListenableFuture.mapFailure(Class, Function, Executor, ListenerOptimizationStrategy) except that this mapper function returns a ListenableFuture 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 to ListenableFuture.mapFailure(Class, Function, Executor, ListenerOptimizationStrategy) the mapper can also throw an exception directly.
    
    Specified by:
    
    flatMapFailure in interface ListenableFuture<T>
    
    Type Parameters:
    
    TT - The type of throwable that should be handled
    
    Parameters:
    
    throwableType - The class referencing to the type of throwable this mapper handles
    
    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 ListenableFuture that will resolve after the mapper is considered

Class SettableListenableFuture<T>

Nested Class Summary

Nested classes/interfaces inherited from interface org.threadly.concurrent.future.ListenableFuture

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.threadly.concurrent.future.ListenableFuture

Constructor Detail

SettableListenableFuture

SettableListenableFuture

Method Detail

listener

callback

resultCallback

failureCallback

handleResult

handleFailure

setResult

setFailure

setRunningThread

cancel

isCancelled

clearResult

isDone

isCompletedExceptionally

get

get

getFailure

getFailure

getRunningStackTrace

map

map

map

throwMap

throwMap

throwMap

flatMap

flatMap

flatMap

flatMap

mapFailure

mapFailure

mapFailure

flatMapFailure

flatMapFailure

flatMapFailure