public class Promise<T>

  1. Object
  2. Promise

An implementation of Promise for use with Codename One applications. Due to java reserved words, there are a few differences in this implementation:

  • Instead of catch(), we use except()

  • Instead of finally(), we use always()

Since Functor), #except(Functor), and #always(Functor) take Functors as parameters, which must have a return value, this implementation provides convenience wrappers #onSuccess(SuccessCallback), #onFail(SuccessCallback), and #onComplete(SuccessCallback) which take SuccessCallback objects instead. For simple cases, these wrappers will be easier to use because you don’t need to return a dummy null at the end of the callback.

For more complex cases, where the return value of one Functor is meant to be piped into the subsequent Functor, then the Functor variants should be used.

Nested types

enum Promise.StateEncapsulates the state of a Promise.

Constructors

public Promise(ExecutorFunction executor)Creates a new promise with the given executor function.

Methods

public static Promise all(Promise... 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.
public static Promise allSettled(Promise... promises)The Promise.allSettled() method returns a promise that resolves after all of the given promises have either fulfilled or rejected, with an array of objects that each describes the outcome of each promise.
public static <V> Promise<V> resolve(V value)
public static Promise reject(Throwable err)
public static <V> Promise<V> promisify(AsyncResource<V> res)
public Promise ready(SuccessCallback<T> resolutionFunc, SuccessCallback<Throwable> rejectionFunc)A wrapper for Functor) that uses SuccessCallback instead of Functor.
public Promise onSuccess(SuccessCallback<T> resolutionFunc)A wrapper for #then(Functor) that uses SuccessCallback instead of Functor.
public Promise onFail(SuccessCallback<Throwable> rejectionFunc)A wrapper for #except(Functor) that uses SuccessCallback instead of Functor.
public Promise onComplete(SuccessCallback handlerFunc)A wrapper for #always(Functor) that uses SuccessCallback instead of Functor.
public Promise then(Functor<T, ?> resolutionFunc)
public Promise then(Functor<T, ?> resolutionFunc, Functor<Throwable, ?> rejectionFunc)The then() method returns a Promise.
public Promise except(Functor<Throwable, ?> rejectionFunc)Implementation of Promise.catch().
public Promise always(Functor handlerFunc)Implementation of Promise.finally().
public T getValue()Gets the return value once the promise is fulfilled.
public Promise.State getState()Returns the current state of the promise.
public T await()Uses invokeAndBlock to wait for this promise to be either resolved or rejected.
public AsyncResource<T> asAsyncResource()

Inherited methods

From Object

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

Constructor details

Promise

public Promise(ExecutorFunction executor)
Creates a new promise with the given executor function. Works the same as Javascript equivalent.

Parameters

executor ExecutorFunction
The executor function. This is executed immediately, and should call either the passed resolve or reject functor to mark success or failure.

See also

Method details

all

public static Promise all(Promise... 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. Unlike the JavaScript original this makes no guarantee about WHICH error is reported when several inputs reject: a handler already attached is called with the first, while one attached later reads the stored error, which every subsequent rejection overwrites.

See also

allSettled

public static Promise allSettled(Promise... promises)

The Promise.allSettled() method returns a promise that resolves after all of the given promises have either fulfilled or rejected, with an array of objects that each describes the outcome of each promise.

It is typically used when you have multiple asynchronous tasks that are not dependent on one another to complete successfully, or you’d always like to know the result of each promise.

In comparison, the Promise returned by Promise.all() may be more appropriate if the tasks are dependent on each other / if you’d like to immediately reject upon any of them rejecting.

See also

resolve

public static <V> Promise<V> resolve(V value)

reject

public static Promise reject(Throwable err)

promisify

public static <V> Promise<V> promisify(AsyncResource<V> res)

ready

public Promise ready(SuccessCallback<T> resolutionFunc, SuccessCallback<Throwable> rejectionFunc)
A wrapper for Functor) that uses SuccessCallback instead of Functor.

Parameters

resolutionFunc SuccessCallback<T>
Callback to run on resolution of promise.
rejectionFunc SuccessCallback<Throwable>
Callback to run on rejection of promise.

onSuccess

public Promise onSuccess(SuccessCallback<T> resolutionFunc)
A wrapper for #then(Functor) that uses SuccessCallback instead of Functor.

Parameters

resolutionFunc SuccessCallback<T>
Callback called when project is fulfilled.

onFail

public Promise onFail(SuccessCallback<Throwable> rejectionFunc)
A wrapper for #except(Functor) that uses SuccessCallback instead of Functor.

onComplete

public Promise onComplete(SuccessCallback handlerFunc)
A wrapper for #always(Functor) that uses SuccessCallback instead of Functor.

then

public Promise then(Functor<T, ?> resolutionFunc)

then

public Promise then(Functor<T, ?> resolutionFunc, Functor<Throwable, ?> rejectionFunc)
The then() method returns a Promise. It takes up to two arguments: callback functions for the success and failure cases of the Promise.

Parameters

resolutionFunc Functor<T, ?>
A Function called if the Promise is fulfilled. This function has one argument, the fulfillment value. If it is null, it is internally replaced with an “Identity” function (it returns the received argument).
rejectionFunc Functor<Throwable, ?>
A Function called if the Promise is rejected. This function has one argument, the rejection reason. If it is null, the rejection passes through unhandled to the promise this method returns, carrying the original reason.

Returns

Once a Promise is fulfilled or rejected, the respective handler function (resolutionFunc or rejectionFunc) will be called asynchronously (scheduled on the EDT). The behavior of the handler function follows a specific set of rules. If a handler function:

returns a value, the promise returned by then gets resolved with the returned value as its value. doesn’t return anything, the promise returned by then gets resolved with an undefined value. throws an error, the promise returned by then gets rejected with the thrown error as its value. returns an already fulfilled promise, the promise returned by then gets fulfilled with that promise’s value as its value. returns an already rejected promise, the promise returned by then gets rejected with that promise’s value as its value. returns another pending promise object, the resolution/rejection of the promise returned by then will be subsequent to the resolution/rejection of the promise returned by the handler. Also, the resolved value of the promise returned by then will be the same as the resolved value of the promise returned by the handler.

See also

except

public Promise except(Functor<Throwable, ?> rejectionFunc)
Implementation of Promise.catch(). Named “except” because of Java reserved word..

Parameters

rejectionFunc Functor<Throwable, ?>
Function called if promise is rejected.

See also

always

public Promise always(Functor handlerFunc)
Implementation of Promise.finally(). Named “always” because of Java reserved word.

See also

getValue

public T getValue()
Gets the return value once the promise is fulfilled. If the promise isnt resolved, this just returns null.

getState

public Promise.State getState()
Returns the current state of the promise.

await

public T await()
Uses invokeAndBlock to wait for this promise to be either resolved or rejected. This will throw an exception of type AsyncResource.AsyncExecutionException if the promise failed. Otherwise it will return the resolved value.

asAsyncResource

public AsyncResource<T> asAsyncResource()