# 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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `Promise.State`
  Encapsulates the state of a Promise.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Promise(ExecutorFunction executor)`
  Creates a new promise with the given executor function.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `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.
  `Promise`
  `always(Functor handlerFunc)`
  Implementation of Promise.finally().
  `AsyncResource<T>`
  `asAsyncResource()`
  `T`
  `await()`
  Uses invokeAndBlock to wait for this promise to be either resolved or rejected.
  `Promise`
  `except(Functor<Throwable, ?> rejectionFunc)`
  Implementation of Promise.catch().
  `Promise.State`
  `getState()`
  Returns the current state of the promise.
  `T`
  `getValue()`
  Gets the return value once the promise is fulfilled.
  `Promise`
  `onComplete(SuccessCallback handlerFunc)`
  A wrapper for `#always(Functor)` that uses `SuccessCallback` instead of `Functor`.
  `Promise`
  `onFail(SuccessCallback<Throwable> rejectionFunc)`
  A wrapper for `#except(Functor)` that uses `SuccessCallback` instead of `Functor`.
  `Promise`
  `onSuccess(SuccessCallback<T> resolutionFunc)`
  A wrapper for `#then(Functor)` that uses `SuccessCallback` instead of `Functor`.
  `static <V> Promise<V>`
  `promisify(AsyncResource<V> res)`
  `Promise`
  `ready(SuccessCallback<T> resolutionFunc, SuccessCallback<Throwable> rejectionFunc)`
  A wrapper for `Functor)` that uses `SuccessCallback` instead of `Functor`.
  `static Promise`
  `reject(Throwable err)`
  `static <V> Promise<V>`
  `resolve(V value)`
  `Promise`
  `then(Functor<T,?> resolutionFunc)`

  ###### Parameters

  `Promise`
  `then(Functor<T,?> resolutionFunc, Functor<Throwable, ?> rejectionFunc)`
  The then() method returns a Promise.

  ### Methods inherited from class Object

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

- ## 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

    - MDN documentation for Promise

- ## 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.

    ###### Parameters

    - `promises`

    ###### See also

    - See MDN documentation for all()

  - ### 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

    - See MDN documentation for allSettled()

  - ### 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, the rejection passes through unhandled to the promise this method returns, carrying the original reason.

    ###### 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

      - See MDN documentation for then()

  - ### 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

    - See MDN documentation for catch()

  - ### always

    public Promise always(Functor handlerFunc)

    Implementation of Promise.finally(). Named "always" because of Java reserved word.

    ###### Parameters

    - `handlerFunc`

    ###### See also

    - See MDN documentation for finally()

  - ### 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()