Package org.forgerock.util.promise

Class Promises

java.lang.Object
org.forgerock.util.promise.Promises
public final class Promises extends Object
Utility methods for creating and composing Promises.

  • Method Details

    • newPromise

      public static <V, E extends Exception> Promise<V,E> newPromise(Supplier<V,E> supplier)
      Execute a task and return the result as a Promise.

      If the task executed successfully, then the Promise is completed with the returned result of the task's execution.

      If the task failed during its execution then the Promise is completed with the caught Exception (or RuntimeException).

      Type Parameters:
      V - The type of the task's result, or Void if the task does not return anything (i.e. it only has side-effects).
      E - The type of the exception thrown by the task if it fails, or NeverThrowsException if the task cannot fail.
      Parameters:
      supplier - The supplier that computes the result or throw an exception in case of failure.
      Returns:
      A Promise representing a completed asynchronous task.

    • executeAsync

      public static <T, E extends Exception> Promise<T,E> executeAsync(Executor executor, Supplier<T,E> supplier)
      Execute the provided supplier through the executor and returns immediately a Promise that will be completed once the supplier has been executed.
      Type Parameters:
      T - The value type
      E - The exception type
      Parameters:
      executor - The executor to use to execute the supplier
      supplier - The block to execute asynchronously through the executor
      Returns:
      A Promise that will be completed once the supplier has been executed.

    • newRuntimeExceptionPromise

      public static <V, E extends Exception> Promise<V,E> newRuntimeExceptionPromise(RuntimeException exception)
      Returns a Promise representing an asynchronous task which has already failed with the provided runtime exception. Attempts to get the result will immediately fail, and any listeners registered against the returned promise will be immediately invoked in the same thread as the caller.
      Type Parameters:
      V - The type of the task's result, or Void if the task does not return anything (i.e. it only has side-effects).
      E - The type of the exception thrown by the task if it fails, or NeverThrowsException if the task cannot fail.
      Parameters:
      exception - The exception indicating why the asynchronous task has failed.
      Returns:
      A Promise representing an asynchronous task which has already failed with the provided exception.

    • newExceptionPromise

      public static <V, E extends Exception> Promise<V,E> newExceptionPromise(E exception)
      Returns a Promise representing an asynchronous task which has already failed with the provided exception. Attempts to get the result will immediately fail, and any listeners registered against the returned promise will be immediately invoked in the same thread as the caller.
      Type Parameters:
      V - The type of the task's result, or Void if the task does not return anything (i.e. it only has side-effects).
      E - The type of the exception thrown by the task if it fails, or NeverThrowsException if the task cannot fail.
      Parameters:
      exception - The exception indicating why the asynchronous task has failed.
      Returns:
      A Promise representing an asynchronous task which has already failed with the provided exception.

    • newResultPromise

      public static <V, E extends Exception> Promise<V,E> newResultPromise(V result)
      Returns a Promise representing an asynchronous task which has already succeeded with the provided result. Attempts to get the result will immediately return the result, and any listeners registered against the returned promise will be immediately invoked in the same thread as the caller.
      Type Parameters:
      V - The type of the task's result, or Void if the task does not return anything (i.e. it only has side-effects).
      E - The type of the exception thrown by the task if it fails, or NeverThrowsException if the task cannot fail.
      Parameters:
      result - The result of the asynchronous task.
      Returns:
      A Promise representing an asynchronous task which has already succeeded with the provided result.

    • newVoidResultPromise

      public static <E extends Exception> Promise<Void,E> newVoidResultPromise()
      Returns a Promise representing an asynchronous task which has already succeeded without result. Any listeners registered against the returned promise will be immediately invoked in the same thread as the caller.
      Type Parameters:
      E - The type of the exception thrown by the task if it fails, or NeverThrowsException if the task cannot fail.
      Returns:
      A Promise representing an asynchronous task which has already succeeded with the provided result.

    • when

      public static <V, E extends Exception> Promise<List<V>,E> when(List<Promise<V,E>> promises)
      Returns a Promise which will be completed once all of the provided promises have succeeded, or as soon as one of them fails.
      Type Parameters:
      V - The type of the tasks' result, or Void if the tasks do not return anything (i.e. they only has side-effects).
      E - The type of the exception thrown by the tasks if they fail, or NeverThrowsException if the tasks cannot fail.
      Parameters:
      promises - The list of tasks to be combined.
      Returns:
      A Promise which will be completed once all of the provided promises have succeeded, or as soon as one of them fails.

    • when

      @SafeVarargs public static <V, E extends Exception> Promise<List<V>,E> when(Promise<V,E>... promises)
      Returns a Promise which will be completed once all of the provided promises have succeeded, or as soon as one of them fails.
      Type Parameters:
      V - The type of the tasks' result, or Void if the tasks do not return anything (i.e. they only has side-effects).
      E - The type of the exception thrown by the tasks if they fail, or NeverThrowsException if the tasks cannot fail.
      Parameters:
      promises - The list of tasks to be combined.
      Returns:
      A Promise which will be completed once all of the provided promises have succeeded, or as soon as one of them has thrown an exception.

    • anyResultFrom

      public static <V, E extends Exception> Optional<Promise<V,E>> anyResultFrom(Stream<Promise<V,E>> promises)
      Takes a stream of promises that may not yet be resolved and returns a resolved value from them, or if none resolve to a result, the failure from the last.
      Type Parameters:
      V - The type of promise value.
      E - The type of promise exception.
      Parameters:
      promises - The promises.
      Returns:
      A promise that will either have a completed value from one of the provided promsies, or the failure from the last promise to complete, or an empty optional if there were no promises.

    • iterateOver

      public static <V, E extends Exception> Promises.IterateOverBuilder<V,E> iterateOver(Stream<AsyncSupplier<V,E>> promiseStream)
      Configure an Promises.IterateOverBuilder to iterate over a Stream of promise suppliers in search of the first to match a given predicate.
      Type Parameters:
      V - The type of promise's Optional value
      E - The type of promise exception
      Parameters:
      promiseStream - Stream of promise suppliers
      Returns:
      An Promises.IterateOverBuilder to be configured for use
      See Also:

    • iterateOver

      public static <V, E extends Exception> Promises.IterateOverBuilder<V,E> iterateOver(Iterable<AsyncSupplier<V,E>> promiseIterable)
      Configure an Promises.IterateOverBuilder to iterate over an Iterable of promise suppliers in search of the first to match a given predicate.
      Type Parameters:
      V - The type of promise's Optional value
      E - The type of promise exception
      Parameters:
      promiseIterable - Iterable of promise suppliers
      Returns:
      An Promises.IterateOverBuilder to be configured for use
      See Also:

    • allDone

      public static Promise<Void,NeverThrowsException> allDone(Collection<Promise<?,?>> promises)
      Returns a Promise which will be completed successfully once all the provided promises have completed (successfully or not, including runtime exceptions).
      Parameters:
      promises - The collection of tasks to be combined.
      Returns:
      A Promise which will be completed successfully once all the provided promises have completed (successfully or not).

    • allDone

      public static <V> Promise<V,NeverThrowsException> allDone(Collection<Promise<?,?>> promises, V context)
      Returns a Promise which will be completed successfully once all the provided promises have completed (successfully or not, including runtime exceptions), returning back the context parameter.
      Type Parameters:
      V - The type of the promise' result (can be Void).
      Parameters:
      promises - The collection of tasks to be combined.
      context - Instance passed back to the resulting promise on completion (can be null)
      Returns:
      A Promise which will be completed successfully once all of the provided promises have completed (successfully or not).

    • join

      @SafeVarargs public static Promise<Promises.Results,Exception> join(Promise<?,? extends Exception>... promises)
      Returns a Promise which will be completed once all the provided promises have succeeded, or as soon as one of them fails.

      On successful completion, an immutable Promises.Results instance containing all respective results of the joined promises (in the same order) is provided.

      Parameters:
      promises - The list of tasks to be combined.
      Returns:
      A Promise which will be completed once all of the provided promises have succeeded, or as soon as one of them has thrown an exception.

    • join

      public static Promise<Promises.Results,Exception> join(List<Promise<?,? extends Exception>> promises)
      Returns a Promise which will be completed once all the provided promises have succeeded, or as soon as one of them fails.

      On successful completion, an immutable Promises.Results instance containing all respective results of the joined promises (in the same order) is provided.

      Parameters:
      promises - The list of tasks to be combined.
      Returns:
      A Promise which will be completed once all the provided promises have succeeded, or as soon as one of them has thrown an exception.