akasha.promise

Class Promise<T>

java.lang.Object

akasha.promise.Promise<T>

@JsType(isNative=true,
        namespace="<global>",
        name="Promise")
public class Promise<T>
extends java.lang.Object

The Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.

A Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.

A Promise is in one of these states:

• pending: initial state, neither fulfilled nor rejected.
• fulfilled: meaning that the operation was completed successfully.
• rejected: meaning that the operation failed.

A pending promise can either be fulfilled with a value or rejected with a reason (error). When either of these options happens, the associated handlers queued up by a promise's then method are called. If the promise has already been fulfilled or rejected when a corresponding handler is attached, the handler will be called, so there is no race condition between an asynchronous operation completing and its handlers being attached.

See Also:

Promise - MDN

Constructor Summary

Constructors

Constructor and Description
Promise(PromiseExecutor<T> executor) Creates a new Promise object.

Method Summary

Modifier and Type	Method and Description
static <V> Promise<JsArray<V>>	all(JsIterable<Promise<? extends V>> promises) The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises.
static <V> Promise<JsArray<V>>	all(Promise<? extends V>... promises) The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises.
static <V> Promise<V>	any(JsIterable<Promise<? extends V>> promises) Promise.any() takes an iterable of Promise objects and, as soon as one of the promises in the iterable fulfills, returns a single promise that resolves with the value from that promise.
static <V> Promise<V>	any(Promise<? extends V>... promises) Promise.any() takes an iterable of Promise objects and, as soon as one of the promises in the iterable fulfills, returns a single promise that resolves with the value from that promise.
<V> Promise<V>	catch_(OnRejectedCallback<? extends V> onRejected) Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.
Promise<T>	finally_(OnSettledCallback onSettle) The finally() method returns a Promise.
static <V> Promise<V>	race(JsIterable<Promise<? extends V>> promises) The Promise.race() method returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise.
static <V> Promise<V>	race(Promise<? extends V>... promises) The Promise.race() method returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise.
static <V> Promise<V>	reject(java.lang.Object reason) Returns a new Promise object that is rejected with the given reason.
static <V> Promise<V>	resolve(Promise<V> value) Returns a new Promise object that is resolved with the given value.
static <V> Promise<V>	resolve(V value) Returns a new Promise object that is resolved with the given value.
<V> Promise<V>	then(OnFulfilledCallback<? super T,? extends V> onFulfilled) Appends the fulfillment handler to the promise, and returns a new promise resolving to the return value of the called handler.
<V> Promise<V>	then(OnFulfilledCallback<? super T,? extends V> onFulfilled, OnRejectedCallback<? extends V> onRejected) Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e.
Promise<java.lang.Void>	thenAccept(AcceptCallback<? super T> onAccept) Appends the fulfillment handler to the promise, and returns a new promise resolving to a void value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Promise

public Promise(@Nonnull
               PromiseExecutor<T> executor)

Creates a new Promise object. The constructor is primarily used to wrap functions that do not already support promises.

Parameters:

executor - a function executed by the constructor during the process of constructing the promise. The executor is custom code that ties an outcome to a promise.

See Also:

Promise() - MDN

Method Detail

all

@SafeVarargs
 @Nonnull
 @JsOverlay
public static <V> Promise<JsArray<V>> all(@Nonnull
                                                                             Promise<? extends V>... promises)

The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises. This returned promise will resolve when all of the input's promises have resolved, or if the input iterable contains no promises. It rejects immediately upon any of the input promises rejecting or non-promises throwing an error, and will reject with this first rejection message / error.

Type Parameters:

V - the component type of the promise returned.

Parameters:

promises - the promises.

Returns:

the result promise.

See Also:

Promise.all - MDN

all

@Nonnull
public static <V> Promise<JsArray<V>> all(@Nonnull
                                                   JsIterable<Promise<? extends V>> promises)

The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises. This returned promise will resolve when all of the input's promises have resolved, or if the input iterable contains no promises. It rejects immediately upon any of the input promises rejecting or non-promises throwing an error, and will reject with this first rejection message / error.

Type Parameters:

V - the component type of the promise results.

Parameters:

promises - the promises.

Returns:

the result promise.

See Also:

Promise.all - MDN

any

@SafeVarargs
 @Nonnull
 @JsOverlay
public static <V> Promise<V> any(@Nonnull
                                                                    Promise<? extends V>... promises)

Promise.any() takes an iterable of Promise objects and, as soon as one of the promises in the iterable fulfills, returns a single promise that resolves with the value from that promise. If no promises in the iterable fulfill (if all of the given promises are rejected), then the returned promise is rejected with an AggregateError, a new subclass of Error that groups together individual errors. Essentially, this method is the opposite of Promise.all().

Type Parameters:

V - the component type of the promise returned.

Parameters:

promises - the promises.

Returns:

A promise that yields the value of the first promise in the given iterable to fulfill or an AggregateError containing the reasons for all the rejected promises.

See Also:

Promise.any - MDN

any

@Nonnull
public static <V> Promise<V> any(@Nonnull
                                          JsIterable<Promise<? extends V>> promises)

Promise.any() takes an iterable of Promise objects and, as soon as one of the promises in the iterable fulfills, returns a single promise that resolves with the value from that promise. If no promises in the iterable fulfill (if all of the given promises are rejected), then the returned promise is rejected with an AggregateError, a new subclass of Error that groups together individual errors. Essentially, this method is the opposite of Promise.all().

Type Parameters:

V - the component type of the promise returned.

Parameters:

promises - the promises.

Returns:

A promise that yields the value of the first promise in the given iterable to fulfill or an AggregateError containing the reasons for all the rejected promises.

See Also:

Promise.any - MDN

race

@SafeVarargs
 @Nonnull
 @JsOverlay
public static <V> Promise<V> race(@Nonnull
                                                                     Promise<? extends V>... promises)

The Promise.race() method returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise.

Type Parameters:

V - the component type of the promise returned.

Parameters:

promises - the promises.

Returns:

A pending Promise that asynchronously yields the value of the first promise in the given iterable to fulfill or reject.

See Also:

Promise.race - MDN

race

@Nonnull
public static <V> Promise<V> race(@Nonnull
                                           JsIterable<Promise<? extends V>> promises)

The Promise.race() method returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise.

Type Parameters:

V - the component type of the promise returned.

Parameters:

promises - the promises.

Returns:

A pending Promise that asynchronously yields the value of the first promise in the given iterable to fulfill or reject.

See Also:

Promise.race - MDN

resolve

@Nonnull
public static <V> Promise<V> resolve(@Nullable
                                              Promise<V> value)

Returns a new Promise object that is resolved with the given value.

Type Parameters:

V - the component type of the promise returned.

Parameters:

value - the promise to wrap and return.

Returns:

a Promise that is resolved with the given value.

See Also:

Promise.resolve - MDN

resolve

@Nonnull
public static <V> Promise<V> resolve(@Nullable
                                              V value)

Returns a new Promise object that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise, the returned promise will be fulfilled with the value.

Generally, if you don't know if a value is a promise or not, Promise.resolve(value) it instead and work with the return value as a promise.

Type Parameters:

V - the component type of the promise returned.

Parameters:

value - the value to use when creating the promise.

Returns:

a Promise that is resolved with the given value.

See Also:

Promise.resolve - MDN

reject

@Nonnull
public static <V> Promise<V> reject(@Nullable
                                             java.lang.Object reason)

Returns a new Promise object that is rejected with the given reason.

Type Parameters:

V - the component type of the promise returned.

Parameters:

reason - the reason to reject promise with.

Returns:

a promise that is rejected with the given reason.

See Also:

Promise.reject - MDN

then

@Nonnull
public <V> Promise<V> then(@Nonnull
                                    OnFulfilledCallback<? super T,? extends V> onFulfilled)

Appends the fulfillment handler to the promise, and returns a new promise resolving to the return value of the called handler.

Type Parameters:

V - the component type of the promise returned from the callback.

Parameters:

onFulfilled - the callback function called when the promise is fulfilled.

Returns:

a Promise with the fulfillment handler set to the specified callback.

See Also:

Promise.then - MDN

thenAccept

@JsMethod(name="then")
 @Nonnull
public Promise<java.lang.Void> thenAccept(@Nonnull
                                                                           AcceptCallback<? super T> onAccept)

Appends the fulfillment handler to the promise, and returns a new promise resolving to a void value. This is an affordance added to simplify integration with a java-esque library and is equivalent to a javascript then method that returns undefined.

Parameters:

onAccept - the callback function called when the promise is fulfilled.

Returns:

a promise with the fulfillment handler set to the specified callback.

See Also:

Promise.then - MDN

catch_

@JsMethod(name="catch")
 @Nonnull
public <V> Promise<V> catch_(@Nonnull
                                                               OnRejectedCallback<? extends V> onRejected)

Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.

Type Parameters:

V - the component type of the promise returned from the callback.

Parameters:

onRejected - the callback function called when the promise is rejected.

Returns:

a Promise with the rejection handler set to the specified callback.

See Also:

Promise.catch - MDN

then

@Nonnull
public <V> Promise<V> then(@Nullable
                                    OnFulfilledCallback<? super T,? extends V> onFulfilled,
                                    @Nullable
                                    OnRejectedCallback<? extends V> onRejected)

Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e. if the relevant handler onFulfilled or onRejected is not a function).

Type Parameters:

V - the component type of the promise returned from the callback.

Parameters:

onFulfilled - the callback function called when the promise is fulfilled.

onRejected - the callback function called when the promise is rejected.

Returns:

a Promise with the fulfillment handler set to the specified callback.

See Also:

Promise.then - MDN

finally_

@JsMethod(name="finally")
 @Nonnull
public Promise<T> finally_(OnSettledCallback onSettle)

The finally() method returns a Promise. When the promise is settled, i.e either fulfilled or rejected, the specified callback function is executed. This provides a way for code to be run whether the promise was fulfilled successfully or rejected once the Promise has been dealt with.

Parameters:

onSettle - a callback function called when the Promise is settled.

Returns:

a Promise with the finally handler set to the specified callback.

See Also:

Promise.finally - MDN