me.joeycumines.javapromises.v1

Class PromiseRunnable<T>

java.lang.Object

me.joeycumines.javapromises.v1.PromiseBase<T>

me.joeycumines.javapromises.v1.PromiseRunnable<T>

All Implemented Interfaces:

Promise<T>

public class PromiseRunnable<T>
extends PromiseBase<T>

First-pass promise implementation.

The focus was maximum flexibility, with the ability to extend or implement promises for various use cases.

The most complex part of this implementation is the action property which is explained below: - action is used to simplify and provide safety for all paths - action will only be executed AT MOST once, either manually, or part of internal logic - neither action nor runner is required IF you are not calling run(), and will manage the state externally - executing actions are handled by the PromiseRunner, implement that however you wish

Field Summary

Fields inherited from class me.joeycumines.javapromises.v1.PromiseBase

lock

Constructor Summary

Constructors

Constructor and Description
PromiseRunnable()
PromiseRunnable(PromiseRunner runner)
PromiseRunnable(PromiseRunner runner, java.util.function.Consumer<PromiseRunnable<T>> action)

Method Summary

Modifier and Type	Method and Description
<U> Promise<U>	always(java.util.function.BiFunction<? super T,java.lang.Throwable,? extends Promise<? extends U>> callback) Specify a callback that will always run on resolution, or as soon as possible if this is already in a resolved state.
Promise<T>	except(java.util.function.BiConsumer<java.lang.Throwable,java.util.function.Consumer<? super T>> callback) Specify a callback to be run if this resolves with a failed state REJECTED, and return a new promise, that will fulfill with the value accepted within the callback, into it's second argument, a Consumer.
Promise<T>	except(java.util.function.Function<java.lang.Throwable,? extends Promise<? extends T>> callback) Specify a callback to be run if this resolves with a failed state REJECTED, and return a new promise, that will resolve with the same state and value as the callback's returned promise, after the callback promise resolves.
PromiseRunnable<T>	fulfill(T value)
java.util.function.Consumer<PromiseRunnable<T>>	getAction()
PromiseRunner	getRunner()
boolean	isRun()
PromiseRunnable<T>	reject(java.lang.Throwable exception)
PromiseRunnable<T>	resolve(Promise<? extends T> promise) Resolve this promise with the same value/exception and state as another promise.
PromiseRunnable<T>	run()
PromiseRunnable<T>	setAction(java.util.function.Consumer<PromiseRunnable<T>> action)
PromiseRunnable<T>	setRun()
PromiseRunnable<T>	setRunner(PromiseRunner runner)
<U> Promise<U>	then(java.util.function.BiConsumer<? super T,java.util.function.Consumer<? super U>> callback) Specify a callback to be run on successful resolution FULFILLED of this, and return a new promise, that will fulfill with the value accepted within the callback, into it's second argument, a Consumer.
<U> Promise<U>	then(java.util.function.Function<? super T,? extends Promise<? extends U>> callback) Specify a callback to be run on successful resolution FULFILLED of this, and return a new promise, that will resolve with the same state and value as the callback's returned promise, after the callback promise resolves.

Methods inherited from class me.joeycumines.javapromises.v1.PromiseBase

exceptSync, getException, getState, getValue, sync, thenSync

Methods inherited from class java.lang.Object

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

Constructor Detail

PromiseRunnable

public PromiseRunnable()

PromiseRunnable

public PromiseRunnable(PromiseRunner runner)

PromiseRunnable

public PromiseRunnable(PromiseRunner runner,
                       java.util.function.Consumer<PromiseRunnable<T>> action)

Method Detail

getAction

public java.util.function.Consumer<PromiseRunnable<T>> getAction()

setAction

public PromiseRunnable<T> setAction(java.util.function.Consumer<PromiseRunnable<T>> action)
                             throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

getRunner

public PromiseRunner getRunner()

setRunner

public PromiseRunnable<T> setRunner(PromiseRunner runner)
                             throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

isRun

public boolean isRun()

setRun

public PromiseRunnable<T> setRun()

run

public PromiseRunnable<T> run()

reject

public PromiseRunnable<T> reject(java.lang.Throwable exception)
                          throws MutatedStateException,
                                 java.lang.NullPointerException

Overrides:

reject in class PromiseBase<T>

Throws:

MutatedStateException

java.lang.NullPointerException

fulfill

public PromiseRunnable<T> fulfill(T value)
                           throws SelfResolutionException,
                                  MutatedStateException

Overrides:

fulfill in class PromiseBase<T>

Throws:

SelfResolutionException

MutatedStateException

resolve

public PromiseRunnable<T> resolve(Promise<? extends T> promise)
                           throws SelfResolutionException,
                                  MutatedStateException

Description copied from class: PromiseBase

Resolve this promise with the same value/exception and state as another promise. Resolving null will fulfill this with null.

Note that this may happen asynchronously, subsequent calls to resolve may fail silently. Take this into consideration especially if exposing this method externally.

Circular references are not checked, but we do take care not to directly resolve this.

Overrides:

resolve in class PromiseBase<T>

Parameters:

promise - The promise to resolve.

Returns:

This promise.

Throws:

SelfResolutionException - If promise is this, or the promise is resolved to this.

MutatedStateException - If this was already resolved, at the time of this call. Not triggered immediately if promise is PENDING.

then

public <U> Promise<U> then(java.util.function.Function<? super T,? extends Promise<? extends U>> callback)

Description copied from interface: Promise

Specify a callback to be run on successful resolution FULFILLED of this, and return a new promise, that will resolve with the same state and value as the callback's returned promise, after the callback promise resolves. The input parameter will be the FULFILLED value of this.

The callback will be run as soon as possible (but not inline) if this is already FULFILLED.

If the callback returns a null value, then the returned promise will resolve as FULFILLED with value null.

If an exception is thrown within the callback, then the returned promise will be REJECTED, with that exception.

If this resolved with the REJECTED state, then the returned promise will reflect the state and value of this, and the callback will not be run.

Type Parameters:

U - The return type of the new promise, dictated by the callback promise's return type.

Parameters:

callback - The operation which will be performed if this resolves successfully.

Returns:

A promise which will resolve after the previous promise(s) AND any inner operations.

except

public Promise<T> except(java.util.function.Function<java.lang.Throwable,? extends Promise<? extends T>> callback)

Description copied from interface: Promise

Specify a callback to be run if this resolves with a failed state REJECTED, and return a new promise, that will resolve with the same state and value as the callback's returned promise, after the callback promise resolves. The input parameter will be the REJECTED value of this (a Throwable).

To preserve type safety, the returned type of promise within the callback is restricted to things which can be cast to the type of T, unlike Promise.then(Function), which can allow any type, due to the fact that the no-callback case will only ever result in a Throwable.

The callback will be run as soon as possible (but not inline) if this is already REJECTED.

If the callback returns a null value, then the returned promise will resolve as FULFILLED with value null.

If an exception is thrown within the callback, then the returned promise will be REJECTED, with that exception.

If this resolved with the FULFILLED state, then the returned promise will reflect the state and value of this, and the callback will not be run.

Parameters:

callback - The operation which will be performed if the promise resolves exceptionally.

Returns:

A promise which will resolve after the previous promise(s) AND any inner operations.

always

public <U> Promise<U> always(java.util.function.BiFunction<? super T,java.lang.Throwable,? extends Promise<? extends U>> callback)

Description copied from interface: Promise

Specify a callback that will always run on resolution, or as soon as possible if this is already in a resolved state. Returns a new promise, that will resolve with the same state and value as the callback's return value (a promise), after the returned promise resolves.

The right input parameter will be the REJECTED exception (not null), if this rejected, otherwise it can be assumed that the state was FULFILLED, and the left input parameter will be set, if the fulfillment value was non-null.

The callback will be run as soon as possible (but not inline) if this is already resolved.

If the callback returns a null value, then the returned promise will resolve as FULFILLED with value null.

If an exception is thrown within the callback, then the returned promise will be REJECTED, with that exception.

Type Parameters:

U - The return type of the new promise, dictated by the callback promise's return type.

Parameters:

callback - The operation to perform when the promise resolves.

Returns:

A promise which will resolve after the previous promise AND any inner operations.

then

public <U> Promise<U> then(java.util.function.BiConsumer<? super T,java.util.function.Consumer<? super U>> callback)

Description copied from interface: Promise

Specify a callback to be run on successful resolution FULFILLED of this, and return a new promise, that will fulfill with the value accepted within the callback, into it's second argument, a Consumer.

The callback will be run as soon as possible (but not inline) if this is already FULFILLED.

If no call is made to this second argument within the callback, then the resolved value of the returned promise will be null, and the state FULFILLED.

If this resolves as REJECTED callback will not be called, and the returned promise will reject with the same Throwable.

If an exception is thrown within the callback, then the returned promise will be REJECTED with that exception, provided that it has not already resolved.

For example:

     
         Promise<Integer> input = // some async operation which eventually fulfills with int(5)
         Promise<Integer> output = input.then((inputValue, fulfill) -> fulfill.accept(inputValue + 10));
         // will output 15
         System.out.println(output.thenSync());
     
 

Type Parameters:

U - The return type of the new promise.

Parameters:

callback - The operation which will be performed if the promise resolves successfully.

Returns:

A promise which will resolve after the previous promise AND any inner operations.

except

public Promise<T> except(java.util.function.BiConsumer<java.lang.Throwable,java.util.function.Consumer<? super T>> callback)

Description copied from interface: Promise

Specify a callback to be run if this resolves with a failed state REJECTED, and return a new promise, that will fulfill with the value accepted within the callback, into it's second argument, a Consumer.

To preserve type safety, the type of fulfillment value within the callback is restricted, to things which can be cast to the type of T, unlike Promise.then(BiConsumer), which can allow any type, due to the fact that the no-callback case will only ever result in a Throwable.

The callback will be run as soon as possible (but not inline) if this is already REJECTED.

If no call is made to this second argument within the callback, then the resolved value of the returned promise will be null, and the state FULFILLED.

If this resolves as FULFILLED callback will not be called, and the returned promise will fulfill with the same value.

If an exception is thrown within the callback, then the returned promise will be REJECTED with that exception, provided that it has not already resolved.

For example:

     
         Promise<Object> input = // some async operation which eventually rejects with an exception
         Promise<Object> output = input.except((exception, fulfill) -> fulfill.accept(exception));
         // will output the string representation of the FULFILLED exception originally REJECTED by input
         System.out.println(output.thenSync());
     
 

Parameters:

callback - The operation which will be performed if the promise resolves exceptionally.

Returns:

A promise which will resolve after the previous promise AND any inner operations.