me.joeycumines.javapromises.v1

Class PromiseStage<T>

java.lang.Object

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

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

All Implemented Interfaces:

Promise<T>

public class PromiseStage<T>
extends PromiseBase<T>

This Promise implementation supports the wrapping of the Java 8 interface, CompletionStage. As the callee controls how new dependant Promise objects are created, said implementation will also control the threading, etc, of dependant stages.

The promise state and value is retrieved by way of callback, meaning that, provided the CompletionStage implementation is correct, this promise will always be resolved before resolving promises registered with then, etc.

This class is provided more as a way to enable inter-operation with other libraries, then as a recommended way to use promises.

The thread-safe implementation of state is implemented by PromiseBase.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.concurrent.Executor	executor
protected java.util.concurrent.CompletionStage<T>	stage

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

lock

Constructor Summary

Constructors

Constructor and Description
PromiseStage(java.util.concurrent.CompletionStage<T> stage)
PromiseStage(java.util.concurrent.CompletionStage<T> stage, java.util.concurrent.Executor executor)

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.
java.util.concurrent.Executor	getExecutor()
java.util.concurrent.CompletionStage<T>	getStage()
<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.
static <T> Promise<T>	wrap(java.util.concurrent.CompletionStage<T> stage, java.util.concurrent.Executor executor, Promise<? extends T> promise) Use a completed CompletionStage as a base, create a new PromiseStage, that will resolve with the same state and value as the provided Promise.

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

exceptSync, fulfill, getException, getState, getValue, reject, resolve, sync, thenSync

Methods inherited from class java.lang.Object

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

Field Detail

stage

protected final java.util.concurrent.CompletionStage<T> stage

executor

protected final java.util.concurrent.Executor executor

Constructor Detail

PromiseStage

public PromiseStage(java.util.concurrent.CompletionStage<T> stage)

PromiseStage

public PromiseStage(java.util.concurrent.CompletionStage<T> stage,
                    java.util.concurrent.Executor executor)

Method Detail

getStage

public java.util.concurrent.CompletionStage<T> getStage()

getExecutor

public java.util.concurrent.Executor getExecutor()

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.

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

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.

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.

wrap

public static <T> Promise<T> wrap(java.util.concurrent.CompletionStage<T> stage,
                                  java.util.concurrent.Executor executor,
                                  Promise<? extends T> promise)

Use a completed CompletionStage as a base, create a new PromiseStage, that will resolve with the same state and value as the provided Promise.

A null stage or promise will result in a NullPointerException.

If the stage provided is not completed, and will never complete, then this thread will hang.

Type Parameters:

T - The type of the returned promise.

Parameters:

stage - A SUCCESSFULLY COMPLETED completion stage.

executor - The executor to create the new PromiseStage with. Can be null.

promise - The promise to wrap.

Returns:

A new promise that will resolve the same as the provided one that is an instance of PromiseStage.