me.joeycumines.javapromises.core

Interface PromiseFactory

All Known Implementing Classes:

PromiseApi, PromiseRunnableFactory, PromiseStageFactory

public interface PromiseFactory

Create promises in completion states, or allow them to be run asynchronously.

This interface provides a way to pass around ways to instance Promise objects, and can be considered the core API.

Method Summary

Modifier and Type	Method and Description
<T> Promise<T>	create(java.util.function.BiConsumer<java.util.function.Consumer<? super T>,java.util.function.Consumer<java.lang.Throwable>> action) Creates a promise, and executes it asynchronously.
<T> Promise<T>	fulfill(T value) Create a new promise that is FULFILLED with the provided value.
<T> Promise<T>	reject(java.lang.Throwable reason) Create a new REJECTED promise, with a provided reason for rejection.
<T> Promise<T>	wrap(Promise<? extends T> promise) Return a promise created by this PromiseFactory, from any given promise, that will resolve in the same way.

Method Detail

create

<T> Promise<T> create(java.util.function.BiConsumer<java.util.function.Consumer<? super T>,java.util.function.Consumer<java.lang.Throwable>> action)

Creates a promise, and executes it asynchronously.

The action parameter format is (fulfill, reject) -> // stuff.

The first call to either fulfill or reject will be the resolved value. Both of these methods must throw a MutatedStateException for any subsequent calls. If no call is made within action, then the state of the promise must be PENDING immediately after action completes. The implementation of BlockingPromise takes advantage of this behaviour.

If fulfill is used to attempt to resolve a promise with itself, it must throw a SelfResolutionException.

Any Throwable throwable that is thrown, within the action, will be the equivalent of calling reject.accept(throwable).

Calling the reject parameter, within the action, with a null value, will cause a NullPointerException to be thrown internally, which will cause the returned promise to resolve as REJECTED, with that exception.

A null action parameter will cause a NullPointerException to be thrown.

Type Parameters:

T - The type the promise will resolve with.

Parameters:

action - The task to perform asynchronously.

Returns:

A new promise.

Throws:

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

reject

<T> Promise<T> reject(java.lang.Throwable reason)

Create a new REJECTED promise, with a provided reason for rejection.

This MUST happen synchronously (the returned Promise MUST be REJECTED, not PENDING to reject asynchronously).

A null reason will result in a NullPointerException being thrown.

Parameters:

reason - The value this will reject with.

Returns:

A new promise.

Throws:

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

fulfill

<T> Promise<T> fulfill(T value)

Create a new promise that is FULFILLED with the provided value.

This MUST happen synchronously (the returned Promise MUST be FULFILLED, not PENDING to fulfill asynchronously).

Type Parameters:

T - The type of the value the promise resolved.

Parameters:

value - The value to fulfill.

Returns:

A new promise.

wrap

<T> Promise<T> wrap(Promise<? extends T> promise)

Return a promise created by this PromiseFactory, from any given promise, that will resolve in the same way.

Performs a similar but tangential function to PromiseApi.resolve(Object, Class), some use cases will require one or the other, and some will require both.

This method is provided as a convenience, for cases when you need to ensure certain behaviour, due to differences in promise implementations.

NOTE: The returned promise must be resolved not pending, if the promise to wrap was already resolved.

Type Parameters:

T - The type of the promise.

Parameters:

promise - The promise you want to wrap.

Returns:

A new promise.