Package org.forgerock.util.promise

Interface Promise<V,E extends Exception>

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.
All Known Subinterfaces:
LdapPromise<S>
All Known Implementing Classes:
PromiseImpl
public interface Promise<V,E extends Exception>
A Promise represents the result of an asynchronous task.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    cancel(boolean mayInterruptIfRunning)
    Attempts to cancel the asynchronous task associated with this Promise.
    V
    get()
    Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an ExecutionException containing the cause of the failure.
    V
    get(long timeout, TimeUnit unit)
    Waits if necessary for at most the given time for this Promise to complete, and then returns the result if it completed successfully, or throws an ExecutionException containing the cause of the failure.
    V
    getOrThrow()
    Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.
    V
    getOrThrow(long timeout, TimeUnit unit)
    Waits if necessary for at most the given time for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.
    default V
    getOrThrowIfInterrupted()
    Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.
    V
    getOrThrowUninterruptibly()
    Deprecated.
    Since 25.0.0.
    V
    getOrThrowUninterruptibly(long timeout, TimeUnit unit)
    Deprecated.
    Since 25.0.0.
    boolean
    isCancelled()
    Returns true if this Promise was cancelled before it completed normally.
    boolean
    isDone()
    Returns true if this Promise has completed.
    boolean
    isResult()
    Returns true if this Promise has completed and contains a value.
    <VOUT> Promise<VOUT,E>
    then(Function<? super V,VOUT,E> onResult)
    Submits the provided function for execution once this Promise has completed with a result, and returns a new Promise representing the outcome of the function.
    <VOUT, EOUT extends Exception>
    Promise<VOUT,EOUT>
    then(Function<? super V,VOUT,EOUT> onResult, Function<? super E,VOUT,EOUT> onException)
    Submits the provided functions for execution once this Promise has completed (with a result or an exception), and returns a new Promise representing the outcome of the invoked function.
    <VOUT, EOUT extends Exception>
    Promise<VOUT,EOUT>
    then(Function<? super V,VOUT,EOUT> onResult, Function<? super E,VOUT,EOUT> onException, Function<? super RuntimeException,VOUT,EOUT> onRuntimeException)
    Submits the provided functions for execution once this Promise has completed (with a result or an exception or a RuntimeException), and returns a new Promise representing the outcome of the invoked function.
    Promise<V,E>
    thenAlways(Runnable onResultOrException)
    Submits the provided runnable for execution once this Promise has completed, and regardless of whether it has a result or an exception.
    <VOUT> Promise<VOUT,E>
    thenAsync(AsyncFunction<? super V,VOUT,E> onResult)
    Submits the provided asynchronous function for execution once this Promise has completed with a result, and returns a new Promise representing the outcome of the function.
    <VOUT, EOUT extends Exception>
    Promise<VOUT,EOUT>
    thenAsync(AsyncFunction<? super V,VOUT,EOUT> onResult, AsyncFunction<? super E,VOUT,EOUT> onException)
    Submits the provided asynchronous functions for execution once this Promise has completed, and returns a new Promise representing the outcome of the invoked function.
    <VOUT, EOUT extends Exception>
    Promise<VOUT,EOUT>
    thenAsync(AsyncFunction<? super V,VOUT,EOUT> onResult, AsyncFunction<? super E,VOUT,EOUT> onException, AsyncFunction<? super RuntimeException,VOUT,EOUT> onRuntimeException)
    Submits the provided asynchronous functions for execution once this Promise has completed, and returns a new Promise representing the outcome of the invoked function.
    <EOUT extends Exception>
    Promise<V,EOUT>
    thenCatch(Function<? super E,V,EOUT> onException)
    Submits the provided function for execution once this Promise has not completed with a result (has completed with an exception), and returns a new Promise representing the outcome of the function.
    <EOUT extends Exception>
    Promise<V,EOUT>
    thenCatchAsync(AsyncFunction<? super E,V,EOUT> onException)
    Submits the provided asynchronous function for execution once this Promise has completed with an exception, and returns a new Promise representing the outcome of the function.
    Promise<V,E>
    thenCatchRuntimeException(Function<? super RuntimeException,V,E> onRuntimeException)
    Submits the provided function for execution once this Promise has not completed with a result nor with an exception but with a RuntimeException, and returns a new Promise representing the outcome of the function.
    Promise<V,E>
    thenCatchRuntimeExceptionAsync(AsyncFunction<? super RuntimeException,V,E> onRuntimeException)
    Submits the provided asynchronous function for execution once this Promise has completed with a RuntimeException, and returns a new Promise representing the outcome of the function.
    default Promise<Void,E>
    thenDiscardResult()
    Discards the promise result if this Promise has completed with a result.
    Promise<V,E>
    thenFinally(Runnable onResultOrException)
    Submits the provided runnable for execution once this Promise has completed, and regardless of whether of its outcome.
    <T extends ResultHandler<? super V> & ExceptionHandler<? super E> & RuntimeExceptionHandler>
    Promise<V,E>
    thenOnCompletion(T handler)
    Registers the provided completion handler for notification for all completion cases of this Promise.
    Promise<V,E>
    thenOnException(ExceptionHandler<? super E> onException)
    Registers the provided completion handler for notification if this Promise cannot be completed due to an exception.
    Promise<V,E>
    thenOnResult(ResultHandler<? super V> onResult)
    Registers the provided completion handler for notification once this Promise has completed with a result.
    Promise<V,E>
    thenOnResultOrException(Runnable onResultOrException)
    Submits the provided runnable for execution once this Promise has completed, and regardless of whether it has a result or an exception.
    Promise<V,E>
    thenOnResultOrException(ResultHandler<? super V> onResult, ExceptionHandler<? super E> onException)
    Registers the provided completion handlers for notification once this Promise has completed (with a result or an exception).
    Promise<V,E>
    thenOnRuntimeException(RuntimeExceptionHandler onRuntimeException)
    Registers the provided completion handler for notification if this Promise cannot be completed due to an runtime exception.

  • Method Details

    • cancel

      boolean cancel(boolean mayInterruptIfRunning)
      Attempts to cancel the asynchronous task associated with this Promise. Cancellation will fail if this Promise has already completed or has already been cancelled. If successful, then cancellation will complete this Promise with an appropriate exception and notify any registered functions and completion handlers.

      After this method returns, subsequent calls to isDone() will always return true. Subsequent calls to isCancelled() will always return true if this method returned true.

      Parameters:
      mayInterruptIfRunning - true if the thread executing executing the response handler should be interrupted; otherwise, in-progress response handlers are allowed to complete.
      Returns:
      false if Promise could not be cancelled, typically because it has already completed normally; true otherwise.

    • get

      V get() throws ExecutionException, InterruptedException
      Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an ExecutionException containing the cause of the failure.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      ExecutionException - If this Promise was cancelled or did not complete successfully. The ExecutionException will contain the cause of the failure.
      InterruptedException - If the current thread was interrupted while waiting.

    • get

      V get(long timeout, TimeUnit unit) throws ExecutionException, TimeoutException, InterruptedException
      Waits if necessary for at most the given time for this Promise to complete, and then returns the result if it completed successfully, or throws an ExecutionException containing the cause of the failure.
      Parameters:
      timeout - The maximum time to wait.
      unit - The time unit of the timeout argument.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      ExecutionException - If this Promise was cancelled or did not complete successfully. The ExecutionException will contain the cause of the failure.
      TimeoutException - If the wait timed out.
      InterruptedException - If the current thread was interrupted while waiting.

    • getOrThrow

      V getOrThrow() throws InterruptedException, E
      Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      E - If this Promise was cancelled or did not complete successfully.
      InterruptedException - If the current thread was interrupted while waiting.

    • getOrThrowIfInterrupted

      default V getOrThrowIfInterrupted() throws E
      Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure. If the thread is interrupted while waiting for the result then the thread's interrupted status is reset and a RuntimeException is thrown.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      E - If this Promise was cancelled or did not complete successfully.
      RuntimeException - If the caller's thread is interrupted while waiting for the promise to resolve.

    • getOrThrow

      V getOrThrow(long timeout, TimeUnit unit) throws InterruptedException, E, TimeoutException
      Waits if necessary for at most the given time for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.
      Parameters:
      timeout - The maximum time to wait.
      unit - The time unit of the timeout argument.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      E - If this Promise was cancelled or did not complete successfully.
      TimeoutException - If the wait timed out.
      InterruptedException - If the current thread was interrupted while waiting.

    • getOrThrowUninterruptibly

      @Deprecated V getOrThrowUninterruptibly() throws E
      Deprecated.
      Since 25.0.0. Prefer using getOrThrow() and handle properly the InterruptedException in the calling code, or use getOrThrowIfInterrupted().
      Waits if necessary for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.

      This method is similar to getOrThrow() except that it will ignore thread interrupts. When this method returns the status of the current thread will be interrupted if an interrupt was received while waiting.

      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      E - If this Promise was cancelled or did not complete successfully.

    • getOrThrowUninterruptibly

      @Deprecated V getOrThrowUninterruptibly(long timeout, TimeUnit unit) throws E, TimeoutException
      Deprecated.
      Since 25.0.0. Prefer using get(long, TimeUnit) and handle properly the InterruptedException in the calling code, or use getOrThrowIfInterrupted().
      Waits if necessary for at most the given time for this Promise to complete, and then returns the result if it completed successfully, or throws an exception representing the cause of the failure.

      This method is similar to getOrThrow(long, TimeUnit) except that it will ignore thread interrupts. When this method returns the status of the current thread will be interrupted if an interrupt was received while waiting.

      Parameters:
      timeout - The maximum time to wait.
      unit - The time unit of the timeout argument.
      Returns:
      The result, but only if this Promise completed successfully.
      Throws:
      E - If this Promise was cancelled or did not complete successfully.
      TimeoutException - If the wait timed out.

    • isCancelled

      boolean isCancelled()
      Returns true if this Promise was cancelled before it completed normally.
      Returns:
      true if this Promise was cancelled before it completed normally, otherwise false.

    • isDone

      boolean isDone()
      Returns true if this Promise has completed.

      Completion may be due to normal termination, an exception, or cancellation. In all of these cases, this method will return true.

      Returns:
      true if this Promise has completed, otherwise false.

    • isResult

      boolean isResult()
      Returns true if this Promise has completed and contains a value.
      Returns:
      true if this Promise has completed with a value.

    • thenOnException

      Promise<V,E> thenOnException(ExceptionHandler<? super E> onException)
      Registers the provided completion handler for notification if this Promise cannot be completed due to an exception. If this Promise completes with a result then the completion handler will not be notified.

      This method can be used for asynchronous completion notification.

      Parameters:
      onException - The completion handler which will be notified upon failure completion of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • thenOnResult

      Promise<V,E> thenOnResult(ResultHandler<? super V> onResult)
      Registers the provided completion handler for notification once this Promise has completed with a result. If this Promise completes with an exception then the completion handler will not be notified.

      This method can be used for asynchronous completion notification and is equivalent to then(Function).

      Parameters:
      onResult - The completion handler which will be notified upon successful completion of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • thenOnResultOrException

      Promise<V,E> thenOnResultOrException(ResultHandler<? super V> onResult, ExceptionHandler<? super E> onException)
      Registers the provided completion handlers for notification once this Promise has completed (with a result or an exception). If this Promise completes with a result then onResult will be notified with the result, otherwise onException will be notified with the exception that occurred.

      This method can be used for asynchronous completion notification.

      Parameters:
      onResult - The completion handler which will be notified upon completion with a result of this Promise.
      onException - The completion handler which will be notified upon failure of this Promise.
      Returns:
      A Promise that is guaranted to be completed once the provided callback has been executed.

    • thenOnResultOrException

      Promise<V,E> thenOnResultOrException(Runnable onResultOrException)
      Submits the provided runnable for execution once this Promise has completed, and regardless of whether it has a result or an exception.

      This method can be used for resource cleanup after a series of asynchronous tasks have completed. More specifically, this method should be used in a similar manner to finally statements in try...catch expressions.

      This method is equivalent to thenAlways(Runnable).

      Parameters:
      onResultOrException - The runnable which will be notified regardless of the final outcome of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • then

      <VOUT> Promise<VOUT,E> then(Function<? super V,VOUT,E> onResult)
      Submits the provided function for execution once this Promise has completed with a result, and returns a new Promise representing the outcome of the function. If this Promise does not complete with a result then the function will not be invoked and the exception will be forwarded to the returned Promise.

      This method can be used for transforming the result of an asynchronous task.

      Type Parameters:
      VOUT - The type of the function's result, or Void if the function does not return anything (i.e. it only has side-effects). Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The function which will be executed upon successful completion of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • thenCatch

      <EOUT extends Exception> Promise<V,EOUT> thenCatch(Function<? super E,V,EOUT> onException)
      Submits the provided function for execution once this Promise has not completed with a result (has completed with an exception), and returns a new Promise representing the outcome of the function. If this Promise completes with a result then the function will not be invoked and the result notification will be forwarded to the returned Promise.

      This method can be used for transforming the result of an asynchronous task.

      Type Parameters:
      EOUT - The type of the exception thrown by the function if it fails, or NeverThrowsException if it cannot fails. Note that the type may be different to the type of this Promise.
      Parameters:
      onException - The function which will be executed upon failure completion of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • thenCatchRuntimeException

      Promise<V,E> thenCatchRuntimeException(Function<? super RuntimeException,V,E> onRuntimeException)
      Submits the provided function for execution once this Promise has not completed with a result nor with an exception but with a RuntimeException, and returns a new Promise representing the outcome of the function. If this Promise completes with a result or an exception then the function will not be invoked and the result notification will be forwarded to the returned Promise.

      This method can be used for transforming the result of an asynchronous task.

      Parameters:
      onRuntimeException - The function which will be executed upon failure completion of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • thenCatchRuntimeExceptionAsync

      Promise<V,E> thenCatchRuntimeExceptionAsync(AsyncFunction<? super RuntimeException,V,E> onRuntimeException)
      Submits the provided asynchronous function for execution once this Promise has completed with a RuntimeException, and returns a new Promise representing the outcome of the function. If this Promise completes with a result or the typed exception then the completion asynchronous function will not be called.

      This method may be used for chaining together a series of asynchronous tasks.

      Parameters:
      onRuntimeException - The asynchronous function which will be executed upon failure completion with a RuntimeException of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • then

      <VOUT, EOUT extends Exception> Promise<VOUT,EOUT> then(Function<? super V,VOUT,EOUT> onResult, Function<? super E,VOUT,EOUT> onException)
      Submits the provided functions for execution once this Promise has completed (with a result or an exception), and returns a new Promise representing the outcome of the invoked function. If this Promise completes with a result then onResult will be invoked with the result, otherwise onException will be invoked with the exception that occurred.

      This method can be used for transforming the outcome of an asynchronous task.

      Type Parameters:
      VOUT - The type of the functions' result, or Void if the functions do not return anything (i.e. they only have side-effects). Note that the type may be different to the type of this Promise.
      EOUT - The type of the exception thrown by the functions if they fail, or NeverThrowsException if they cannot fail. Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The function which will be executed upon successful completion of this Promise.
      onException - The function which will be executed upon failure of this Promise.
      Returns:
      A new Promise representing the outcome of the invoked function.

    • then

      <VOUT, EOUT extends Exception> Promise<VOUT,EOUT> then(Function<? super V,VOUT,EOUT> onResult, Function<? super E,VOUT,EOUT> onException, Function<? super RuntimeException,VOUT,EOUT> onRuntimeException)
      Submits the provided functions for execution once this Promise has completed (with a result or an exception or a RuntimeException), and returns a new Promise representing the outcome of the invoked function. If this Promise completes with a result then onResult will be invoked with the result, with a RuntimeException then onRuntimeException will be invoked with the runtime exception that occurred, otherwise onException will be invoked with the exception that occurred.

      This method can be used for transforming the outcome of an asynchronous task.

      Type Parameters:
      VOUT - The type of the functions' result, or Void if the functions do not return anything (i.e. they only have side-effects). Note that the type may be different to the type of this Promise.
      EOUT - The type of the exception thrown by the functions if they fail, or NeverThrowsException if they cannot fail. Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The function which will be executed upon successful completion of this Promise.
      onException - The function which will be executed upon failure of this Promise.
      onRuntimeException - The function which will be executed upon failure with RuntimeException of this Promise.
      Returns:
      A new Promise representing the outcome of the invoked function.

    • thenDiscardResult

      default Promise<Void,E> thenDiscardResult()
      Discards the promise result if this Promise has completed with a result.

      This method can be used when only a completion signal is expected from an asynchronous operation.

      It is mainly useful when an API need to return a completion signal (denoted by Promise<Void, ... >) from another promise that already has a specific type.

      Returns:
      A new Promise representing the outcome of the invoked function.

    • thenAlways

      Promise<V,E> thenAlways(Runnable onResultOrException)
      Submits the provided runnable for execution once this Promise has completed, and regardless of whether it has a result or an exception.

      This method can be used for resource cleanup after a series of asynchronous tasks have completed. More specifically, this method should be used in a similar manner to finally statements in try...catch expressions.

      This method is equivalent to thenOnResultOrException(Runnable).

      Parameters:
      onResultOrException - The runnable which will be notified regardless of the final outcome of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • thenFinally

      Promise<V,E> thenFinally(Runnable onResultOrException)
      Submits the provided runnable for execution once this Promise has completed, and regardless of whether of its outcome.

      This method can be used for resource cleanup after a series of asynchronous tasks have completed. More specifically, this method should be used in a similar manner to finally statements in try...catch expressions.

      This method is equivalent to thenAlways(Runnable).

      Parameters:
      onResultOrException - The runnable which will be notified regardless of the final outcome of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • thenAsync

      <VOUT> Promise<VOUT,E> thenAsync(AsyncFunction<? super V,VOUT,E> onResult)
      Submits the provided asynchronous function for execution once this Promise has completed with a result, and returns a new Promise representing the outcome of the function. If this Promise complete with an exception then the function will not be invoked and the error will be forwarded to the returned Promise.

      This method may be used for chaining together a series of asynchronous tasks.

      Type Parameters:
      VOUT - The type of the function's result, or Void if the function does not return anything (i.e. it only has side-effects). Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The asynchronous function which will be executed upon successful completion of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • thenCatchAsync

      <EOUT extends Exception> Promise<V,EOUT> thenCatchAsync(AsyncFunction<? super E,V,EOUT> onException)
      Submits the provided asynchronous function for execution once this Promise has completed with an exception, and returns a new Promise representing the outcome of the function. If this Promise completes with a result then the function will not be invoked and the exception will be forwarded to the returned Promise.

      This method may be used for chaining together a series of asynchronous tasks.

      Type Parameters:
      EOUT - The type of the exception thrown by the function if it fails, or NeverThrowsException if it cannot fails. Note that the type may be different to the type of this Promise.
      Parameters:
      onException - The asynchronous function which will be executed upon failure completion of this Promise.
      Returns:
      A new Promise representing the outcome of the function.

    • thenAsync

      <VOUT, EOUT extends Exception> Promise<VOUT,EOUT> thenAsync(AsyncFunction<? super V,VOUT,EOUT> onResult, AsyncFunction<? super E,VOUT,EOUT> onException)
      Submits the provided asynchronous functions for execution once this Promise has completed, and returns a new Promise representing the outcome of the invoked function. If this Promise completes with a result then onResult will be invoked with the result, otherwise onException will be invoked with the exception that occurred.

      This method may be used for chaining together a series of asynchronous tasks.

      Type Parameters:
      VOUT - The type of the functions' result, or Void if the functions do not return anything (i.e. they only have side-effects). Note that the type may be different to the type of this Promise.
      EOUT - The type of the exception thrown by the functions if they fail, or NeverThrowsException if they cannot fail. Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The asynchronous function which will be executed upon successful completion of this Promise.
      onException - The asynchronous function which will be executed upon failure of this Promise.
      Returns:
      A new Promise representing the outcome of the invoked function.

    • thenAsync

      <VOUT, EOUT extends Exception> Promise<VOUT,EOUT> thenAsync(AsyncFunction<? super V,VOUT,EOUT> onResult, AsyncFunction<? super E,VOUT,EOUT> onException, AsyncFunction<? super RuntimeException,VOUT,EOUT> onRuntimeException)
      Submits the provided asynchronous functions for execution once this Promise has completed, and returns a new Promise representing the outcome of the invoked function. If this Promise completes with a result then onResult will be invoked with the result, otherwise onException will be invoked with the exception that occurred, or onRuntimeException will be invoked with the runtime exception that occurred.

      This method may be used for chaining together a series of asynchronous tasks.

      Type Parameters:
      VOUT - The type of the functions' result, or Void if the functions do not return anything (i.e. they only have side-effects). Note that the type may be different to the type of this Promise.
      EOUT - The type of the exception thrown by the functions if they fail, or NeverThrowsException if they cannot fail. Note that the type may be different to the type of this Promise.
      Parameters:
      onResult - The asynchronous function which will be executed upon successful completion of this Promise.
      onException - The asynchronous function which will be executed upon failure of this Promise.
      onRuntimeException - The asynchronous function which will be executed upon failure with RuntimeException of this Promise.
      Returns:
      A new Promise representing the outcome of the invoked function.

    • thenOnRuntimeException

      Promise<V,E> thenOnRuntimeException(RuntimeExceptionHandler onRuntimeException)
      Registers the provided completion handler for notification if this Promise cannot be completed due to an runtime exception. If this Promise completes with a result or the typed exception then the completion handler will not be notified.

      This method can be used for asynchronous completion notification.

      Parameters:
      onRuntimeException - The completion handler which will be notified upon an uncaught runtime exception completion of this Promise.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.

    • thenOnCompletion

      <T extends ResultHandler<? super V> & ExceptionHandler<? super E> & RuntimeExceptionHandler> Promise<V,E> thenOnCompletion(T handler)
      Registers the provided completion handler for notification for all completion cases of this Promise.

      This method can be used for asynchronous completion notification.

      Type Parameters:
      T - the composite type of the handler for handling all completion cases
      Parameters:
      handler - The handler that will be called once this Promise is completed.
      Returns:
      A Promise that is guaranteed to be completed once the provided callback has been executed.