Class CompletionStages


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

      Fields 
      Modifier and Type Field Description
      static java.lang.Runnable NO_OP_RUNNABLE  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static AggregateCompletionStage<java.lang.Void> aggregateCompletionStage()
      Returns a CompletionStage that also can be composed of many other CompletionStages.
      static <R> AggregateCompletionStage<R> aggregateCompletionStage​(R valueToReturn)
      Same as aggregateCompletionStage() except that when this stage completes normally it will return the value provided.
      static java.util.concurrent.CompletionStage<java.lang.Void> allOf​(java.util.concurrent.CompletionStage<?>... stages)
      Returns a CompletionStage that completes when all of the provided stages complete, either normally or via exception.
      static java.util.concurrent.CompletionStage<java.lang.Void> allOf​(java.util.concurrent.CompletionStage<java.lang.Void> first, java.util.concurrent.CompletionStage<java.lang.Void> second)
      Returns a CompletableStage that completes when both of the provides CompletionStages complete.
      static <V> java.util.concurrent.CompletionStage<V> continueOnExecutor​(java.util.concurrent.CompletionStage<V> delay, java.util.concurrent.Executor continuationExecutor, java.lang.Object traceId)
      When the provided stage is complete, continue the completion chain of the returned CompletionStage on the supplied executor.
      static <T,​U>
      java.util.concurrent.CompletionStage<U>
      handleAndCompose​(java.util.concurrent.CompletionStage<T> stage, java.util.function.BiFunction<T,​java.lang.Throwable,​java.util.concurrent.CompletionStage<U>> handleFunction)
      Extend CompletionStage.thenCompose(Function) to also handle exceptions.
      static java.util.concurrent.CompletionStage<java.lang.Void> ignoreValue​(java.util.concurrent.CompletionStage<?> stage)  
      static boolean isCompletedSuccessfully​(java.util.concurrent.CompletionStage<?> stage)
      Returns if the provided CompletionStage has already completed normally, that is not due to an exception.
      static <R> R join​(java.util.concurrent.CompletionStage<R> stage)
      Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.
      static java.util.concurrent.CompletionStage<java.lang.Void> schedule​(java.lang.Runnable command, java.util.concurrent.ScheduledExecutorService executor, long delay, java.util.concurrent.TimeUnit timeUnit)  
      static <T> java.util.concurrent.CompletionStage<T> schedule​(java.util.concurrent.Callable<T> command, java.util.concurrent.ScheduledExecutorService executor, long delay, java.util.concurrent.TimeUnit timeUnit)  
      static <T> java.util.concurrent.CompletionStage<T> scheduleNonBlocking​(java.util.concurrent.Callable<? extends java.util.concurrent.CompletionStage<T>> command, java.util.concurrent.ScheduledExecutorService executor, long delay, java.util.concurrent.TimeUnit timeUnit)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NO_OP_RUNNABLE

        public static final java.lang.Runnable NO_OP_RUNNABLE
    • Method Detail

      • aggregateCompletionStage

        public static AggregateCompletionStage<java.lang.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​(java.util.concurrent.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​(java.util.concurrent.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:
        java.util.concurrent.CompletionException - if this stage completed exceptionally or a completion computation threw an exception
      • allOf

        public static java.util.concurrent.CompletionStage<java.lang.Void> allOf​(java.util.concurrent.CompletionStage<java.lang.Void> first,
                                                                                 java.util.concurrent.CompletionStage<java.lang.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 java.util.concurrent.CompletionStage<java.lang.Void> allOf​(java.util.concurrent.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> java.util.concurrent.CompletionStage<V> continueOnExecutor​(java.util.concurrent.CompletionStage<V> delay,
                                                                                     java.util.concurrent.Executor continuationExecutor,
                                                                                     java.lang.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
      • handleAndCompose

        public static <T,​U> java.util.concurrent.CompletionStage<U> handleAndCompose​(java.util.concurrent.CompletionStage<T> stage,
                                                                                           java.util.function.BiFunction<T,​java.lang.Throwable,​java.util.concurrent.CompletionStage<U>> handleFunction)
        Extend CompletionStage.thenCompose(Function) to also handle exceptions.
      • schedule

        public static java.util.concurrent.CompletionStage<java.lang.Void> schedule​(java.lang.Runnable command,
                                                                                    java.util.concurrent.ScheduledExecutorService executor,
                                                                                    long delay,
                                                                                    java.util.concurrent.TimeUnit timeUnit)
      • schedule

        public static <T> java.util.concurrent.CompletionStage<T> schedule​(java.util.concurrent.Callable<T> command,
                                                                           java.util.concurrent.ScheduledExecutorService executor,
                                                                           long delay,
                                                                           java.util.concurrent.TimeUnit timeUnit)
      • scheduleNonBlocking

        public static <T> java.util.concurrent.CompletionStage<T> scheduleNonBlocking​(java.util.concurrent.Callable<? extends java.util.concurrent.CompletionStage<T>> command,
                                                                                      java.util.concurrent.ScheduledExecutorService executor,
                                                                                      long delay,
                                                                                      java.util.concurrent.TimeUnit timeUnit)
      • ignoreValue

        public static java.util.concurrent.CompletionStage<java.lang.Void> ignoreValue​(java.util.concurrent.CompletionStage<?> stage)