Promise (Codename One API)

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:
1. Instead of catch(), we use except()
2. Instead of finally(), we use always()
Since then(Functor, 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.
Since:

8.0

See Also:

MDN documentation for Promise

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Promise.State
Encapsulates the state of a Promise.

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

Constructor Summary

Constructors
Constructor and Description

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

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 `then(Functor, Functor)` that uses `SuccessCallback` instead of `Functor`.
`static Promise`	`reject(Throwable err)`
`static <V> Promise<V>`	`resolve(V value)`
`Promise`	`then(Functor<T,?> resolutionFunc)`
`Promise`	`then(Functor<T,?> resolutionFunc, Functor<Throwable,?> rejectionFunc)` The then() method returns a Promise.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Promise
```
public Promise(ExecutorFunction executor)
```
    Creates a new promise with the given executor function. Works the same as Javascript equivalent.
    
    Parameters:
    
    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 Detail
  - ready
```
public Promise ready(SuccessCallback<T> resolutionFunc,
                     SuccessCallback<Throwable> rejectionFunc)
```
    A wrapper for then(Functor, Functor) that uses SuccessCallback instead of Functor.
    
    Parameters:
    
    resolutionFunc - Callback to run on resolution of promise.
    
    rejectionFunc - Callback to run on rejection of promise.
    
    Returns:
  - 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.
    
    Returns:
  - onFail
```
public Promise onFail(SuccessCallback<Throwable> rejectionFunc)
```
    A wrapper for except(Functor) that uses SuccessCallback instead of Functor.
    
    Parameters:
    
    rejectionFunc -
    
    Returns:
  - onComplete
```
public Promise onComplete(SuccessCallback handlerFunc)
```
    A wrapper for always(Functor) that uses SuccessCallback instead of Functor.
    
    Parameters:
    
    handlerFunc -
    
    Returns:
  - then
```
public Promise then(Functor<T,?> resolutionFunc)
```
    Parameters:
    
    resolutionFunc -
    
    Returns:
  - 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:
    
    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.
    
    Returns:
    
    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 -
    
    Returns:
    
    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.
    
    Returns:
  - getState
```
public Promise.State getState()
```
    Returns the current state of the promise.
    
    Returns:
  - 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 -
    
    Returns:
    
    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 -
    
    Returns:
    
    See Also:
    
    See MDN documentation for allSettled()
  - 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.
    
    Returns:
  - 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)
```
  - asAsyncResource
```
public AsyncResource<T> asAsyncResource()
```

Class Promise<T>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Promise

Method Detail

ready

onSuccess

onFail

onComplete

then

then

except

always

getValue

getState

all

allSettled

await

resolve

reject

promisify

asAsyncResource