Class Promise<T>

java.lang.Object
com.codename1.util.promise.Promise<T>
public class Promise<T> extends Object

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.

  • Constructor Details

    • Promise

      public Promise(ExecutorFunction executor)

      Creates a new promise with the given executor function. Works the same as Javascript equivalent.

      Parameters
      • executor: @param executor 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, and will reject with this first rejection message / error.

      Parameters
      • promises
      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.

      Parameters
      • promises
      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: Callback to run on resolution of promise.

      • rejectionFunc: 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: Callback called when project is fulfilled.

    • onFail

      public Promise onFail(SuccessCallback<Throwable> rejectionFunc)

      A wrapper for #except(Functor) that uses SuccessCallback instead of Functor.

      Parameters
      • rejectionFunc

    • onComplete

      public Promise onComplete(SuccessCallback handlerFunc)

      A wrapper for #always(Functor) that uses SuccessCallback instead of Functor.

      Parameters
      • handlerFunc

    • then

      public Promise then(Functor<T,?> resolutionFunc)
      Parameters
      • 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: 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: A Function called if the Promise is rejected. This function has one argument, the rejection reason. If it is null, it is internally replaced with a "Thrower" function (it throws an error it received as argument).

      Returns
      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: 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.

      Parameters
      • handlerFunc
      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()