Интерфейс CompletionStage<T>

public interface CompletionStage<T>

Этап потенциально асинхронного вычисления, выполняющий действие или вычисляющий значение, когда завершается другой CompletionStage. Этап завершается при завершении вычисления, но это может, в свою очередь, запустить другие зависимые этапы. Функциональность, определенная в этом интерфейсе, имеет всего несколько основных форм, которые расширяются до более широкого набора методов для захвата различных стилей использования:

• Вычисление, выполняемое этапом, может быть выражено как Function, Consumer или Runnable (используя методы с названиями, включающими apply, accept или run соответственно), в зависимости от того, требует ли оно аргументов и/или производит результаты. Например:

   
   stage.thenApply(x -> square(x))
        .thenAccept(x -> System.out.print(x))
        .thenRun(() -> System.out.println());

  Дополнительная форма (compose) позволяет создавать цепочки вычислений из функций, возвращающих CompletionStage.

  Любой аргумент вычисления этапа является результатом вычисления запускающего этапа.

• Выполнение одного этапа может быть запущено завершением одного этапа, или обоих двух этапов, или любого из двух этапов. Зависимости от одного этапа организуются с помощью методов с префиксом then. Те, которые запускаются завершением обоих двух этапов, могут combine свои результаты или эффекты, используя соответствующие методы. Те, которые запускаются любым из двух этапов, не гарантируют, какой из результатов или эффектов используется для вычисления зависимого этапа.
• Зависимости между этапами контролируют запуск вычислений, но не гарантируют никакой особой последовательности. Кроме того, выполнение вычислений нового этапа может быть организовано тремя способами: по умолчанию, по умолчанию асинхронно (используя методы с суффиксом async, которые используют стандартную асинхронную обработку этапа) или пользовательским (через предоставленный Executor). Свойства выполнения режимов по умолчанию и асинхронного режима определяются реализациями CompletionStage, а не этим интерфейсом. Методы с явными аргументами Executor могут иметь произвольные свойства выполнения и могут даже не поддерживать параллельное выполнение, но организованы для обработки таким образом, чтобы учитывать асинхронность.
• Две формы методов (handle и whenComplete) поддерживают безусловное вычисление независимо от того, завершился ли запускающий этап нормально или с исключением. Метод exceptionally поддерживает вычисление только при завершении запускающего этапа с исключением, вычисляя заменяющий результат, аналогично ключевому слову java catch. Во всех остальных случаях, если вычисление этапа завершается внезапно с (непроверяемым) исключением или ошибкой, все зависимые этапы, требующие его завершения, также завершаются с исключением, с CompletionException, содержащим исключение в качестве причины. Если этап зависит от обоих двух этапов, и оба завершаются с исключением, то CompletionException может соответствовать любому из этих исключений. Если этап зависит от любого из двух других, и только один из них завершается с исключением, не гарантируется, завершится ли зависимый этап нормально или с исключением. В случае метода whenComplete, если само предоставленное действие сталкивается с исключением, то этап завершается с этим исключением, за исключением случая, когда исходный этап также завершился с исключением, в этом случае предпочтительным и передаваемым зависимому этапу является исключительное завершение исходного этапа.

Все методы соответствуют вышеуказанным спецификациям запуска, выполнения и исключительного завершения (которые не повторяются в отдельных спецификациях методов). Кроме того, хотя аргументы, используемые для передачи результата завершения (то есть для параметров типа T) для методов, принимающих их, могут быть null, передача null-значения для любого другого параметра приведет к тому, что будет брошено исключение NullPointerException.

Форма метода handle является наиболее общим способом создания продолжения этапа, безусловно выполняющего вычисление, которому передаются результат и исключение (если таковое имеется) запускающего CompletionStage, и вычисляющего произвольный результат. Метод whenComplete аналогичен, но сохраняет результат запускающего этапа вместо вычисления нового. Поскольку нормальный результат этапа может быть null, оба метода должны иметь вычисление, структурированное таким образом:

(result, exception) -> {
   if (exception == null) {
     // triggering stage completed normally
   } else {
     // triggering stage completed exceptionally
   }
 }

Этот интерфейс не определяет методы для первоначального создания, принудительного завершения нормально или с исключением, проверки статуса или результатов завершения или ожидания завершения этапа. Реализации CompletionStage могут предоставлять средства для достижения таких эффектов, если это уместно. Метод toCompletableFuture() обеспечивает межсетевое взаимодействие между различными реализациями этого интерфейса, предоставляя общий тип преобразования.