Package com.spotify.futures

Class CompletableFutures

java.lang.Object
com.spotify.futures.CompletableFutures
public final class CompletableFutures extends Object
A collection of static utility methods that extend the Java completable future API.
Since:
0.1.0

  • Constructor Details

    • CompletableFutures

      private CompletableFutures()

  • Method Details

    • allAsList

      public static <T> CompletableFuture<List<T>> allAsList(List<? extends CompletionStage<? extends T>> stages)
      Returns a new CompletableFuture which completes to a list of all values of its input stages, if all succeed. The list of results is in the same order as the input stages.

      As soon as any of the given stages complete exceptionally, then the returned future also does so, with a CompletionException holding this exception as its cause.

      If no stages are provided, returns a future holding an empty list.

      Type Parameters:
      T - the common super-type of all of the input stages, that determines the monomorphic type of the output future
      Parameters:
      stages - the stages to combine
      Returns:
      a future that completes to a list of the results of the supplied stages
      Throws:
      NullPointerException - if the stages list or any of its elements are null
      Since:
      0.1.0

    • allAsMap

      public static <U, T> CompletableFuture<Map<U,T>> allAsMap(Map<U,? extends CompletionStage<? extends T>> map)
      Returns a new CompletableFuture which completes to a map of all values of its input stages, if all succeed.

      If any of the given stages complete exceptionally, then the returned future also does so, with a CompletionException holding this exception as its cause.

      If no stages are provided, returns a future holding an empty map.

      Type Parameters:
      U - the common super-type of the keys
      T - the common super-type of all of the input value-stages, that determines the monomorphic type of the output future
      Parameters:
      map - the map of stages to combine
      Returns:
      a future that completes to a map of the results of the supplied keys and value-stages
      Throws:
      NullPointerException - if value-stages or any of its elements are null
      Since:
      0.3.3

    • successfulAsList

      public static <T> CompletableFuture<List<T>> successfulAsList(List<? extends CompletionStage<T>> stages, Function<Throwable,? extends T> defaultValueMapper)
      Returns a new CompletableFuture which completes to a list of values of those input stages that succeeded. The list of results is in the same order as the input stages. For failed stages, the defaultValueMapper will be called, and the value returned from that function will be put in the resulting list.

      If no stages are provided, returns a future holding an empty list.

      Type Parameters:
      T - the common type of all of the input stages, that determines the type of the output future
      Parameters:
      stages - the stages to combine.
      defaultValueMapper - a function that will be called when a future completes exceptionally to provide a default value to place in the resulting list
      Returns:
      a future that completes to a list of the results of the supplied stages
      Throws:
      NullPointerException - if the stages list or any of its elements are null

    • exceptionallyCompletedFuture

      public static <T> CompletableFuture<T> exceptionallyCompletedFuture(Throwable throwable)
      Returns a new CompletableFuture that is already exceptionally completed with the given exception.
      Type Parameters:
      T - an arbitrary type for the returned future; can be anything since the future will be exceptionally completed and thus there will never be a value of type T
      Parameters:
      throwable - the exception
      Returns:
      a future that exceptionally completed with the supplied exception
      Throws:
      NullPointerException - if the supplied throwable is null
      Since:
      0.1.0

    • joinList

      public static <T, S extends CompletionStage<? extends T>> Collector<S,?,CompletableFuture<List<T>>> joinList()
      Collect a stream of CompletionStages into a single future holding a list of the joined entities.

      Usage: 

      
 collection.stream()
     .map(this::someAsyncFunc)
     .collect(joinList())
     .thenApply(this::consumeList)

      The generated CompletableFuture will complete to a list of all entities, in the order they were encountered in the original stream. Similar to CompletableFuture.allOf(CompletableFuture[]), if any of the input futures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.

      Type Parameters:
      T - the common super-type of all of the input stages, that determines the monomorphic type of the output future
      S - the implementation of CompletionStage that the stream contains
      Returns:
      a new CompletableFuture according to the rules outlined in the method description
      Throws:
      NullPointerException - if any future in the stream is null
      Since:
      0.1.0

    • joinMap

      public static <T, K, V> Collector<T,?,CompletableFuture<Map<K,V>>> joinMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends CompletionStage<? extends V>> valueFutureMapper)
      Collect a stream of Objects into a single future holding a Map whose keys are the result of applying the provided mapping function to the input elements, and whose values are the corresponding joined entities.

      Usage: 

      
 collection.stream()
     .collect(joinMap(this::toKey, this::someAsyncFunc))
     .thenApply(this::consumeMap)

      The generated CompletableFuture will complete to a Map of all entities. Similar to CompletableFuture.allOf(CompletableFuture[]), if any of the input futures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.

      Type Parameters:
      T - the type of the input elements
      K - the output type of the key mapping function
      V - the common super-type of the stages returned by the value future mapping function
      Parameters:
      keyMapper - a mapping function to produce keys
      valueFutureMapper - a mapping function to produce futures that will eventually produce the values
      Returns:
      a new CompletableFuture according to the rules outlined in the method description
      Throws:
      NullPointerException - if valueFutureMapper returns null for any input element
      Since:
      0.3.4

    • checkCompleted

      public static void checkCompleted(CompletionStage<?> stage)
      Checks that a stage is completed.
      Parameters:
      stage - the CompletionStage to check
      Throws:
      IllegalStateException - if the stage is not completed
      Since:
      0.1.0

    • getCompleted

      public static <T> T getCompleted(CompletionStage<T> stage)
      Gets the value of a completed stage.
      Type Parameters:
      T - the type of the value that the stage completes into
      Parameters:
      stage - a completed CompletionStage
      Returns:
      the value of the stage if it has one
      Throws:
      IllegalStateException - if the stage is not completed
      Since:
      0.1.0

    • getException

      public static <T> Throwable getException(CompletionStage<T> stage)
      Gets the exception from an exceptionally completed future
      Type Parameters:
      T - the type of the value that the stage completes into
      Parameters:
      stage - an exceptionally completed CompletionStage
      Returns:
      the exception the stage has completed with
      Throws:
      IllegalStateException - if the stage is not completed exceptionally
      CancellationException - if the stage was cancelled
      UnsupportedOperationException - if the CompletionStage does not support the CompletionStage.toCompletableFuture() operation

    • handleCompose

      public static <T, U> CompletionStage<U> handleCompose(CompletionStage<T> stage, BiFunction<? super T,Throwable,? extends CompletionStage<U>> fn)
      Returns a new stage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.

      When this stage is complete, the given function is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments, and the function's result is used to complete the returned stage.

      This differs from CompletionStage.handle(java.util.function.BiFunction) in that the function should return a CompletionStage rather than the value directly.

      Type Parameters:
      T - the type of the input stage's value.
      U - the function's return type
      Parameters:
      stage - the CompletionStage to compose
      fn - the function to use to compute the value of the returned CompletionStage
      Returns:
      the new CompletionStage
      Since:
      0.1.0

    • exceptionallyCompose

      public static <T> CompletionStage<T> exceptionallyCompose(CompletionStage<T> stage, Function<Throwable,? extends CompletionStage<T>> fn)
      Returns a new stage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function. Otherwise, if this stage completes normally, then the returned stage also completes normally with the same value.

      This differs from CompletionStage.exceptionally(java.util.function.Function) in that the function should return a CompletionStage rather than the value directly.

      Type Parameters:
      T - the type of the input stage's value.
      Parameters:
      stage - the CompletionStage to compose
      fn - the function to use to compute the value of the returned CompletionStage if this stage completed exceptionally
      Returns:
      the new CompletionStage
      Since:
      0.1.0

    • supplyAsyncCompose

      public static <U> CompletionStage<U> supplyAsyncCompose(Supplier<CompletionStage<U>> supplier)
      This allows for a stage to be the return type of supplier when using supplyAsync and returns a plain stage.

      This differs from CompletableFuture.supplyAsync(Supplier) in that the function should return a CompletionStage rather than the CompletionStage of a CompletionStage of a value when the return value of the Supplier is a CompletionStage.

      Type Parameters:
      U - the type of the supplied stage's value
      Parameters:
      supplier - a Supplier with a return value of CompletionStage
      Returns:
      the new CompletionStage
      Since:
      0.3.6

    • supplyAsyncCompose

      public static <U> CompletionStage<U> supplyAsyncCompose(Supplier<CompletionStage<U>> supplier, Executor executor)
      This allows for a stage to be the return type of supplier when using supplyAsync and returns a plain stage.

      This differs from CompletableFuture.supplyAsync(Supplier, Executor) in that the function should return a CompletionStage rather than the CompletionStage of a CompletionStage of a value when the return value of the Supplier is a CompletionStage.

      Type Parameters:
      U - the type of the supplied stage's value
      Parameters:
      supplier - a Supplier with a return value of CompletionStage
      executor - a Executor the executor to use for asynchronous execution
      Returns:
      the new CompletionStage
      Since:
      0.3.6

    • dereference

      public static <T> CompletionStage<T> dereference(CompletionStage<? extends CompletionStage<T>> stage)
      This takes a stage of a stage of a value and returns a plain stage of a value.
      Type Parameters:
      T - the type of the inner stage's value.
      Parameters:
      stage - a CompletionStage of a CompletionStage of a value
      Returns:
      the CompletionStage of the value
      Since:
      0.1.0

    • wrap

      private static <T> CompletionStage<CompletionStage<T>> wrap(CompletionStage<T> future)

    • combine

      public static <R, A, B> CompletionStage<R> combine(CompletionStage<A> a, CompletionStage<B> b, BiFunction<A,B,R> function)
      Combines multiple stages by applying a function.
      Type Parameters:
      R - the type of the combining function's return value.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      function - the combining function.
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.1.0

    • combine

      public static <R, A, B, C> CompletionStage<R> combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, Function3<A,B,C,R> function)
      Combines multiple stages by applying a function.
      Type Parameters:
      R - the type of the combining function's return value.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      function - the combining function.
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.1.0

    • combine

      public static <R, A, B, C, D> CompletionStage<R> combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, Function4<A,B,C,D,R> function)
      Combines multiple stages by applying a function.
      Type Parameters:
      R - the type of the combining function's return value.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      function - the combining function.
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.1.0

    • combine

      public static <R, A, B, C, D, E> CompletionStage<R> combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, Function5<A,B,C,D,E,R> function)
      Combines multiple stages by applying a function.
      Type Parameters:
      R - the type of the combining function's return value.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      E - the type of the fifth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      e - the fifth stage.
      function - the combining function.
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.1.0

    • combine

      public static <R, A, B, C, D, E, F> CompletionStage<R> combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, CompletionStage<F> f, Function6<A,B,C,D,E,F,R> function)
      Combines multiple stages by applying a function.
      Type Parameters:
      R - the type of the combining function's return value.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      E - the type of the fifth stage's value.
      F - the type of the sixth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      e - the fifth stage.
      f - the sixth stage.
      function - the combining function.
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.3.2

    • combine

      public static <T> CompletionStage<T> combine(Function<CombinedFutures,T> function, CompletionStage<?>... stages)
      Combines multiple stages by applying a function.
      Type Parameters:
      T - the type of the combining function's return value.
      Parameters:
      function - the combining function.
      stages - the stages to combine
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.4.0

    • combine

      public static <T> CompletionStage<T> combine(Function<CombinedFutures,T> function, List<? extends CompletionStage<?>> stages)
      Combines multiple stages by applying a function.
      Type Parameters:
      T - the type of the combining function's return value.
      Parameters:
      function - the combining function.
      stages - the stages to combine
      Returns:
      a stage that completes into the return value of the supplied function.
      Since:
      0.4.0

    • combineFutures

      public static <R, A, B> CompletionStage<R> combineFutures(CompletionStage<A> a, CompletionStage<B> b, BiFunction<A,B,CompletionStage<R>> function)
      Composes multiple stages into another stage using a function.
      Type Parameters:
      R - the type of the composed CompletionStage.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      function - the combining function.
      Returns:
      a stage that is composed from the input stages using the function.
      Throws:
      UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

    • combineFutures

      public static <R, A, B, C> CompletionStage<R> combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, Function3<A,B,C,CompletionStage<R>> function)
      Composes multiple stages into another stage using a function.
      Type Parameters:
      R - the type of the composed CompletionStage.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      function - the combining function.
      Returns:
      a stage that is composed from the input stages using the function.
      Throws:
      UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

    • combineFutures

      public static <R, A, B, C, D> CompletionStage<R> combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, Function4<A,B,C,D,CompletionStage<R>> function)
      Composes multiple stages into another stage using a function.
      Type Parameters:
      R - the type of the composed CompletionStage.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      function - the combining function.
      Returns:
      a stage that is composed from the input stages using the function.
      Throws:
      UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

    • combineFutures

      public static <R, A, B, C, D, E> CompletionStage<R> combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, Function5<A,B,C,D,E,CompletionStage<R>> function)
      Composes multiple stages into another stage using a function.
      Type Parameters:
      R - the type of the composed CompletionStage.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      E - the type of the fifth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      e - the fifth stage.
      function - the combining function.
      Returns:
      a stage that is composed from the input stages using the function.
      Throws:
      UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

    • combineFutures

      public static <R, A, B, C, D, E, F> CompletionStage<R> combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, CompletionStage<F> f, Function6<A,B,C,D,E,F,CompletionStage<R>> function)
      Composes multiple stages into another stage using a function.
      Type Parameters:
      R - the type of the composed CompletionStage.
      A - the type of the first stage's value.
      B - the type of the second stage's value.
      C - the type of the third stage's value.
      D - the type of the fourth stage's value.
      E - the type of the fifth stage's value.
      F - the type of the sixth stage's value.
      Parameters:
      a - the first stage.
      b - the second stage.
      c - the third stage.
      d - the fourth stage.
      e - the fifth stage.
      f - the sixth stage.
      function - the combining function.
      Returns:
      a stage that is composed from the input stages using the function.
      Throws:
      UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

    • poll

      public static <T> CompletableFuture<T> poll(Supplier<Optional<T>> pollingTask, Duration frequency, ScheduledExecutorService executorService)
      Polls an external resource periodically until it returns a non-empty result.

      The polling task should return Optional.empty() until it becomes available, and then Optional.of(result). If the polling task throws an exception or returns null, that will cause the result future to complete exceptionally.

      Canceling the returned future will cancel the scheduled polling task as well.

      Note that on a ScheduledThreadPoolExecutor the polling task might remain allocated for up to frequency time after completing or being cancelled. If you have lots of polling operations or a long polling frequency, consider setting removeOnCancelPolicy to true. See ScheduledThreadPoolExecutor.setRemoveOnCancelPolicy(boolean).

      Type Parameters:
      T - the type of the result of the polling task, that will be returned when the task succeeds.
      Parameters:
      pollingTask - the polling task
      frequency - the frequency to run the polling task at
      executorService - the executor service to schedule the polling task on
      Returns:
      a future completing to the result of the polling task once that becomes available

    • pollTask

      private static <T> void pollTask(Supplier<Optional<T>> pollingTask, CompletableFuture<T> resultFuture)