Класс CompletableFuture<T>

java.lang.Object
- java.util.concurrent.CompletableFuture<T>

Все реализованные интерфейсы:: CompletionStage<T>, Future<T>

public class CompletableFuture<T>
extends Object
implements Future<T>, CompletionStage<T>

A Future that may be explicitly completed (setting its value and status), and may be used as a CompletionStage, supporting dependent functions and actions that trigger upon its completion.

When two or more threads attempt to complete, completeExceptionally, or cancel a CompletableFuture, only one of them succeeds.

In addition to these and related methods for directly manipulating status and results, CompletableFuture implements interface CompletionStage with the following policies:

Actions supplied for dependent completions of non-async methods may be performed by the thread that completes the current CompletableFuture, or by any other caller of a completion method.
All async methods without an explicit Executor argument are performed using the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least two, in which case, a new Thread is created to run each task). To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interface CompletableFuture.AsynchronousCompletionTask.
All CompletionStage methods are implemented independently of other public methods, so the behavior of one method is not impacted by overrides of others in subclasses.

CompletableFuture also implements Future with the following policies:

Since (unlike FutureTask) this class has no direct control over the computation that causes it to be completed, cancellation is treated as just another form of exceptional completion. Method cancel has the same effect as completeExceptionally(new CancellationException()). Method isCompletedExceptionally() can be used to determine if a CompletableFuture completed in any exceptional fashion.
In case of exceptional completion with a CompletionException, methods get() and get(long, TimeUnit) throw an ExecutionException with the same cause as held in the corresponding CompletionException. To simplify usage in most contexts, this class also defines methods join() and getNow(T) that instead throw the CompletionException directly in these cases.

Since:: 1.8

Вложенные классы

Модификатор и тип	Класс и описание
`static interface`	`CompletableFuture.AsynchronousCompletionTask` Маркерный интерфейс, определяющий асинхронные задачи, созданные методами `async`.

Краткое описание конструкторов

Конструктор и описание
`CompletableFuture()` Создает новый незавершенный CompletableFuture.

Краткое описание методов

Модификатор и тип	Метод и описание
`CompletableFuture<Void>`	`acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с соответствующим результатом в качестве аргумента для предоставленной операции.
`CompletableFuture<Void>`	`acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с соответствующим результатом в качестве аргумента для предоставленной операции.
`CompletableFuture<Void>`	`acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с использованием предоставленного исполнителя, с соответствующим результатом в качестве аргумента для предоставленной функции.
`static CompletableFuture<Void>`	`allOf(CompletableFuture<?>... cfs)` Возвращает новый CompletableFuture, который завершается, когда все заданные CompletableFutures завершатся.
`static CompletableFuture<Object>`	`anyOf(CompletableFuture<?>... cfs)` Возвращает новый CompletableFuture, который завершается, когда любой из заданных CompletableFutures завершается, с тем же результатом.
`<U> CompletableFuture<U>`	`applyToEither(CompletionStage<? extends T> other, Function<? super T,U> fn)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с соответствующим результатом в качестве аргумента для предоставленной функции.
`<U> CompletableFuture<U>`	`applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с соответствующим результатом в качестве аргумента для предоставленной функции.
`<U> CompletableFuture<U>`	`applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn, Executor executor)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняется с использованием предоставленного исполнителя, с соответствующим результатом в качестве аргумента для предоставленной функции.
`boolean`	`cancel(boolean mayInterruptIfRunning)` Если ещё не завершён, завершает этот CompletableFuture с `CancellationException`.
`boolean`	`complete(T value)` Если ещё не завершён, устанавливает значение, возвращаемое `get()` и связанными методами, до заданного значения.
`static <U> CompletableFuture<U>`	`completedFuture(U value)` Возвращает новый CompletableFuture, уже завершённый заданным значением.
`boolean`	`completeExceptionally(Throwable ex)` Если ещё не завершён, заставляет вызовы `get()` и связанных методов выбрасывать заданное исключение.
`CompletableFuture<T>`	`exceptionally(Function<Throwable,? extends T> fn)` Возвращает новый CompletableFuture, который завершается, когда этот CompletableFuture завершается, с результатом предоставленной функции исключения, вызывающего завершение этого CompletableFuture при возникновении исключения; в противном случае, если этот CompletableFuture завершается нормально, то возвращаемый CompletableFuture также завершается нормально с тем же значением.
`T`	`get()` Если необходимо, ожидает завершения этого будущего и возвращает его результат.
`T`	`get(long timeout, TimeUnit unit)` Если необходимо, ожидает не более заданного времени завершения этого будущего и возвращает его результат, если он доступен.
`T`	`getNow(T valueIfAbsent)` Возвращает значение результата (или выводит любое возникшее исключение), если завершено, иначе возвращает значение valueIfAbsent.
`int`	`getNumberOfDependents()` Возвращает приблизительное количество CompletableFutures, ожидание завершения которых зависит от завершения этого CompletableFuture.
`<U> CompletableFuture<U>`	`handle(BiFunction<? super T,Throwable,? extends U> fn)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально или с исключением, выполняется с результатом и исключением этого этапа в качестве аргументов предоставленной функции.
`<U> CompletableFuture<U>`	`handleAsync(BiFunction<? super T,Throwable,? extends U> fn)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально или с исключением, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с результатом и исключением этого этапа в качестве аргументов предоставленной функции.
`<U> CompletableFuture<U>`	`handleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально или с исключением, выполняется с использованием предоставленного исполнителя, с результатом и исключением этого этапа в качестве аргументов предоставленной функции.
`boolean`	`isCancelled()` Возвращает `true` если этот CompletableFuture был отменён до завершения его нормальным образом.
`boolean`	`isCompletedExceptionally()` Возвращает `true` если этот CompletableFuture завершился с исключением любым способом.
`boolean`	`isDone()` Возвращает `true` если завершился любым способом: нормально, с исключением или через отмену.
`T`	`join()` Возвращает значение результата при завершении или выбрасывает (непроверенное) исключение, если завершился с исключением.
`void`	`obtrudeException(Throwable ex)` Принудительно заставляет последующие вызовы метода `get()` и связанных методов выбрасывать заданное исключение, независимо от того, завершён ли он уже.
`void`	`obtrudeValue(T value)` Принудительно устанавливает или сбрасывает значение, которое впоследствии возвращается методом `get()` и связанными методами, независимо от того, завершён ли он уже.
`CompletableFuture<Void>`	`runAfterBoth(CompletionStage<?> other, Runnable action)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап оба завершатся нормально, выполняет предоставленную операцию.
`CompletableFuture<Void>`	`runAfterBothAsync(CompletionStage<?> other, Runnable action)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап завершатся нормально, выполняет предоставленную операцию с использованием стандартных асинхронных средств выполнения этого этапа.
`CompletableFuture<Void>`	`runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап завершатся нормально, выполняет предоставленную операцию с использованием предоставленного исполнителя.
`CompletableFuture<Void>`	`runAfterEither(CompletionStage<?> other, Runnable action)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняет предоставленную операцию.
`CompletableFuture<Void>`	`runAfterEitherAsync(CompletionStage<?> other, Runnable action)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняет предоставленную операцию с использованием стандартных асинхронных средств выполнения этого этапа.
`CompletableFuture<Void>`	`runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)` Возвращает новый CompletionStage, который, когда этот или другой заданный этап завершатся нормально, выполняет предоставленную операцию с использованием предоставленного исполнителя.
`static CompletableFuture<Void>`	`runAsync(Runnable runnable)` Возвращает новый CompletableFuture, который асинхронно завершается задачей, выполняемой в `ForkJoinPool.commonPool()` после выполнения предоставленной операции.
`static CompletableFuture<Void>`	`runAsync(Runnable runnable, Executor executor)` Возвращает новый CompletableFuture, который асинхронно завершается задачей, выполняемой в предоставленном исполнителе после выполнения предоставленной операции.
`static <U> CompletableFuture<U>`	`supplyAsync(Supplier<U> supplier)` Возвращает новый CompletableFuture, который асинхронно завершается задачей, выполняемой в `ForkJoinPool.commonPool()`, со значением, полученным при вызове предоставленного Supplier.
`static <U> CompletableFuture<U>`	`supplyAsync(Supplier<U> supplier, Executor executor)` Возвращает новый CompletableFuture, который асинхронно завершается задачей, выполняемой в предоставленном исполнителе, со значением, полученным при вызове предоставленного Supplier.
`CompletableFuture<Void>`	`thenAccept(Consumer<? super T> action)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально, выполняется с результатом этого этапа в качестве аргумента предоставленной операции.
`CompletableFuture<Void>`	`thenAcceptAsync(Consumer<? super T> action)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с результатом этого этапа в качестве аргумента предоставленной операции.
`CompletableFuture<Void>`	`thenAcceptAsync(Consumer<? super T> action, Executor executor)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально, выполняется с использованием предоставленного Executor, с результатом этого этапа в качестве аргумента предоставленной операции.
`<U> CompletableFuture<Void>`	`thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап оба завершатся нормально, выполняется с двумя результатами в качестве аргументов предоставленной операции.
`<U> CompletableFuture<Void>`	`thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап завершатся нормально, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с двумя результатами в качестве аргументов предоставленной операции.
`<U> CompletableFuture<Void>`	`thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)` Возвращает новый CompletionStage, который, когда этот и другой заданный этап завершатся нормально, выполняется с использованием предоставленного исполнителя, с двумя результатами в качестве аргументов предоставленной функции.
`<U> CompletableFuture<U>`	`thenApply(Function<? super T,? extends U> fn)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально, выполняется с результатом этого этапа в качестве аргумента предоставленной функции.
`<U> CompletableFuture<U>`	`thenApplyAsync(Function<? super T,? extends U> fn)` Возвращает новый CompletionStage, который, когда этот этап завершается нормально, выполняется с использованием стандартных асинхронных средств выполнения этого этапа, с результатом этого этапа в качестве аргумента предоставленной функции.

`<U> CompletableFuture<U>`	`thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняется с помощью предоставленного Executor, при этом результат этой фазы используется как аргумент для предоставленной функции.
`<U,V> CompletableFuture<V>`	`thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)` Возвращает новую CompletionStage, которая, когда эта и другая указанная фаза завершаются нормально, выполняется с двумя результатами в качестве аргументов предоставленной функции.
`<U,V> CompletableFuture<V>`	`thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)` Возвращает новую CompletionStage, которая, когда эта и другая указанная фаза завершаются нормально, выполняется с помощью стандартного асинхронного механизма выполнения этой фазы с двумя результатами в качестве аргументов предоставленной функции.
`<U,V> CompletableFuture<V>`	`thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)` Возвращает новую CompletionStage, которая, когда эта и другая указанная фаза завершаются нормально, выполняется с использованием предоставленного исполнителя, с двумя результатами в качестве аргументов предоставленной функции.
`<U> CompletableFuture<U>`	`thenCompose(Function<? super T,? extends CompletionStage<U>> fn)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняется с этой фазой в качестве аргумента предоставленной функции.
`<U> CompletableFuture<U>`	`thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняется с помощью стандартного асинхронного механизма выполнения этой фазы с этой фазой в качестве аргумента предоставленной функции.
`<U> CompletableFuture<U>`	`thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняется с помощью предоставленного Executor, при этом результат этой фазы используется как аргумент для предоставленной функции.
`CompletableFuture<Void>`	`thenRun(Runnable action)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняет заданное действие.
`CompletableFuture<Void>`	`thenRunAsync(Runnable action)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняет заданное действие с использованием стандартного асинхронного механизма выполнения этой фазы.
`CompletableFuture<Void>`	`thenRunAsync(Runnable action, Executor executor)` Возвращает новую CompletionStage, которая, когда эта фаза завершается нормально, выполняет заданное действие с использованием предоставленного Executor.
`CompletableFuture<T>`	`toCompletableFuture()` Возвращает этот CompletableFuture.
`String`	`toString()` Возвращает строку, идентифицирующую этот CompletableFuture, а также его состояние завершения.
`CompletableFuture<T>`	`whenComplete(BiConsumer<? super T,? super Throwable> action)` Возвращает новую CompletionStage с тем же результатом или исключением, что и эта фаза, которая выполняет заданное действие, когда эта фаза завершается.
`CompletableFuture<T>`	`whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)` Возвращает новую CompletionStage с тем же результатом или исключением, что и эта фаза, которая выполняет заданное действие с использованием стандартного асинхронного механизма выполнения этой фазы, когда эта фаза завершается.
`CompletableFuture<T>`	`whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)` Возвращает новую CompletionStage с тем же результатом или исключением, что и эта фаза, которая выполняет заданное действие с использованием предоставленного Executor, когда эта фаза завершается.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Конструкторы

CompletableFuture

public CompletableFuture()

Создаёт новый незавершенный CompletableFuture.

Методы

supplyAsync

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier)

Возвращает новый CompletableFuture, асинхронно завершённый задачей, выполняемой в ForkJoinPool.commonPool(), со значением, полученным путём вызова заданного Supplier.

Параметры типа:: U - тип возвращаемого значения функции
Параметры:: supplier - функция, возвращающая значение, используемое для завершения возвращаемого CompletableFuture
Возвращаемое значение:: новый CompletableFuture

supplyAsync

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier,
                                                   Executor executor)

Возвращает новый CompletableFuture, асинхронно завершённый задачей, выполняемой в заданном исполнителе, со значением, полученным путём вызова заданного Supplier.

Параметры типа:: U - тип возвращаемого значения функции
Параметры:: supplier - функция, возвращающая значение, используемое для завершения возвращаемого CompletableFuture; executor - исполнитель, используемый для асинхронного выполнения
Возвращаемое значение:: новый CompletableFuture

runAsync

public static CompletableFuture<Void> runAsync(Runnable runnable)

Возвращает новый CompletableFuture, асинхронно завершённый задачей, выполняемой в ForkJoinPool.commonPool() после выполнения заданного действия.

Параметры:: runnable - действие, которое выполняется перед завершением возвращаемого CompletableFuture
Возвращаемое значение:: новый CompletableFuture

runAsync

public static CompletableFuture<Void> runAsync(Runnable runnable,
                                               Executor executor)

Возвращает новый CompletableFuture, асинхронно завершённый задачей, выполняемой в заданном исполнителе после выполнения заданного действия.

Параметры:: runnable - действие, которое выполняется перед завершением возвращаемого CompletableFuture; executor - исполнитель, используемый для асинхронного выполнения
Возвращаемое значение:: новый CompletableFuture

completedFuture

public static <U> CompletableFuture<U> completedFuture(U value)

Возвращает новый CompletableFuture, который уже завершён заданным значением.

Параметры типа:: U - тип значения
Параметры:: value - значение
Возвращаемое значение:: завершенный CompletableFuture

isDone

public boolean isDone()

Возвращает true , если завершено каким-либо способом: обычно, по исключению или через отмену.

Определено в:: isDone в интерфейсе Future<T>
Возвращаемое значение:: true если завершено

get

public T get()
      throws InterruptedException,
             ExecutionException

Ждёт, если необходимо, пока этот future не завершится, а затем возвращает его результат.

Определено в:: get в интерфейсе Future<T>
Возвращаемое значение:: значение результата
Исключения:: CancellationException - если этот future был отменён; ExecutionException - если этот future завершился по исключению; InterruptedException - если текущий поток был прерван во время ожидания

get

public T get(long timeout,
             TimeUnit unit)
      throws InterruptedException,
             ExecutionException,
             TimeoutException

Ждёт, если необходимо, не более заданного времени, пока этот future не завершится, а затем возвращает его результат, если он доступен.

Определено в:: get в интерфейсе Future<T>
Параметры:: timeout - максимальное время ожидания; unit - единица измерения времени аргумента таймаута
Возвращаемое значение:: значение результата
Исключения:: CancellationException - если этот future был отменён; ExecutionException - если этот future завершился по исключению; InterruptedException - если текущий поток был прерван во время ожидания; TimeoutException - если ожидание истекло

join

public T join()

Возвращает значение результата при завершении или выбрасывает (непроверенное) исключение, если завершение произошло по исключению. Для лучшего соответствия использованию общих функциональных форм, если вычисление, участвовавшее в завершении этого CompletableFuture, вызвало исключение, этот метод выбрасывает (непроверенное) CompletionException с базовым исключением в качестве причины.

Возвращаемое значение:: значение результата
Исключения:: CancellationException - если вычисление было отменено; CompletionException - если этот future завершился по исключению или вычисление завершения вызвало исключение

getNow

public T getNow(T valueIfAbsent)

Возвращает значение результата (или выбрасывает любое возникшее исключение), если завершено, иначе возвращает заданное valueIfAbsent.

Параметры:: valueIfAbsent - значение, возвращаемое, если не завершено
Возвращаемое значение:: значение результата, если завершено, иначе заданное valueIfAbsent
Исключения:: CancellationException - если вычисление было отменено; CompletionException - если этот future завершился по исключению или вычисление завершения вызвало исключение

complete

public boolean complete(T value)

Если ещё не завершено, устанавливает значение, возвращаемое get() и связанными методами, до заданного значения.

Параметры:: value - значение результата
Возвращаемое значение:: true если это вызов вызвал переход этого CompletableFuture в состояние завершения, иначе false

completeExceptionally

public boolean completeExceptionally(Throwable ex)

Если ещё не завершено, вызывает вызовы get() и связанных методов, чтобы выбросить заданное исключение.

Параметры:: ex - исключение
Возвращаемое значение:: true если этот вызов вызвал переход этого CompletableFuture в состояние завершения, иначе false