Package io.activej.promise

Interface Promise<T>

All Superinterfaces:

AsyncComputation<T>, Promisable<T>

All Known Implementing Classes:

CompleteExceptionallyPromise, CompleteNullPromise, CompletePromise, CompleteResultPromise, NextPromise, SettablePromise

public interface Promise<T>
extends Promisable<T>, AsyncComputation<T>

Replacement of default Java CompletionStage interface with optimized design, which allows to handle 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:

CompletionStage

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Promise.BlockingCallable<V>
static interface	Promise.BlockingRunnable

Method Summary

Modifier and Type	Method	Description
@NotNull Promise<T>	async()	Ensures that Promise completes asynchronously: if this Promise is already completed, its completion will be posted to next eventloop tick.
@NotNull Promise<Void>	both(@NotNull Promise<?> other)	Returns a new Promise when both this and provided other Promises complete.
<U,V> @NotNull Promise<V>	combine(@NotNull Promise<? extends U> other, @NotNull BiFunction<? 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.
static @NotNull CompleteNullPromise<Void>	complete()	Creates successfully completed Promise
@NotNull Promise<T>	either(@NotNull Promise<? extends T> other)	Returns the Promise which was completed first.
Throwable	getException()
T	getResult()
io.activej.common.collection.Try<T>	getTry()
default boolean	isComplete()
boolean	isException()
boolean	isResult()
<U> @NotNull Promise<U>	map(@NotNull Function<? super T,? extends U> fn)	Returns a new Promise which is executed with this Promise's result as the argument to the provided function when this Promise completes successfully.
<U> @NotNull Promise<U>	mapEx(@NotNull BiFunction<? super T,@Nullable Throwable,? extends U> fn)	Returns a new Promise which is executed with this Promise's result as the argument to the provided function when this Promise completes either successfully (when exception is null) or with an exception.
<U,P extends Callback<? super T> & Promise<U>> @NotNull Promise<U>	next(P promise)	Executes given promise after execution of this Promise completes.
static <T> @NotNull CompletePromise<T>	of(T value)	Creates successfully completed Promise.
static <T> @NotNull Promise<T>	of(T value, @Nullable Throwable e)	Creates a completed Promise from T value and Throwable e parameters, any of them can be null.
static <T> Promise<T>	ofBlockingCallable(@NotNull Executor executor, @NotNull Promise.BlockingCallable<? extends T> callable)	Runs some task in another thread (executed by a given Executor) and returns a Promise for it.
static @NotNull Promise<Void>	ofBlockingRunnable(@NotNull Executor executor, @NotNull Promise.BlockingRunnable runnable)	Same as ofBlockingCallable(Executor, BlockingCallable), but without a result (returned Promise is only a marker of completion).
static <T> @NotNull Promise<T>	ofCallback(@NotNull Consumer<@NotNull SettablePromise<T>> callbackConsumer)	Creates and returns a new SettablePromise that is accepted by the provided Consumer of SettablePromise
static <T> @NotNull Promise<T>	ofCompletionStage(CompletionStage<? extends T> completionStage)	Wraps Java CompletionStage in a Promise, running it in current eventloop.
static <T> @NotNull CompleteExceptionallyPromise<T>	ofException(@NotNull Throwable e)	Creates an exceptionally completed Promise.
static <T> @NotNull Promise<T>	ofFuture(@NotNull CompletableFuture<? extends T> future)	Creates a Promise wrapper around default Java CompletableFuture and runs it immediately.
static <T> @NotNull Promise<T>	ofFuture(@NotNull Executor executor, @NotNull Future<? extends T> future)	Wraps Java Future in a Promise running it with given Executor.
static <T> @NotNull Promise<T>	ofOptional(@NotNull Optional<T> optional)
static <T> @NotNull Promise<T>	ofOptional(@NotNull Optional<T> optional, @NotNull Supplier<? extends Throwable> errorSupplier)	Creates a new Promise of the given value.
static <T> @NotNull Promise<T>	ofTry(@NotNull io.activej.common.collection.Try<T> t)	Returns a new CompletePromise or CompleteExceptionallyPromise based on the provided Try.
default @NotNull Promise<T>	post()
default Promise<T>	promise()
default void	run(@NotNull Callback<? super T> action)
<U> @NotNull Promise<U>	then(@NotNull Function<? super T,? extends Promise<? extends U>> fn)	Returns a new Promise which, when this Promise completes successfully, is executed with this Promise's result as the argument to the supplied function.
<U> @NotNull Promise<U>	then(@NotNull Supplier<? extends Promise<? extends U>> fn)
<U> @NotNull Promise<U>	thenEx(@NotNull BiFunction<? super T,@Nullable Throwable,? extends Promise<? extends U>> fn)	Returns a new Promise which, when this Promise completes either successfully (if exception is null) or exceptionally (if exception is not null), is executed with this Promise's result as the argument to the supplied function.
@NotNull CompletableFuture<T>	toCompletableFuture()	Wraps Promise into CompletableFuture.
@NotNull Promise<io.activej.common.collection.Try<T>>	toTry()	Returns Promise that always completes successfully with result or exception wrapped in Try.
@NotNull Promise<Void>	toVoid()	Waits for result and discards it.
@NotNull Promise<T>	whenComplete(@NotNull Callback<? super T> action)	Subscribes given action to be executed after this Promise completes and returns a new Promise.
@NotNull Promise<T>	whenComplete(@NotNull Runnable action)	Subscribes given action to be executed after this Promise completes and returns a new Promise.
Promise<T>	whenException(@NotNull Runnable action)
Promise<T>	whenException(@NotNull Consumer<Throwable> action)	Subscribes given action to be executed after this Promise completes exceptionally and returns a new Promise.
Promise<T>	whenResult(@NotNull Runnable action)
@NotNull Promise<T>	whenResult(Consumer<? super T> action)	Subscribes given action to be executed after this Promise completes successfully and returns a new Promise.

Method Detail

complete

@NotNull
static @NotNull CompleteNullPromise<Void> complete()

Creates successfully completed Promise

of

@NotNull
static <T> @NotNull CompletePromise<T> of(@Nullable
                                          T value)

Creates successfully completed Promise.

Parameters:

value - result of Promise. If value is null, returns CompleteNullPromise, otherwise CompleteResultPromise

ofException

@NotNull
static <T> @NotNull CompleteExceptionallyPromise<T> ofException(@NotNull
                                                                @NotNull Throwable e)

Creates an exceptionally completed Promise.

Parameters:

e - Throwable

ofCallback

@NotNull
static <T> @NotNull Promise<T> ofCallback(@NotNull
                                          @NotNull Consumer<@NotNull SettablePromise<T>> callbackConsumer)

Creates and returns a new SettablePromise that is accepted by the provided Consumer of SettablePromise

ofOptional

@NotNull
static <T> @NotNull Promise<T> ofOptional(@NotNull
                                          @NotNull Optional<T> optional)

See Also:

ofOptional(Optional, Supplier)

ofOptional

@NotNull
static <T> @NotNull Promise<T> ofOptional(@NotNull
                                          @NotNull Optional<T> optional,
                                          @NotNull
                                          @NotNull Supplier<? extends Throwable> 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

@NotNull
static <T> @NotNull Promise<T> of(@Nullable
                                  T value,
                                  @Nullable
                                  @Nullable Throwable e)

Creates a completed Promise from T value and Throwable e parameters, any of them can be null. Useful for thenEx(BiFunction) 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

@NotNull
static <T> @NotNull Promise<T> ofTry(@NotNull
                                     @NotNull io.activej.common.collection.Try<T> t)

Returns a new CompletePromise or CompleteExceptionallyPromise based on the provided Try.

ofFuture

@NotNull
static <T> @NotNull Promise<T> ofFuture(@NotNull
                                        @NotNull 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

@NotNull
static <T> @NotNull Promise<T> ofCompletionStage(CompletionStage<? extends T> completionStage)

Wraps Java CompletionStage in a Promise, running it in current eventloop.

Parameters:

completionStage - completion stage itself

Returns:

result of the given completionStage wrapped in a Promise

ofFuture

@NotNull
static <T> @NotNull Promise<T> ofFuture(@NotNull
                                        @NotNull Executor executor,
                                        @NotNull
                                        @NotNull 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

ofBlockingCallable

static <T> Promise<T> ofBlockingCallable(@NotNull
                                         @NotNull Executor executor,
                                         @NotNull
                                         @NotNull Promise.BlockingCallable<? extends T> callable)

Runs some task in another thread (executed by a given Executor) and returns a Promise for it. Also manages external task count for current eventloop, so it won't shut down until the task is complete.

Parameters:

executor - executor to execute the task concurrently

callable - the task itself

Returns:

Promise for the given task

ofBlockingRunnable

@NotNull
static @NotNull Promise<Void> ofBlockingRunnable(@NotNull
                                                 @NotNull Executor executor,
                                                 @NotNull
                                                 @NotNull Promise.BlockingRunnable runnable)

Same as ofBlockingCallable(Executor, BlockingCallable), but without a result (returned Promise is only a marker of completion).

promise

default Promise<T> promise()

Specified by:

promise in interface Promisable<T>

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)
Throwable getException()

getTry

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

async

@Contract(pure=true)
@NotNull
@NotNull Promise<T> async()

Ensures that Promise completes asynchronously: if this Promise is already completed, its completion will be posted to next eventloop tick. Otherwise, does nothing.

post

@Contract(pure=true)
@NotNull
default @NotNull Promise<T> post()

next

@Contract("_ -> param1")
@NotNull
<U,P extends Callback<? super T> & Promise<U>> @NotNull Promise<U> next(@NotNull
                                                                              P promise)

Executes given promise after execution of this Promise completes.

Type Parameters:

U - type of result

Parameters:

promise - given promise

Returns:

subscribed Promise

map

@Contract(pure=true)
@NotNull
<U> @NotNull Promise<U> map(@NotNull
                            @NotNull Function<? super T,? extends U> fn)

Returns a new Promise which is executed with this Promise's result as the argument to the provided function when this Promise completes successfully.

Parameters:

fn - function to be applied to this Promise when it completes successfully

Returns:

new Promise which is the result of function applied to the result of this Promise

See Also:

CompletionStage.thenApply(Function)

mapEx

@Contract(pure=true)
@NotNull
<U> @NotNull Promise<U> mapEx(@NotNull
                              @NotNull BiFunction<? super T,@Nullable Throwable,? extends U> fn)

Returns a new Promise which is executed with this Promise's result as the argument to the provided function when this Promise completes either successfully (when exception is null) or with an exception.

Parameters:

fn - function to be applied to this Promise when it completes either successfully or with an exception

Returns:

new Promise which is the result of function applied to the result of this Promise

then

@Contract(pure=true)
@NotNull
<U> @NotNull Promise<U> then(@NotNull
                             @NotNull Function<? super T,? extends Promise<? extends U>> fn)

Returns a new Promise which, when this Promise completes successfully, is executed with this Promise's result as the argument to the supplied function.

Parameters:

fn - to be applied

then

@NotNull
<U> @NotNull Promise<U> then(@NotNull
                             @NotNull Supplier<? extends Promise<? extends U>> fn)

thenEx

@Contract(pure=true)
@NotNull
<U> @NotNull Promise<U> thenEx(@NotNull
                               @NotNull BiFunction<? super T,@Nullable Throwable,? extends Promise<? extends U>> fn)

Returns a new Promise which, when this Promise completes either successfully (if exception is null) or exceptionally (if exception is not null), is executed with this Promise's result as the argument to the supplied function.

Parameters:

fn - to be applied to the result of this Promise

Returns:

new Promise

whenComplete

@Contract(" _ -> this")
@NotNull
@NotNull Promise<T> whenComplete(@NotNull
                                 @NotNull Callback<? super T> action)

Subscribes given action to be executed after this Promise completes and returns a new Promise.

Parameters:

action - to be executed

whenComplete

@Contract(" _ -> this")
@NotNull
@NotNull Promise<T> whenComplete(@NotNull
                                 @NotNull Runnable action)

Subscribes given action to be executed after this Promise completes and returns a new Promise.

Parameters:

action - to be executed

whenResult

@Contract(" _ -> this")
@NotNull
@NotNull Promise<T> whenResult(Consumer<? super T> action)

Subscribes given action to be executed after this Promise completes successfully and returns a new Promise.

Parameters:

action - to be executed

whenResult

Promise<T> whenResult(@NotNull
                      @NotNull Runnable action)

whenException

@Contract("_ -> this")
Promise<T> whenException(@NotNull
                         @NotNull Consumer<Throwable> action)

Subscribes given action to be executed after this Promise completes exceptionally and returns a new Promise.

Parameters:

action - to be executed

whenException

Promise<T> whenException(@NotNull
                         @NotNull Runnable action)

combine

@Contract(pure=true)
@NotNull
<U,V> @NotNull Promise<V> combine(@NotNull
                                        @NotNull Promise<? extends U> other,
                                        @NotNull
                                        @NotNull BiFunction<? 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)
@NotNull
@NotNull Promise<Void> both(@NotNull
                            @NotNull 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)
@NotNull
@NotNull Promise<T> either(@NotNull
                           @NotNull 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)
@NotNull
@NotNull 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)
@NotNull
@NotNull Promise<Void> toVoid()

Waits for result and discards it.

run

default void run(@NotNull
                 @NotNull Callback<? super T> action)

Specified by:

run in interface AsyncComputation<T>

toCompletableFuture

@Contract(pure=true)
@NotNull
@NotNull CompletableFuture<T> toCompletableFuture()

Wraps Promise into CompletableFuture.