Class CompletionStages


  • public class CompletionStages
    extends Object
    Utility methods for handling CompletionStage instances.
    Since:
    10.0
    Author:
    wburns
    • Field Detail

      • NO_OP_RUNNABLE

        public static final Runnable NO_OP_RUNNABLE
    • Method Detail

      • aggregateCompletionStage

        public static AggregateCompletionStage<Void> aggregateCompletionStage()
        Returns a CompletionStage that also can be composed of many other CompletionStages. A stage can compose another stage in it by invoking the AggregateCompletionStage.dependsOn(CompletionStage) method passing in the CompletionStage. After all stages this composition stage depend upon have been added, the AggregateCompletionStage.freeze() should be invoked so that the AggregateCompletionStage can finally complete when all of the stages it depends upon complete.

        If any stage this depends upon fails the returned stage will contain the Throwable from one of the stages.

        Returns:
        composed completion stage
      • aggregateCompletionStage

        public static <R> AggregateCompletionStage<R> aggregateCompletionStage​(R valueToReturn)
        Same as aggregateCompletionStage() except that when this stage completes normally it will return the value provided.
        Type Parameters:
        R - the type of the value
        Parameters:
        valueToReturn - value to return to future stage compositions
        Returns:
        composed completion stage that returns the value upon normal completion
      • isCompletedSuccessfully

        public static boolean isCompletedSuccessfully​(CompletionStage<?> stage)
        Returns if the provided CompletionStage has already completed normally, that is not due to an exception.
        Parameters:
        stage - stage to check
        Returns:
        if the stage is completed normally
      • join

        public static <R> R join​(CompletionStage<R> stage)
        Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally. To better conform with the use of common functional forms, if a computation involved in the completion of this CompletionStage threw an exception, this method throws an (unchecked) CompletionException with the underlying exception as its cause.
        Type Parameters:
        R - the type in the stage
        Parameters:
        stage - stage to wait on
        Returns:
        the result value
        Throws:
        CompletionException - if this stage completed exceptionally or a completion computation threw an exception
      • allOf

        public static CompletionStage<Void> allOf​(CompletionStage<Void> first,
                                                  CompletionStage<Void> second)
        Returns a CompletableStage that completes when both of the provides CompletionStages complete. This method may choose to return either of the argument if the other is complete or a new instance completely.
        Parameters:
        first - the first CompletionStage
        second - the second CompletionStage
        Returns:
        a CompletionStage that is complete when both of the given CompletionStages complete
      • allOf

        public static CompletionStage<Void> allOf​(CompletionStage<?>... stages)
        Returns a CompletionStage that completes when all of the provided stages complete, either normally or via exception. If one or more states complete exceptionally the returned CompletionStage will complete with the exception of one of these. If no CompletionStages are provided, returns a CompletionStage completed with the value null.
        Parameters:
        stages - the CompletionStages
        Returns:
        a CompletionStage that is completed when all of the given CompletionStages complete
      • continueOnExecutor

        public static <V> CompletionStage<V> continueOnExecutor​(CompletionStage<V> delay,
                                                                Executor continuationExecutor,
                                                                Object traceId)
        When the provided stage is complete, continue the completion chain of the returned CompletionStage on the supplied executor. If tracing is enabled a trace message is printed using the object as an identifier to more easily track the transition between threads.

        This method is useful when an asynchronous computation completes and you do not want to run further processing on the thread that returned it. An example may be that some blocking operation is performed on a special blocking thread pool. However when the blocking operation completes we will want to continue the processing of that result in a thread pool that is for computational tasks.

        If the supplied stage is already completed when invoking this command, this will return an already completed stage, which means any additional dependent stages will run in the invoking thread.

        Type Parameters:
        V - return value type of the supplied stage
        Parameters:
        delay - the stage to delay the continuation until complete
        continuationExecutor - the executor to run any further completion chain methods on
        traceId - the id to print when tracing is enabled
        Returns:
        a CompletionStage that when depended upon will run any callback in the supplied executor