me.joeycumines.javapromises.core

Class PromiseApi

java.lang.Object

me.joeycumines.javapromises.core.PromiseApi

All Implemented Interfaces:

PromiseFactory

Direct Known Subclasses:

PromiseRunnableFactory, PromiseStageFactory

public abstract class PromiseApi
extends java.lang.Object
implements PromiseFactory

Helpers for the creation and use promises. It is not required to use this implementation, but it is designed to work with any promise implementation.

Note: This class is designed to work with any promise implementation, make a concrete class extending this.

Constructor Summary

Constructors

Constructor and Description
PromiseApi()

Method Summary

Modifier and Type	Method and Description
<T> Promise<java.util.List<T>>	all(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable) Given an iterable of one or more promises, return a promise, that will resolve with a List containing the fulfillment values of each input promise, provided every promise resolves successfully.
<T> Promise<java.util.List<T>>	all(Promise<? extends T> promise, Promise<? extends T>... promises)
<T> Promise<T>	any(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable) Given an iterable of one or more promises, return a promise, that will fulfill with the value of the first of the input promises that fulfills.
<T> Promise<T>	any(Promise<? extends T> promise, Promise<? extends T>... promises)
Promise<?>	attempt(java.lang.Runnable action) Perform an action, and return a promise that will resolve with rejected, if the action throws an exception.
<T> Promise<T>	attempt(java.util.function.Supplier<? extends Promise<? extends T>> action) Perform an action, and return a promise that will resolve with rejected, if the action throws an exception.
<T,U> Promise<java.util.List<U>>	each(java.lang.Iterable<? extends T> inputIterable, java.util.function.Function<? super T,? extends Promise<? extends U>> action) Given an iterable, perform an asynchronous action on each element serially, similar to Iterable.forEach(Consumer).
<T> Promise<T>	race(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable) Given an iterable of one or more promises, return a promise, that will resolve with the same state and value as the first one that resolves.
<T> Promise<T>	race(Promise<? extends T> promise, Promise<? extends T>... promises)
<T> Promise<T>	resolve(java.lang.Object value, java.lang.Class<? extends T> type) Create a new promise that will fulfill or reject, if given a promise and based on it's state, otherwise simply fulfilling with the value given, provided it can be cast to the given type.
<T> java.util.List<Promise<T>>	resolveAll(java.lang.Iterable<?> inputIterable, java.lang.Class<? extends T> type) Copy an iterable into a new ArrayList, performing resolve(Object, Class) on each element.
<T> java.util.concurrent.CompletableFuture<T>	toCompletableFuture(Promise<? extends T> promise) Convert a promise to a CompletableFuture.

Methods inherited from class java.lang.Object

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

Methods inherited from interface me.joeycumines.javapromises.core.PromiseFactory

create, fulfill, reject, wrap

Constructor Detail

PromiseApi

public PromiseApi()

Method Detail

all

@SafeVarargs
public final <T> Promise<java.util.List<T>> all(Promise<? extends T> promise,
                                                             Promise<? extends T>... promises)
                                                      throws java.lang.NullPointerException,
                                                             java.lang.IllegalArgumentException

Throws:

java.lang.NullPointerException

java.lang.IllegalArgumentException

See Also:

all(Iterable)

race

@SafeVarargs
public final <T> Promise<T> race(Promise<? extends T> promise,
                                              Promise<? extends T>... promises)
                                       throws java.lang.NullPointerException,
                                              java.lang.IllegalArgumentException

Throws:

java.lang.NullPointerException

java.lang.IllegalArgumentException

See Also:

race(Iterable)

any

@SafeVarargs
public final <T> Promise<T> any(Promise<? extends T> promise,
                                             Promise<? extends T>... promises)
                                      throws java.lang.NullPointerException,
                                             java.lang.IllegalArgumentException

Throws:

java.lang.NullPointerException

java.lang.IllegalArgumentException

See Also:

any(Iterable)

all

public <T> Promise<java.util.List<T>> all(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable)
                                   throws java.lang.NullPointerException,
                                          java.lang.IllegalArgumentException

Given an iterable of one or more promises, return a promise, that will resolve with a List containing the fulfillment values of each input promise, provided every promise resolves successfully. The returned promise will reject with same reason as the first (if any) input promise that rejects. This will not wait on any other promises, and is as such useful for situations requiring early-exit behaviour.

If any of the input promises are already rejected, then the first encountered rejected promise (using a iterator), will have it's rejection reason propagated to the returned promise.

Unlike the JS promise spec, an empty iterable WILL throw an IllegalArgumentException.

Any null argument encountered will result in a NullPointerException (MAY not be triggered by an input containing a null value IF and only if there is a rejected promise encountered BEFORE the null value).

Type Parameters:

T - The type of the promise to return.

Parameters:

promiseIterable - The promises to resolve. Must not be null, and must contain no null values.

Returns:

A promise that will resolve successfully only if all inputs do, with their values in a list.

Throws:

java.lang.NullPointerException - If the promiseIterable parameter, or any of it's values, are null.*

java.lang.IllegalArgumentException - If the iterable was empty.

race

public <T> Promise<T> race(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable)
                    throws java.lang.NullPointerException,
                           java.lang.IllegalArgumentException

Given an iterable of one or more promises, return a promise, that will resolve with the same state and value as the first one that resolves. This exit-early behaviour is useful in a number of cases.

If any of the provided promises are already resolved, then the first encountered promise (using an iterator) will be used to determine the state and value of the returned promise.

Unlike the JS promise spec, an empty iterable WILL throw an IllegalArgumentException.

Any null argument encountered will result in a NullPointerException (MAY not be triggered by an input containing a null value IF and only if there is a resolve promise encountered BEFORE the null value).

Type Parameters:

T - The type of the promise to return.

Parameters:

promiseIterable - The promises to race. Must not be null, and must contain no null values.

Returns:

A promise that will resolve with the same state and value as the first input promise to resolve.

Throws:

java.lang.NullPointerException - If the promiseIterable parameter, or any of it's values, are null.*

java.lang.IllegalArgumentException - If the iterable was empty.

any

public <T> Promise<T> any(java.lang.Iterable<? extends Promise<? extends T>> promiseIterable)
                   throws java.lang.NullPointerException,
                          java.lang.IllegalArgumentException

Given an iterable of one or more promises, return a promise, that will fulfill with the value of the first of the input promises that fulfills. If all of the promises reject, then the returned promise will reject with an AggregateException, which can be used to retrieve the reasons why it rejected.

If any of the provided promises are already fulfilled, then the first iterated promise will have it's fulfillment value propagated. If they are all rejected, then this will reject immediately.

Any null argument encountered will result in a NullPointerException (MAY not be triggered by an input containing a null value IF and only if there is a fulfilled promise encountered BEFORE the null value).

Type Parameters:

T - The type of promise to return.

Parameters:

promiseIterable - The promises to watch. Must not be null, and must contain no null values.

Returns:

A new promise, that will fulfill the same as the first input to do so, or reject when all do.

Throws:

java.lang.NullPointerException - If the promiseIterable parameter, or any of it's values, are null.*

java.lang.IllegalArgumentException - If the iterable was empty.

each

public <T,U> Promise<java.util.List<U>> each(java.lang.Iterable<? extends T> inputIterable,
                                             java.util.function.Function<? super T,? extends Promise<? extends U>> action)
                                      throws java.lang.NullPointerException

Given an iterable, perform an asynchronous action on each element serially, similar to Iterable.forEach(Consumer). These actions are chained together using the promise returned from each call to action, which takes the iterated value. The next element will not be iterated until / unless the promise returned by the previous action call resolves successfully. A null return value from the action is allowed, it will be treated as a null fulfillment.

If all actions complete successfully, the returned Promise will fulfill with a List, containing an element for each element iterated, in order, from the inputIterable. The elements will be set with the fulfillment values of the promises returned by the corresponding action call.

If any action returns a rejected promise or throws any exceptions, then the returned promise will resolve as REJECTED, with the same exception.

It should be noted that the iterable is walked before the async operations are performed, in order to improve thread safety (the values are shallow copied locally).

Any null parameters will result in a NullPointerException.

Type Parameters:

T - The type of the input values.

U - The type of the output values.

Parameters:

inputIterable - The source of the values to iterate.

action - The action to perform on each value.

Returns:

A new promise, that will resolve with a List of promises

Throws:

java.lang.NullPointerException - If any parameters are null.

attempt

public <T> Promise<T> attempt(java.util.function.Supplier<? extends Promise<? extends T>> action)
                       throws java.lang.NullPointerException

Perform an action, and return a promise that will resolve with rejected, if the action throws an exception.

If the action returns a non null promise, then the returned promise will reflect the same state and value.

Type Parameters:

T - The type of the promise returned.

Parameters:

action - The action to attempt.

Returns:

A new promise, that will resolve successfully, provided the action completes + does not return rejected.

Throws:

java.lang.NullPointerException - If the action is null.

attempt

public Promise<?> attempt(java.lang.Runnable action)
                   throws java.lang.NullPointerException

Perform an action, and return a promise that will resolve with rejected, if the action throws an exception. The returned promise will fulfill with a null value on success, or reject with the thrown exception on failure.

If you need a return type use attempt(Supplier).

Parameters:

action - The action to perform.

Returns:

A promise that will resolve successfully if the provided action does not throw an exception.

Throws:

java.lang.NullPointerException - If the action is null.

See Also:

If you need a typed promise.

toCompletableFuture

public <T> java.util.concurrent.CompletableFuture<T> toCompletableFuture(Promise<? extends T> promise)
                                                                  throws java.lang.NullPointerException

Convert a promise to a CompletableFuture. The reverse of this conversion can be performed by instancing a new PromiseStage.

Type Parameters:

T - The type of the returned CompletableFuture.

Parameters:

promise - The promise to convert.

Returns:

A new CompletableFuture that will resolve with the same state as the input promise.

Throws:

java.lang.NullPointerException - If the input promise is null.

resolve

public <T> Promise<T> resolve(java.lang.Object value,
                              java.lang.Class<? extends T> type)
                       throws CircularResolutionException,
                              java.lang.IllegalArgumentException,
                              java.lang.NullPointerException

Create a new promise that will fulfill or reject, if given a promise and based on it's state, otherwise simply fulfilling with the value given, provided it can be cast to the given type.

This method supports the resolution of multiple promises, that are chained together to an unknown depth.

This method uses a provided type parameter to provide type safety. If at all possible it is, however, recommended to simply chain promises in a inherently type safe way.

If the provided value is not a promise, or it and any chained promise(s) are ALL resolved this MUST happen synchronously, however if any are PENDING then the returned promise will resolve AFTER value, and any children.

NOTE: This method is RECURSIVE, like the A+ Promise spec, and MUST throw a CircularResolutionException in the event that the provided promise is already resolved, and is part of circularly linked resolved promises.

If Promise.class or a subclass is used as the type, an IllegalArgumentException will be thrown.

If type is null, a NullPointerException will be thrown.

Parameters:

value - The value to resolve.

type - The type of the promise that will be resolved, from the input value.

Returns:

A new promise, that will resolve AFTER the provided promise. MAY be created by this PromiseFactory.

Throws:

CircularResolutionException - If the provided promise will form a loop.

java.lang.IllegalArgumentException - If the type was Promise.class.

java.lang.NullPointerException - If the type was null.

resolveAll

public <T> java.util.List<Promise<T>> resolveAll(java.lang.Iterable<?> inputIterable,
                                                 java.lang.Class<? extends T> type)
                                          throws java.lang.NullPointerException

Copy an iterable into a new ArrayList, performing resolve(Object, Class) on each element.

Any null parameters will result in a NullPointerException.

Type Parameters:

T - The target type of the items.

Parameters:

inputIterable - An iterable of items to resolve.

Returns:

A new ArrayList containing the resolved promises (possibly pending).

Throws:

java.lang.NullPointerException - If either input is null.