T - Type of the computation result.public interface Future<T> extends Value<T>
The underlying ExecutorService is used to execute asynchronous handlers, e.g. via
onComplete(...).
A Future has two states: pending and completed.
| Modifier and Type | Field and Description |
|---|---|
static ExecutorService |
DEFAULT_EXECUTOR_SERVICE
The default executor service is
Executors.newCachedThreadPool(). |
| Modifier and Type | Method and Description |
|---|---|
default Future<T> |
andThen(Consumer<? super Try<T>> action)
Support for chaining of callbacks that are guaranteed to be executed in a specific order.
|
void |
await()
Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
|
default boolean |
cancel()
Cancels the Future.
|
boolean |
cancel(boolean mayInterruptIfRunning)
Cancels the Future.
|
ExecutorService |
executorService()
Returns the
ExecutorService used by this Future. |
default Future<Throwable> |
failed()
A projection that inverses the result of this Future.
|
static <T> Future<T> |
failed(ExecutorService executorService,
Throwable exception)
|
static <T> Future<T> |
failed(Throwable exception)
|
default Future<T> |
fallbackTo(Future<? extends T> that)
Returns a Future that returns the result of this Future, if it is a success.
|
default Future<T> |
filter(Predicate<? super T> predicate)
Shortcut for
filterTry(predicate::test. |
default Future<T> |
filterTry(Try.CheckedPredicate<? super T> predicate)
Filters the result of this
Future by calling Try.filterTry(CheckedPredicate). |
static <T> Future<Option<T>> |
find(ExecutorService executorService,
Iterable<? extends Future<? extends T>> futures,
Predicate<? super T> predicate)
Returns a
Future that eventually succeeds with the first result of the given Futures which
matches the given predicate. |
static <T> Future<Option<T>> |
find(Iterable<? extends Future<? extends T>> futures,
Predicate<? super T> predicate)
Returns a
Future that eventually succeeds with the first result of the given Futures which
matches the given predicate. |
static <T> Future<T> |
firstCompletedOf(ExecutorService executorService,
Iterable<? extends Future<? extends T>> futures)
Returns a new
Future that will contain the result of the first of the given futures that is completed,
backed by the given ExecutorService. |
static <T> Future<T> |
firstCompletedOf(Iterable<? extends Future<? extends T>> futures)
Returns a new
Future that will contain the result of the first of the given futures that is completed,
backed by the DEFAULT_EXECUTOR_SERVICE. |
default <U> Future<U> |
flatMap(Function<? super T,? extends Future<? extends U>> mapper) |
default <U> Future<U> |
flatMapTry(Try.CheckedFunction<? super T,? extends Future<? extends U>> mapper) |
static <T,U> Future<U> |
fold(ExecutorService executorService,
Iterable<? extends Future<? extends T>> futures,
U zero,
BiFunction<? super U,? super T,? extends U> f)
Returns a Future which contains the result of the fold of the given future values.
|
static <T,U> Future<U> |
fold(Iterable<? extends Future<? extends T>> futures,
U zero,
BiFunction<? super U,? super T,? extends U> f)
Returns a Future which contains the result of the fold of the given future values.
|
default void |
forEach(Consumer<? super T> action)
Performs the given
action asynchronously hence this Future result becomes available. |
static <T> Future<T> |
fromJavaFuture(ExecutorService executorService,
Future<T> future)
Creates a
Future with the given java.util.concurrent.Future, backed by given ExecutorService |
static <T> Future<T> |
fromJavaFuture(Future<T> future)
Creates a
Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR_SERVICE |
static <T> Future<T> |
fromTry(ExecutorService executorService,
Try<? extends T> result)
|
static <T> Future<T> |
fromTry(Try<? extends T> result)
|
default T |
get()
Returns the value of the future.
|
default Option<Throwable> |
getCause()
Returns the underlying exception of this Future, syntactic sugar for
future.getValue().map(Try::getCause). |
Option<Try<T>> |
getValue()
Returns the value of the Future.
|
boolean |
isCompleted()
Checks if this Future is completed, i.e.
|
default boolean |
isEmpty()
Checks, if this future has a value.
|
default boolean |
isFailure()
Checks if this Future completed with a failure.
|
default boolean |
isSingleValued()
A
Future is single-valued. |
default boolean |
isSuccess()
Checks if this Future completed with a success.
|
default Iterator<T> |
iterator()
Returns a rich
javaslang.collection.Iterator. |
default <U> Future<U> |
map(Function<? super T,? extends U> mapper)
Maps the underlying value to a different component type.
|
default <U> Future<U> |
mapTry(Try.CheckedFunction<? super T,? extends U> mapper) |
static <T> Future<T> |
narrow(Future<? extends T> future)
Narrows a widened
Future<? extends T> to Future<T>
by performing a type safe-cast. |
static <T> Future<T> |
of(ExecutorService executorService,
Try.CheckedSupplier<? extends T> computation)
Starts an asynchronous computation, backed by the given
ExecutorService. |
static <T> Future<T> |
of(Try.CheckedSupplier<? extends T> computation)
Starts an asynchronous computation, backed by the
DEFAULT_EXECUTOR_SERVICE. |
Future<T> |
onComplete(Consumer<? super Try<T>> action)
Performs the action once the Future is complete.
|
default Future<T> |
onFailure(Consumer<? super Throwable> action)
Performs the action once the Future is complete and the result is a
Try.Failure. |
default Future<T> |
onSuccess(Consumer<? super T> action)
Performs the action once the Future is complete and the result is a
Try.Success. |
default Future<T> |
orElse(Future<? extends T> other) |
default Future<T> |
orElse(Supplier<? extends Future<? extends T>> supplier) |
default Future<T> |
peek(Consumer<? super T> action)
Performs the given
action on the first element if this is an eager implementation. |
default Future<T> |
recover(Function<? super Throwable,? extends T> f)
Handles a failure of this Future by returning another result.
|
default Future<T> |
recoverWith(Function<? super Throwable,? extends Future<? extends T>> f)
Handles a failure of this Future by returning the result of another Future.
|
static <T> Future<T> |
reduce(ExecutorService executorService,
Iterable<? extends Future<? extends T>> futures,
BiFunction<? super T,? super T,? extends T> f)
Returns a Future which contains the reduce result of the given future values.
|
static <T> Future<T> |
reduce(Iterable<? extends Future<? extends T>> futures,
BiFunction<? super T,? super T,? extends T> f)
Returns a Future which contains the reduce result of the given future values.
|
static Future<Void> |
run(ExecutorService executorService,
Try.CheckedRunnable unit)
Starts an asynchronous computation, backed by the given
ExecutorService. |
static Future<Void> |
run(Try.CheckedRunnable unit)
Runs an asynchronous computation, backed by the
DEFAULT_EXECUTOR_SERVICE. |
static <T> Future<Seq<T>> |
sequence(ExecutorService executorService,
Iterable<? extends Future<? extends T>> futures)
Reduces many
Futures into a single Future by transforming an
Iterable<Future<? extends T>> into a Future<Seq<T>>. |
static <T> Future<Seq<T>> |
sequence(Iterable<? extends Future<? extends T>> futures)
Reduces many
Futures into a single Future by transforming an
Iterable<Future<? extends T>> into a Future<Seq<T>>. |
default String |
stringPrefix()
Returns the name of this Value type, which is used by toString().
|
static <T> Future<T> |
successful(ExecutorService executorService,
T result)
Creates a succeeded
Future, backed by the given ExecutorService. |
static <T> Future<T> |
successful(T result)
Creates a succeeded
Future, backed by the DEFAULT_EXECUTOR_SERVICE. |
default <U> U |
transform(Function<? super Future<T>,? extends U> f)
Transforms this
Future. |
static <T,U> Future<Seq<U>> |
traverse(ExecutorService executorService,
Iterable<? extends T> values,
Function<? super T,? extends Future<? extends U>> mapper)
Maps the values of an iterable in parallel to a sequence of mapped values into a single
Future by
transforming an Iterable<? extends T> into a Future<Seq<U>>. |
static <T,U> Future<Seq<U>> |
traverse(Iterable<? extends T> values,
Function<? super T,? extends Future<? extends U>> mapper)
Maps the values of an iterable in parallel to a sequence of mapped values into a single
Future by
transforming an Iterable<? extends T> into a Future<Seq<U>>. |
default <U> Future<Tuple2<T,U>> |
zip(Future<? extends U> that)
Returns a tuple of this and that Future result.
|
contains, corresponds, eq, equals, exists, forAll, getOption, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, hashCode, narrow, out, out, stderr, stdout, toArray, toCharSeq, toJavaArray, toJavaArray, toJavaCollection, toJavaList, toJavaList, toJavaMap, toJavaMap, toJavaOptional, toJavaSet, toJavaSet, toJavaStream, toLeft, toLeft, toList, toMap, toOption, toQueue, toRight, toRight, toSet, toStack, toStream, toString, toTree, toTry, toTry, toVectorspliteratorstatic final ExecutorService DEFAULT_EXECUTOR_SERVICE
Executors.newCachedThreadPool().
Please note that it may prevent the VM from shutdown.}static <T> Future<T> failed(Throwable exception)
T - The value type of a successful result.exception - The reason why it failed.Future.NullPointerException - if exception is nullstatic <T> Future<T> failed(ExecutorService executorService, Throwable exception)
T - The value type of a successful result.executorService - An executor service.exception - The reason why it failed.Future.NullPointerException - if executorService or exception is nullstatic <T> Future<Option<T>> find(Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate)
Future that eventually succeeds with the first result of the given Futures which
matches the given predicate. If no result matches, the Future will contain Option.None.
The returned Future is backed by the DEFAULT_EXECUTOR_SERVICE.
T - Result type of the futures.futures - An iterable of futures.predicate - A predicate that tests successful future results.Option of the first result of the given futures that satisfies the given predicate.NullPointerException - if one of the arguments is nullstatic <T> Future<Option<T>> find(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate)
Future that eventually succeeds with the first result of the given Futures which
matches the given predicate. If no result matches, the Future will contain Option.None.
The returned Future is backed by the given ExecutorService.
T - Result type of the futures.executorService - An executor service.futures - An iterable of futures.predicate - A predicate that tests successful future results.Option of the first result of the given futures that satisfies the given predicate.NullPointerException - if one of the arguments is nullstatic <T> Future<T> firstCompletedOf(Iterable<? extends Future<? extends T>> futures)
Future that will contain the result of the first of the given futures that is completed,
backed by the DEFAULT_EXECUTOR_SERVICE.T - The result type.futures - An iterable of futures.Future.NullPointerException - if futures is nullstatic <T> Future<T> firstCompletedOf(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures)
Future that will contain the result of the first of the given futures that is completed,
backed by the given ExecutorService.T - The result type.executorService - An executor service.futures - An iterable of futures.Future.NullPointerException - if executorService or futures is nullstatic <T,U> Future<U> fold(Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U,? super T,? extends U> f)
The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.
T - The result type of the given Futures.U - The fold result type.futures - An iterable of futures.zero - The zero element of the fold.f - The fold operation.Future that will contain the fold result.NullPointerException - if futures or f is null.static <T,U> Future<U> fold(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U,? super T,? extends U> f)
The resulting Future is backed by the given ExecutorService.
T - The result type of the given Futures.U - The fold result type.executorService - An ExecutorService.futures - An iterable of futures.zero - The zero element of the fold.f - The fold operation.Future that will contain the fold result.NullPointerException - if executorService, futures or f is null.static <T> Future<T> fromJavaFuture(Future<T> future)
Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR_SERVICET - Result type of the Futurefuture - A FutureFuture wrapping the result of the Java futureNullPointerException - if future is nullstatic <T> Future<T> fromJavaFuture(ExecutorService executorService, Future<T> future)
Future with the given java.util.concurrent.Future, backed by given ExecutorServiceT - Result type of the FutureexecutorService - An ExecutorServicefuture - A FutureFuture wrapping the result of the Java futureNullPointerException - if executorService or future is nullstatic <T> Future<T> fromTry(Try<? extends T> result)
T - The value type of a successful result.result - The result.Future which contains either a Success or a Failure.NullPointerException - if result is nullstatic <T> Future<T> fromTry(ExecutorService executorService, Try<? extends T> result)
T - The value type of a successful result.executorService - An ExecutorService.result - The result.Future which contains either a Success or a Failure.NullPointerException - if executorService or result is nullstatic <T> Future<T> narrow(Future<? extends T> future)
Future<? extends T> to Future<T>
by performing a type safe-cast. This is eligible because immutable/read-only
collections are covariant.T - Component type of the Future.future - A Future.future instance as narrowed type Future<T>.static <T> Future<T> of(Try.CheckedSupplier<? extends T> computation)
DEFAULT_EXECUTOR_SERVICE.T - Type of the computation result.computation - A computation.NullPointerException - if computation is null.static <T> Future<T> of(ExecutorService executorService, Try.CheckedSupplier<? extends T> computation)
ExecutorService.T - Type of the computation result.executorService - An executor service.computation - A computation.NullPointerException - if one of executorService of computation is null.static <T> Future<T> reduce(Iterable<? extends Future<? extends T>> futures, BiFunction<? super T,? super T,? extends T> f)
The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.
T - The result type of the given Futures.futures - An iterable of futures.f - The reduce operation.Future that will contain the reduce result.NullPointerException - if executorService, futures or f is null.static <T> Future<T> reduce(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, BiFunction<? super T,? super T,? extends T> f)
The resulting Future is backed by the given ExecutorService.
T - The result type of the given Futures.executorService - An ExecutorService.futures - An iterable of futures.f - The reduce operation.Future that will contain the reduce result.NullPointerException - if executorService, futures or f is null.static Future<Void> run(Try.CheckedRunnable unit)
DEFAULT_EXECUTOR_SERVICE.unit - A unit of work.NullPointerException - if unit is null.static Future<Void> run(ExecutorService executorService, Try.CheckedRunnable unit)
ExecutorService.executorService - An executor service.unit - A unit of work.NullPointerException - if one of executorService of unit is null.static <T> Future<Seq<T>> sequence(Iterable<? extends Future<? extends T>> futures)
Futures into a single Future by transforming an
Iterable<Future<? extends T>> into a Future<Seq<T>>.
The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.
// = Future(Success(Seq(1, 2)))
sequence(
List.of(
Future.of(() -> 1),
Future.of(() -> 2)
)
);// = Future(Failure(Error)))
sequence(
List.of(
Future.of(() -> 1),
Future.of(() -> { throw new Error(); }
)
);T - Result type of the futures.futures - An Iterable of Futures.Future of a Seq of results.NullPointerException - if futures is null.static <T> Future<Seq<T>> sequence(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures)
Futures into a single Future by transforming an
Iterable<Future<? extends T>> into a Future<Seq<T>>.
The resulting Future is backed by the given ExecutorService.
T - Result type of the futures.executorService - An ExecutorService.futures - An Iterable of Futures.Future of a Seq of results.NullPointerException - if executorService or futures is null.static <T> Future<T> successful(T result)
Future, backed by the DEFAULT_EXECUTOR_SERVICE.T - The value type of a successful result.result - The result.Future.static <T> Future<T> successful(ExecutorService executorService, T result)
Future, backed by the given ExecutorService.T - The value type of a successful result.executorService - An ExecutorService.result - The result.Future.NullPointerException - if executorService is nullstatic <T,U> Future<Seq<U>> traverse(Iterable<? extends T> values, Function<? super T,? extends Future<? extends U>> mapper)
Future by
transforming an Iterable<? extends T> into a Future<Seq<U>>.
The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.
T - The type of the given values.U - The mapped value type.values - An Iterable of Futures.mapper - A mapper of values to FuturesFuture of a Seq of results.NullPointerException - if values or f is null.static <T,U> Future<Seq<U>> traverse(ExecutorService executorService, Iterable<? extends T> values, Function<? super T,? extends Future<? extends U>> mapper)
Future by
transforming an Iterable<? extends T> into a Future<Seq<U>>.
The resulting Future is backed by the given ExecutorService.
T - The type of the given values.U - The mapped value type.executorService - An ExecutorService.values - An Iterable of values.mapper - A mapper of values to FuturesFuture of a Seq of results.NullPointerException - if executorService, values or f is null.default Future<T> andThen(Consumer<? super Try<T>> action)
An exception, which occurs when performing the given action, is not propagated to the outside.
In other words, subsequent actions are performed based on the value of the original Future.
Example:
// prints Success(1)
Future.of(() -> 1)
.andThen(t -> { throw new Error(""); })
.andThen(System.out::println);
action - A side-effecting action.NullPointerException - if action is nullvoid await()
default boolean cancel()
If the Future was successfully cancelled, the result is a Failure(CancellationException).
false, if this Future is already completed or could not be cancelled, otherwise true.boolean cancel(boolean mayInterruptIfRunning)
If the Future was successfully cancelled, the result is a Failure(CancellationException).
mayInterruptIfRunning - true if a running thread should be interrupted, otherwise a running thread
is allowed to complete its computation.false, if this Future is already completed or could not be cancelled, otherwise true.Future.cancel(boolean)ExecutorService executorService()
ExecutorService used by this Future.ExecutorService.default Future<Throwable> failed()
If this Future succeeds, the failed projection returns a failure containing a NoSuchElementException.
If this Future fails, the failed projection returns a success containing the exception.
default Future<T> fallbackTo(Future<? extends T> that)
that Future is returned, if that is a success. If both Futures fail, the failure
of this Future is returned.
Example:
Future<Integer> future = Future.of(() -> { throw new Error(); });
Future<Integer> that = Future.of(() -> 1);
Future<Integer> result = future.fallbackTo(that);
// prints Some(1)
result.onComplete(System.out::println);
that - A fallback future computationNullPointerException - if that is nulldefault Future<T> filter(Predicate<? super T> predicate)
filterTry(predicate::test.predicate - A predicateFutureNullPointerException - if predicate is nulldefault Future<T> filterTry(Try.CheckedPredicate<? super T> predicate)
Future by calling Try.filterTry(CheckedPredicate).predicate - A checked predicateFutureNullPointerException - if predicate is nulldefault Option<Throwable> getCause()
future.getValue().map(Try::getCause).UnsupportedOperationException - if the Future was successfully completed with a valueOption<Try<T>> getValue()
None, if the Future is not yet completed or was cancelled, otherwise Some(Try).boolean isCompleted()
default boolean isSuccess()
default boolean isFailure()
Future<T> onComplete(Consumer<? super Try<T>> action)
action - An action to be performed when this future is complete.NullPointerException - if action is null.default Future<T> onFailure(Consumer<? super Throwable> action)
Try.Failure. Please note that the
future is also a failure when it was cancelled.action - An action to be performed when this future failed.NullPointerException - if action is null.default Future<T> onSuccess(Consumer<? super T> action)
Try.Success.action - An action to be performed when this future succeeded.NullPointerException - if action is null.default Future<T> recover(Function<? super Throwable,? extends T> f)
Example:
// = "oh!"
Future.of(() -> new Error("oh!")).recover(Throwable::getMessage);
f - A function which takes the exception of a failure and returns a new value.NullPointerException - if f is nulldefault Future<T> recoverWith(Function<? super Throwable,? extends Future<? extends T>> f)
Example:
// = "oh!"
Future.of(() -> { throw new Error("oh!"); }).recoverWith(x -> Future.of(x::getMessage));
f - A function which takes the exception of a failure and returns a new future.NullPointerException - if f is nulldefault <U> U transform(Function<? super Future<T>,? extends U> f)
Future.U - Type of transformation resultf - A transformationUNullPointerException - if f is nulldefault <U> Future<Tuple2<T,U>> zip(Future<? extends U> that)
If this Future failed the result contains this failure. Otherwise the result contains that failure or a tuple of both successful Future results.
U - Result type of thatthat - Another FutureNullPointerException - if that is nulldefault <U> Future<U> flatMapTry(Try.CheckedFunction<? super T,? extends Future<? extends U>> mapper)
default void forEach(Consumer<? super T> action)
action asynchronously hence this Future result becomes available.
The action is not performed, if the result is a failure.default T get()
get in interface Value<T>NoSuchElementException - if the computation unexpectedly failed or was interrupted.default boolean isEmpty()
default boolean isSingleValued()
Future is single-valued.isSingleValued in interface Value<T>truedefault Iterator<T> iterator()
Valuejavaslang.collection.Iterator.default <U> Future<U> map(Function<? super T,? extends U> mapper)
Valuedefault <U> Future<U> mapTry(Try.CheckedFunction<? super T,? extends U> mapper)
default Future<T> peek(Consumer<? super T> action)
Valueaction on the first element if this is an eager implementation.
Performs the given action on all elements (the first immediately, successive deferred),
if this is a lazy implementation.default String stringPrefix()
ValuestringPrefix in interface Value<T>Copyright © 2016. All Rights Reserved.