Package io.activej.promise

Interface Promise<T>

All Superinterfaces:
AsyncComputation<T>
All Known Implementing Classes:
AbstractPromise, AbstractPromise.EitherPromise, AbstractPromise.PromiseBoth, AbstractPromise.PromiseCombine, CompleteExceptionallyPromise, CompleteNullPromise, CompletePromise, CompleteResultPromise, NextPromise, SettablePromise
public interface Promise<T> extends AsyncComputation<T>
Replacement of default Java CompletionStage interface with optimized design, which allows handling different scenarios more efficiently.

Each promise represents some sort of operations executed after the previous Promise completes.

Promise can complete either successfully with a result which will be wrapped inside the Promise or exceptionally, returning a new CompletePromise or CompleteExceptionallyPromise respectively.

SettablePromise allows to create a root for chain of Promises.

See Also:

  • Method Details

    • complete

      static Promise<Void> complete()
      Creates successfully completed Promise

    • of

      static <T> Promise<T> of(@Nullable T value)
      Creates successfully completed Promise.
      Parameters:
      value - result of Promise. If value is null, returns CompleteNullPromise, otherwise CompleteResultPromise

    • ofException

      static <T> Promise<T> ofException(Exception e)
      Creates an exceptionally completed Promise.
      Parameters:
      e - Exception

    • ofCallback

      static <T> Promise<T> ofCallback(CallbackSupplierEx<T> fn)
      Creates and returns a new SettablePromise that is accepted by the provided ConsumerEx of SettablePromise

    • ofCallback

      static <T, R> Promise<R> ofCallback(T value, CallbackFunctionEx<? super T,R> fn)

    • ofCallback

      static <T, R> Promise<R> ofCallback(T value, @Nullable @Nullable Exception exception, CallbackBiFunctionEx<? super T,@Nullable Exception,R> fn)

    • ofCallback

      static <T, R> Promise<R> ofCallback(T value, @Nullable @Nullable Exception exception, CallbackFunctionEx<? super T,R> fn, CallbackFunctionEx<Exception,R> fnException)

    • ofOptional

      static <T> Promise<T> ofOptional(Optional<T> optional)
      Creates a new Promise of the given value
      See Also:

    • ofOptional

      static <T> Promise<T> ofOptional(Optional<T> optional, Supplier<? extends Exception> errorSupplier)
      Creates a new Promise of the given value. If Optional doesn't equal null, a Promise of optional contained value will be created. Otherwise, a Promise with errorSupplier exception will be created.
      Returns:
      CompletePromise if the optional value doesn't equal null, otherwise CompleteExceptionallyPromise with errorSupplier exception.

    • of

      static <T> Promise<T> of(@Nullable T value, @Nullable @Nullable Exception e)
      Creates a completed Promise from T value and Exception e parameters, any of them can be null. Useful for then(io.activej.async.function.AsyncSupplierEx<U>) passthroughs (for example, when mapping specific exceptions).
      Parameters:
      value - value to wrap when exception is null
      e - possibly-null exception, determines type of promise completion

    • ofTry

      static <T> Promise<T> ofTry(io.activej.common.collection.Try<T> t)
      Returns a new CompletePromise or CompleteExceptionallyPromise based on the provided Try.

    • ofFuture

      static <T> Promise<T> ofFuture(CompletableFuture<? extends T> future)
      Creates a Promise wrapper around default Java CompletableFuture and runs it immediately.
      Returns:
      a new Promise with a result of the given future

    • ofCompletionStage

      static <T> Promise<T> ofCompletionStage(CompletionStage<? extends T> completionStage)
      Wraps Java CompletionStage in a Promise, running it in current reactor.
      Parameters:
      completionStage - completion stage itself
      Returns:
      result of the given completionStage wrapped in a Promise

    • ofFuture

      static <T> Promise<T> ofFuture(Executor executor, Future<? extends T> future)
      Wraps Java Future in a Promise running it with given Executor.
      Parameters:
      executor - executor to execute the future concurrently
      future - the future itself
      Returns:
      a new Promise of the future result

    • ofBlocking

      static <T> Promise<T> ofBlocking(Executor executor, io.activej.common.function.SupplierEx<? extends T> supplier)
      Runs some task in another thread (executed by a given Executor) and returns a Promise for it. Also manages external task count for current reactor, so it won't shut down until the task is complete.
      Parameters:
      executor - executor to execute the task concurrently
      supplier - the task itself
      Returns:
      Promise for the given task

    • ofBlocking

      static Promise<Void> ofBlocking(Executor executor, io.activej.common.function.RunnableEx runnable)
      Same as ofBlocking(Executor, SupplierEx), but without a result (returned Promise is only a marker of completion).

    • isComplete

      @Contract(pure=true) default boolean isComplete()

    • isResult

      @Contract(pure=true) boolean isResult()

    • isException

      @Contract(pure=true) boolean isException()

    • getResult

      @Contract(pure=true) T getResult()

    • getException

      @Contract(pure=true) Exception getException()

    • getTry

      @Contract(pure=true) io.activej.common.collection.Try<T> getTry()

    • async

      @Contract(pure=true) Promise<T> async()
      Ensures that Promise completes asynchronously: if this Promise is already completed, its completion will be posted to the next reactor tick. Otherwise, does nothing.

    • subscribe

      Promise<T> subscribe(Callback<? super T> cb)

    • map

      default <U> Promise<U> map(io.activej.common.function.FunctionEx<? super T,? extends U> fn)
      Returns a new Promise which is obtained by mapping a result of this promise to some other value. If this promise is completed exceptionally, a mapping function will not be applied.

      A mapping function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map the result of this Promise to a new value
      Returns:
      new Promise whose result is the result of function applied to the result of this promise
      See Also:

    • map

      default <U> Promise<U> map(io.activej.common.function.BiFunctionEx<? super T,@Nullable Exception,? extends U> fn)
      Returns a new Promise which is obtained by mapping a result and an exception of this promise to some other value. If this promise is completed exceptionally, an exception passed to a mapping function is guaranteed to be not null.

      A {bi function} may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map a result and an exception of this promise to some other value
      Returns:
      new Promise whose result is the result of function applied to the result and exception of this promise

    • map

      default <U> Promise<U> map(io.activej.common.function.FunctionEx<? super T,? extends U> fn, io.activej.common.function.FunctionEx<Exception,? extends U> exceptionFn)
      Returns a new Promise which is obtained by mapping either a result or an exception of this promise to some other values. If this promise is completed successfully, the first function will be called mapping the result to some other value. Otherwise, second function will be called mapping the exception to some other value.

      Each function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map a result of this promise to some other value
      exceptionFn - a function to map an exception of this promise to some other value
      Returns:
      new Promise whose result is the result of either first or second function applied either to a result or an exception of this promise.

    • mapException

      default Promise<T> mapException(io.activej.common.function.FunctionEx<Exception,Exception> exceptionFn)
      Returns a new Promise which is obtained by mapping an exception of this promise to some other exception. The mapping function will be called only if this promise completes exceptionally

      A mapping function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      exceptionFn - a function to map an exception of this promise to some other value
      Returns:
      new Promise whose result is the result of a mapping function applied either to an exception of this promise.

    • mapException

      default <E extends Exception> Promise<T> mapException(Class<E> clazz, io.activej.common.function.FunctionEx<? super E,? extends Exception> exceptionFn)
      Returns a new Promise which is obtained by mapping an exception of this promise to some other exception. The mapping function will be called only if this promise completes with an exception that is an instance of a given Class

      A mapping function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      clazz - an exception class that exception is tested against. A mapping function is applied only if an exception of this promise is an instance of the specified class
      exceptionFn - a function to map an exception of this promise to some other value
      Returns:
      new Promise whose result is the result of a mapping function applied either to an exception of this promise.

    • then

      default <U> Promise<U> then(AsyncSupplierEx<U> fn)
      Returns a new Promise which is obtained by calling a provided supplier of a new promise. If this promise is completed exceptionally, a supplier will not be called.

      A supplier may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a supplier of a new promise which will be called if this promise completes successfully

    • thenCallback

      default <U> Promise<U> thenCallback(CallbackSupplierEx<U> fn)

    • then

      default <U> Promise<U> then(AsyncFunctionEx<? super T,U> fn)
      Returns a new Promise which is obtained by mapping a result of this promise to some other promise. If this promise is completed exceptionally, a mapping function will not be applied.

      A mapping function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map the result of this Promise to a new promise
      Returns:
      new Promise which is the result of function applied to the result of this promise
      See Also:

    • thenCallback

      default <U> Promise<U> thenCallback(CallbackFunctionEx<? super T,U> fn)

    • then

      default <U> Promise<U> then(AsyncBiFunctionEx<? super T,@Nullable Exception,U> fn)
      Returns a new Promise which is obtained by mapping a result and an exception of this promise to some other promise. If this promise is completed exceptionally, an exception passed to a mapping function is guaranteed to be not null.

      A function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map a result and an exception of this promise to some other promise
      Returns:
      new Promise which is the result of function applied to the result and exception of this promise

    • thenCallback

      <U> Promise<U> thenCallback(CallbackBiFunctionEx<? super T,@Nullable Exception,U> fn)

    • then

      default <U> Promise<U> then(AsyncFunctionEx<? super T,U> fn, AsyncFunctionEx<Exception,U> exceptionFn)
      Returns a new Promise which is obtained by mapping either a result or an exception of this promise to some other promises. If this promise is completed successfully, the first function will be called mapping the result to a promise of some other value. Otherwise, second function will be called mapping the exception to a promise of some other value.

      Each function may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a function to map a result of this promise to a dofferent promise
      exceptionFn - a function to map an exception of this promise a different promise
      Returns:
      new Promise which is a result of either first or second function applied either to a result or an exception of this promise.

    • thenCallback

      default <U> Promise<U> thenCallback(CallbackFunctionEx<? super T,U> fn, CallbackFunctionEx<Exception,U> exceptionFn)

    • whenComplete

      default Promise<T> whenComplete(io.activej.common.function.BiConsumerEx<? super T,Exception> fn)
      Subscribes given consumer to be executed after this Promise completes (either successfully or exceptionally). Returns a new Promise.

      A consumer may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - a consumer that consumes a result and an exception of this promise

    • whenComplete

      default Promise<T> whenComplete(io.activej.common.function.ConsumerEx<? super T> fn, io.activej.common.function.ConsumerEx<Exception> exceptionFn)
      Subscribes given consumers to be executed after this Promise completes (either successfully or exceptionally). The first consumer will be executed if this Promise completes successfully, otherwise the second promise will be executed. Returns a new Promise.

      Each consumer may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - consumer that consumes a result of this promise
      exceptionFn - consumer that consumes an exception of this promise

    • whenComplete

      default Promise<T> whenComplete(io.activej.common.function.RunnableEx action)
      Subscribes given runnable to be executed after this Promise completes (either successfully or exceptionally). Returns a new Promise.

      A runnable may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      action - runnable to be executed after this promise completes

    • whenResult

      default Promise<T> whenResult(io.activej.common.function.ConsumerEx<? super T> fn)
      Subscribes given consumer to be executed after this Promise completes successfully. Returns a new Promise.

      A consumer may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - consumer that consumes a result of this promise

    • whenResult

      default Promise<T> whenResult(io.activej.common.function.RunnableEx action)
      Subscribes given runnable to be executed after this Promise completes successfully and a result of this Promise satisfy a given Predicate. Returns a new Promise.

      A runnable may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      action - runnable to be executed after this promise completes successfully

    • whenException

      default Promise<T> whenException(io.activej.common.function.ConsumerEx<Exception> fn)
      Subscribes given consumer to be executed after this Promise completes exceptionally. Returns a new Promise.

      A consumer may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      fn - consumer that consumes an exception of this promise

    • whenException

      default <E extends Exception> Promise<T> whenException(Class<E> clazz, io.activej.common.function.ConsumerEx<? super E> fn)
      Subscribes given consumer to be executed after this Promise completes exceptionally and an exception of this Promise is an instance of a given exception Class. Returns a new Promise.

      A consumer may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      clazz - an exception class that exception is tested against. A consumer is called only if an exception of this promise is an instance of the specified class
      fn - consumer that consumes an exception of this promise

    • whenException

      default Promise<T> whenException(io.activej.common.function.RunnableEx action)
      Subscribes given runnable to be executed after this Promise completes exceptionally. Returns a new Promise.

      A runnable may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      action - runnable to be executed after this promise completes exceptionally

    • whenException

      default Promise<T> whenException(Class<? extends Exception> clazz, io.activej.common.function.RunnableEx action)
      Subscribes given runnable to be executed after this Promise completes exceptionally and an exception of this Promise is an instance of a given exception Class. Returns a new Promise.

      A runnable may throw a checked exception. In this case the resulting promise is completed exceptionally with a thrown exception.

      Parameters:
      clazz - an exception class that exception is tested against. A consumer is called only if an exception of this promise is an instance of the specified class
      action - runnable to be executed after this promise completes exceptionally and an exception of this Promise is an instance of a given exception Class.

    • cast

      default <U> Promise<U> cast()
      Casts this promise to a promise of some other type Promise

      Usage example: 

       Promise<Object> promise = Promise.of(255);
 promise.<Integer>cast()
      .map(Integer::toHexString)
      .whenResult(hex -> System.out.println(hex));
      Type Parameters:
      U - a type to which a promise result will be cast
      Returns:
      a promise of type Promise
      Throws:
      ClassCastException - if a promise result is not null and a cast could not be made

    • cast

      default <U> Promise<U> cast(Class<? extends U> cls)
      Casts this promise to a promise of some other type Promise

      Usage example: 

       Promise<Object> promise = Promise.of(255);
 promise.cast(Integer.class)
      .map(Integer::toHexString)
      .whenResult(hex -> System.out.println(hex));
      Type Parameters:
      U - a type to which a promise result will be cast
      Parameters:
      cls - a class to which a result of this promise will be cast
      Returns:
      a promise of type Promise
      Throws:
      ClassCastException - if a promise result is not null and a cast could not be made

    • combine

      @Contract(pure=true) <U, V> Promise<V> combine(Promise<? extends U> other, io.activej.common.function.BiFunctionEx<? super T,? super U,? extends V> fn)
      Returns a new Promise that, when this and the other given Promise both complete, is executed with the two results as arguments to the supplied function.
      Parameters:
      other - the other Promise
      fn - the function to use to compute the value of the returned Promise
      Returns:
      new Promise

    • both

      @Contract(pure=true) Promise<Void> both(Promise<?> other)
      Returns a new Promise when both this and provided other Promises complete.
      Parameters:
      other - the other Promise
      Returns:
      Promise of null when both this and other Promise complete

    • either

      @Contract(pure=true) Promise<T> either(Promise<? extends T> other)
      Returns the Promise which was completed first.
      Parameters:
      other - the other Promise
      Returns:
      the first completed Promise

    • toTry

      @Contract(pure=true) Promise<io.activej.common.collection.Try<T>> toTry()
      Returns Promise that always completes successfully with result or exception wrapped in Try.

    • toVoid

      @Contract(pure=true) Promise<Void> toVoid()
      Waits for result and discards it.

    • next

      @Internal void next(NextPromise<? super T,?> cb)
      Calls a callback after this promise is completed, passing both a result and an exception of a promise to the callback. This method is similar to whenComplete(BiConsumerEx) but does not create or return a new promise. A Callback interface also prohibits throwing checked exceptions.

      In most cases whenComplete(BiConsumerEx) is preferred. Fall back to using this method only if you expect a performance hit from constantly calling whenComplete(BiConsumerEx) and creating new promises as a result.

      Parameters:
      cb - a callback to be called once a promise completes

    • call

      @Internal default void call(Callback<? super T> cb)
      Specified by:
      call in interface AsyncComputation<T>

    • toCompletableFuture

      @Contract(pure=true) CompletableFuture<T> toCompletableFuture()
      Wraps Promise into CompletableFuture.