com.darylteo.rx.promises.java

Class Promise<T>

java.lang.Object

com.darylteo.rx.promises.AbstractPromise<T>

com.darylteo.rx.promises.java.Promise<T>

All Implemented Interfaces:

rx.Observer<T>

public class Promise<T>
extends com.darylteo.rx.promises.AbstractPromise<T>

A Promise represents a request that will be fulfilled sometime in the future, most usually by an asynchrous task executed on the Vert.x Event Loop. It allows you to assign handlers to deal with the return results of asynchronus tasks, and to flatten "pyramids of doom" or "callback hell".

Promise Rules

• A Promise represents a value that is set in some future time (usually in another cycle of the event loop)
• Each promise has three components: onFulfilled, onRejected, and onFinally
• If the promise is fulfilled, onFulfilled is called with the value of the promise.
• If the promise cannot be fulfilled for some reason, it is then rejected. onRejected is called with the reason for the rejection
• A promise may be further deferred, at which point a new promise is provided. This can lead to a chain of promises.
• If a promise if fulfilled, but onFulfilled is not provided, then the promise is fulfilled with the same value.
• If a promise is rejected, but onRejected is not provided, then the next promise is rejected with the same reason
• If onFinally is provided, it is resolved first before either fulfilling or rejecting the next promise (see previous two points)
• Either onFulfilled, or onRejected may return a new promise (i.e. a repromise) . When this happens, the subsequently created promise will be fulfilled with the value of the repromise when it is eventually fulfilled.

Type-Safe Rules

• All the type-safety rules are related to the output type of onFulfilled.
• If onFulfilled returns type T, then onRejected must either return T, or null. This is facilitated through the use of PromiseFunction, and PromiseAction respectively.
• As per the previous rule, if onFulfilled is an PromiseAction, then onRejected must also be an PromiseAction.
• You may use a RepromiseFunction in place of a PromiseFunction that returns T.
• If onFulfilled is not provided, it is assumed that it is defined in a future handler. As such, onRejected may not change the return type.
• onFinally must be a Repromise or an Action. It does not accept any values. This is facilitated through the use of FinallyFunction and FinallyAction respectively.

Nested Class Summary

Nested classes/interfaces inherited from class com.darylteo.rx.promises.AbstractPromise

com.darylteo.rx.promises.AbstractPromise.STATE

Constructor Summary

Constructors

Constructor and Description
Promise()
Promise(rx.Observable<T> source)

Method Summary

Methods

Modifier and Type	Method and Description
Promise<T>	fail(PromiseAction<java.lang.Exception> onRejected)
Promise<T>	fail(PromiseFunction<java.lang.Exception,T> onRejected)
Promise<T>	fail(RepromiseFunction<java.lang.Exception,T> onRejected)
Promise<T>	fin(FinallyAction onFinally)
Promise<T>	fin(FinallyFunction<?> onFinally)
protected <O> Promise<O>	promise(rx.functions.Function onFulfilled, rx.functions.Function onRejected, rx.functions.Function onFinally)
Promise<java.lang.Void>	then(PromiseAction<T> onFulfilled)
Promise<java.lang.Void>	then(PromiseAction<T> onFulfilled, PromiseAction<java.lang.Exception> onRejected)
<O> Promise<O>	then(PromiseFunction<T,O> onFulfilled)
<O> Promise<O>	then(PromiseFunction<T,O> onFulfilled, PromiseAction<java.lang.Exception> onRejected)
<O> Promise<O>	then(PromiseFunction<T,O> onFulfilled, PromiseFunction<java.lang.Exception,O> onRejected)
<O> Promise<O>	then(PromiseFunction<T,O> onFulfilled, RepromiseFunction<java.lang.Exception,O> onRejected)
<O> Promise<O>	then(RepromiseFunction<T,O> onFulfilled)
<O> Promise<O>	then(RepromiseFunction<T,O> onFulfilled, PromiseAction<java.lang.Exception> onRejected)
<O> Promise<O>	then(RepromiseFunction<T,O> onFulfilled, PromiseFunction<java.lang.Exception,O> onRejected)
<O> Promise<O>	then(RepromiseFunction<T,O> onFulfilled, RepromiseFunction<java.lang.Exception,O> onRejected)

Methods inherited from class com.darylteo.rx.promises.AbstractPromise

_then, become, fulfill, getReason, getState, getValue, isFulfilled, isPending, isRejected, onCompleted, onError, onNext, reject, reject, toObservable

Methods inherited from class java.lang.Object

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

Constructor Detail

Promise

public Promise()

Promise

public Promise(rx.Observable<T> source)

Method Detail

then

public <O> Promise<O> then(PromiseFunction<T,O> onFulfilled)

then

public <O> Promise<O> then(RepromiseFunction<T,O> onFulfilled)

then

public Promise<java.lang.Void> then(PromiseAction<T> onFulfilled)

then

public <O> Promise<O> then(PromiseFunction<T,O> onFulfilled,
                  PromiseFunction<java.lang.Exception,O> onRejected)

then

public <O> Promise<O> then(PromiseFunction<T,O> onFulfilled,
                  RepromiseFunction<java.lang.Exception,O> onRejected)

then

public <O> Promise<O> then(PromiseFunction<T,O> onFulfilled,
                  PromiseAction<java.lang.Exception> onRejected)

then

public <O> Promise<O> then(RepromiseFunction<T,O> onFulfilled,
                  PromiseFunction<java.lang.Exception,O> onRejected)

then

public <O> Promise<O> then(RepromiseFunction<T,O> onFulfilled,
                  RepromiseFunction<java.lang.Exception,O> onRejected)

then

public <O> Promise<O> then(RepromiseFunction<T,O> onFulfilled,
                  PromiseAction<java.lang.Exception> onRejected)

then

public Promise<java.lang.Void> then(PromiseAction<T> onFulfilled,
                           PromiseAction<java.lang.Exception> onRejected)

fail

public Promise<T> fail(PromiseFunction<java.lang.Exception,T> onRejected)

fail

public Promise<T> fail(RepromiseFunction<java.lang.Exception,T> onRejected)

fail

public Promise<T> fail(PromiseAction<java.lang.Exception> onRejected)

fin

public Promise<T> fin(FinallyFunction<?> onFinally)

fin

public Promise<T> fin(FinallyAction onFinally)

promise

protected <O> Promise<O> promise(rx.functions.Function onFulfilled,
                     rx.functions.Function onRejected,
                     rx.functions.Function onFinally)