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

public interface CompletionStage<T>

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

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

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

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

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

• Выполнение одного этапа может быть инициировано завершением одного этапа, или двух этапов, или любого из двух этапов. Зависимости от одного этапа организованы с помощью методов с префиксом then. Те, которые запускаются завершением обоих этапов, могут объединить свои результаты или эффекты, используя соответствующие методы. Те, которые запускаются любым из двух этапов, не гарантируют, какой из результатов или эффектов используется для вычисления зависимого этапа.
• Зависимости между этапами управляют запуском вычислений, но не гарантируют никакой особой последовательности. Кроме того, выполнение вычислений нового этапа может быть организовано тремя способами: по умолчанию, по умолчанию асинхронно (используя методы с суффиксом async, использующие средство асинхронного выполнения по умолчанию этапа), или пользовательским (через предоставленный Executor). Свойства выполнения режимов по умолчанию и async задаются реализациями 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() обеспечивает межсовместимость между различными реализациями этого интерфейса, предоставляя общий тип преобразования.