reactor.core.composable

Class Promise<T>

java.lang.Object

reactor.core.composable.Composable<T>

reactor.core.composable.Promise<T>

Type Parameters:

T - the type of the value that will be made available

All Implemented Interfaces:

Flushable<T>, Pipeline<T>, Supplier<T>

public class Promise<T>
extends Composable<T>
implements Supplier<T>

A Promise is a stateful event processor that accepts a single value or error. In addition to getting or awaiting the value, consumers can be registered to be notified of notified an error, a value, or both. A promise also provides methods for composing actions with the future value much like a Stream. However, where a Stream can process many values, a Promise processes only one value or error.

Reactor's Promise implementation is modeled largely after the Promises/A+ specification, which defines a number of methods and potential actions for promises.

See Also:

Promises/A+ specification

Field Summary

Fields inherited from class reactor.core.composable.Composable

END_EVENT

Fields inherited from interface reactor.core.action.Flushable

FLUSH_EVENT

Constructor Summary

Constructors

Constructor and Description
Promise(Observable observable, Environment env, Composable<?> parent) Creates a new unfulfilled promise.
Promise(java.lang.Throwable error, Observable observable, Environment env) Creates a new promise that has failed with the given error.
Promise(T value, Observable observable, Environment env) Creates a new promise that has been fulfilled with the given value.

Method Summary

Modifier and Type	Method and Description
Promise<T>	add(Action<T> operation) Consume events with the passed Action
T	await() Block the calling thread, waiting for the completion of this Promise.
T	await(long timeout, java.util.concurrent.TimeUnit unit) Block the calling thread for the specified time, waiting for the completion of this Promise.
Promise<T>	connect(Composable<T> composable) Attach another Composable to this one that will cascade the value or error received by this Composable into the next.
Promise<T>	connectErrors(Composable<?> composable) Forward any error to the argument.
Promise<T>	consume(Consumer<T> consumer) Attach a Consumer to this Composable that will consume any values accepted by this Composable.
Promise<T>	consume(java.lang.Object key, Observable observable) Pass values accepted by this Composable into the given Observable, notifying with the given key.
Promise<T>	consumeFlush(Flushable<?> action) Consume flush with the passed Flushable
protected void	errorAccepted(java.lang.Throwable error)
Promise<java.lang.Boolean>	filter() Evaluate each accepted boolean value.
Promise<java.lang.Boolean>	filter(Composable<java.lang.Boolean> elseComposable) Evaluate each accepted boolean value.
Promise<T>	filter(Function<T,java.lang.Boolean> fn) Evaluate each accepted value against the given predicate Function.
Promise<T>	filter(Predicate<T> p) Evaluate each accepted value against the given Predicate.
Promise<T>	filter(Predicate<T> p, Composable<T> elseComposable) Evaluate each accepted value against the given Predicate.
Promise<T>	flush() Flush any cached or unprocessed values through this Stream.
T	get() Returns the value that completed this promise.
boolean	isComplete() Indicates whether this Promise has been completed with either an error or a value
boolean	isError() Indicates whether this Promise has been completed with an error.
boolean	isPending() Indicates whether this Promise has yet to be completed with a value or an error.
boolean	isSuccess() Indicates whether this Promise has been successfully completed a value.
<V> Promise<V>	map(Function<T,V> fn) Assign the given Function to transform the incoming value T into a V and pass it into another Composable.
<V,C extends Composable<V>> Promise<V>	mapMany(Function<T,C> fn) Assign the given Function to transform the incoming value T into a Composable<V> and pass it into another Composable.
Promise<T>	merge(Composable<T>... composables) this#connect(Composable) all the passed to this Composable, merging values streams into the current pipeline.
protected <V> Promise<V>	newComposable() Create a Composable that is compatible with the subclass of Composable in use.
Promise<T>	onComplete(Consumer<Promise<T>> onComplete) Assign a Consumer that will either be invoked later, when the Promise is completed by either setting a value or propagating an error, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.
Promise<T>	onError(Consumer<java.lang.Throwable> onError) Assign a Consumer that will either be invoked later, when the Promise is completed with an error, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.
Promise<T>	onSuccess(Consumer<T> onSuccess) Assign a Consumer that will either be invoked later, when the Promise is successfully completed with a value, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.
Promise<T>	propagate(Supplier<T> supplier) Create a new Composable whose values will be generated from .
java.lang.Throwable	reason() Return the error (if any) that has completed this Promise.
Promise<T>	then(Consumer<T> onSuccess, Consumer<java.lang.Throwable> onError) Assign both a success Consumer and an optional (possibly null) error Consumer.
<V> Promise<V>	then(Function<T,V> onSuccess, Consumer<java.lang.Throwable> onError) Assign a success Function that will either be invoked later, when the Promise is successfully completed with a value, or, if this Promise has already been fulfilled, the function is immediately scheduled to be executed on the current Dispatcher.
Promise<T>	timeout(long timeout) Flush the parent if any or the current composable otherwise when the last notification occurred before milliseconds.
Promise<T>	timeout(long timeout, Timer timer) Flush the parent if any or the current composable otherwise when the last notification occurred before milliseconds.
java.lang.String	toString()
protected void	valueAccepted(T value)
<E extends java.lang.Throwable> Promise<T>	when(java.lang.Class<E> exceptionType, Consumer<E> onError) Assign an error handler to exceptions of the given type.

Methods inherited from class reactor.core.composable.Composable

connectValues, consumeErrorAndFlush, consumeEvent, debug, getAcceptKey, getAcceptSelector, getEnvironment, getError, getFlush, getObservable, getParent

Methods inherited from class java.lang.Object

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

Constructor Detail

Promise

public Promise(@Nullable
               Observable observable,
               @Nullable
               Environment env,
               @Nullable
               Composable<?> parent)

Creates a new unfulfilled promise.

The observable is used when notifying the Promise's consumers, determining the thread on which they are called. The given env is used to determine the default await timeout. If env is null the default await timeout will be 30 seconds. This Promise will consumer errors from its parent such that if the parent completes in error then so too will this Promise.

Parameters:

observable - The Observable to use to call Consumers

env - The Environment, if any, from which the default await timeout is obtained

parent - The parent, if any, from which errors are consumed

Promise

public Promise(T value,
               @Nullable
               Observable observable,
               @Nullable
               Environment env)

Creates a new promise that has been fulfilled with the given value.

The observable is used when notifying the Promise's consumers. The given env is used to determine the default await timeout. If env is null the default await timeout will be 30 seconds.

Parameters:

value - The value that fulfills the promise

observable - The Observable to use to call Consumers

env - The Environment, if any, from which the default await timeout is obtained

Promise

public Promise(java.lang.Throwable error,
               @Nonnull
               Observable observable,
               @Nullable
               Environment env)

Creates a new promise that has failed with the given error.

The observable is used when notifying the Promise's consumers, determining the thread on which they are called. The given env is used to determine the default await timeout. If env is null the default await timeout will be 30 seconds.

Parameters:

error - The error the completed the promise

env - The Environment, if any, from which the default await timeout is obtained

observable - The Observable to use to call Consumers

Method Detail

onComplete

public Promise<T> onComplete(@Nonnull
                             Consumer<Promise<T>> onComplete)

Assign a Consumer that will either be invoked later, when the Promise is completed by either setting a value or propagating an error, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.

Parameters:

onComplete - the completion Consumer

Returns:

this

onSuccess

public Promise<T> onSuccess(@Nonnull
                            Consumer<T> onSuccess)

Assign a Consumer that will either be invoked later, when the Promise is successfully completed with a value, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.

Parameters:

onSuccess - the success Consumer

Returns:

this

onError

public Promise<T> onError(@Nullable
                          Consumer<java.lang.Throwable> onError)

Assign a Consumer that will either be invoked later, when the Promise is completed with an error, or, if this Promise has already been fulfilled, is immediately scheduled to be executed on the current Dispatcher.

Parameters:

onError - the error Consumer

Returns:

this

then

public Promise<T> then(@Nonnull
                       Consumer<T> onSuccess,
                       @Nullable
                       Consumer<java.lang.Throwable> onError)

Assign both a success Consumer and an optional (possibly null) error Consumer.

Parameters:

onSuccess - the success Consumer

onError - the error Consumer

Returns:

this

See Also:

onSuccess(Consumer), onError(Consumer)

then

public <V> Promise<V> then(@Nonnull
                           Function<T,V> onSuccess,
                           @Nullable
                           Consumer<java.lang.Throwable> onError)

Assign a success Function that will either be invoked later, when the Promise is successfully completed with a value, or, if this Promise has already been fulfilled, the function is immediately scheduled to be executed on the current Dispatcher.

A new Promise is returned that will be populated by result of the given transformation Function that turns the incoming T into a V.

Type Parameters:

V - the type of the value returned by the transformation Function

Parameters:

onSuccess - the success transformation Function

onError - the error Consumer

Returns:

a new Promise that will be populated by the result of the transformation Function

isComplete

public boolean isComplete()

Indicates whether this Promise has been completed with either an error or a value

Returns:

true if this Promise is complete, false otherwise.

See Also:

isPending()

isPending

public boolean isPending()

Indicates whether this Promise has yet to be completed with a value or an error.

Returns:

true if this Promise is still pending, false otherwise.

See Also:

isComplete()

isSuccess

public boolean isSuccess()

Indicates whether this Promise has been successfully completed a value.

Returns:

true if this Promise is successful, false otherwise.

isError

public boolean isError()

Indicates whether this Promise has been completed with an error.

Returns:

true if this Promise was completed with an error, false otherwise.

await

public T await()
        throws java.lang.InterruptedException

Block the calling thread, waiting for the completion of this Promise. A default timeout as specified in Reactor's Environment properties using the key reactor.await.defaultTimeout is used. The default is 30 seconds. If the promise is completed with an error a RuntimeException that wraps the error is thrown.

Returns:

the value of this Promise or null if the timeout is reached and the Promise has not completed

Throws:

java.lang.InterruptedException - if the thread is interruped while awaiting completion

java.lang.RuntimeException - if the promise is completed with an error

await

public T await(long timeout,
               java.util.concurrent.TimeUnit unit)
        throws java.lang.InterruptedException

Block the calling thread for the specified time, waiting for the completion of this Promise. If the promise is completed with an error a RuntimeException that wraps the error is thrown.

Parameters:

timeout - the timeout value

unit - the TimeUnit of the timeout value

Returns:

the value of this Promise or null if the timeout is reached and the Promise has not completed

Throws:

java.lang.InterruptedException - if the thread is interruped while awaiting completion

get

public T get()

Returns the value that completed this promise. Returns null if the promise has not been completed. If the promise is completed with an error a RuntimeException that wraps the error is thrown.

Specified by:

get in interface Supplier<T>

Returns:

the value that completed the promise, or null if it has not been completed

Throws:

java.lang.RuntimeException - if the promise was completed with an error

reason

public java.lang.Throwable reason()

Return the error (if any) that has completed this Promise. Returns null if the promise has not been completed, or was completed with a value.

Returns:

the error (if any)

consume

public Promise<T> consume(@Nonnull
                          Consumer<T> consumer)

Description copied from class: Composable

Attach a Consumer to this Composable that will consume any values accepted by this Composable.

Overrides:

consume in class Composable<T>

Parameters:

consumer - the conumer to invoke on each value

Returns:

this

connect

public Promise<T> connect(@Nonnull
                          Composable<T> composable)

Description copied from class: Composable

Attach another Composable to this one that will cascade the value or error received by this Composable into the next.

Overrides:

connect in class Composable<T>

Parameters:

composable - the next Composable to cascade events to

Returns:

this

consume

public Promise<T> consume(@Nonnull
                          java.lang.Object key,
                          @Nonnull
                          Observable observable)

Description copied from class: Composable

Pass values accepted by this Composable into the given Observable, notifying with the given key.

Overrides:

consume in class Composable<T>

Parameters:

key - the key to notify on

observable - the Observable to notify

Returns:

this

mapMany

public <V,C extends Composable<V>> Promise<V> mapMany(@Nonnull
                                                      Function<T,C> fn)

Description copied from class: Composable

Assign the given Function to transform the incoming value T into a Composable<V> and pass it into another Composable.

Overrides:

mapMany in class Composable<T>

Type Parameters:

V - the type of the return value of the transformation function

Parameters:

fn - the transformation function

Returns:

a new Composable containing the transformed values

when

public <E extends java.lang.Throwable> Promise<T> when(@Nonnull
                                                       java.lang.Class<E> exceptionType,
                                                       @Nonnull
                                                       Consumer<E> onError)

Description copied from class: Composable

Assign an error handler to exceptions of the given type.

Overrides:

when in class Composable<T>

Type Parameters:

E - type of the exception to handle

Parameters:

exceptionType - the type of exceptions to handle

onError - the error handler for each exception

Returns:

this

map

public <V> Promise<V> map(@Nonnull
                          Function<T,V> fn)

Description copied from class: Composable

Assign the given Function to transform the incoming value T into a V and pass it into another Composable.

Overrides:

map in class Composable<T>

Type Parameters:

V - the type of the return value of the transformation function

Parameters:

fn - the transformation function

Returns:

a new Composable containing the transformed values

filter

public Promise<T> filter(@Nonnull
                         Predicate<T> p)

Description copied from class: Composable

Evaluate each accepted value against the given Predicate. If the predicate test succeeds, the value is passed into the new Composable. If the predicate test fails, the value is ignored.

Overrides:

filter in class Composable<T>

Parameters:

p - the Predicate to test values against

Returns:

a new Composable containing only values that pass the predicate test

filter

public Promise<T> filter(@Nonnull
                         Predicate<T> p,
                         Composable<T> elseComposable)

Description copied from class: Composable

Evaluate each accepted value against the given Predicate. If the predicate test succeeds, the value is passed into the new Composable. If the predicate test fails, the value is propagated into the elseComposable.

Overrides:

filter in class Composable<T>

Parameters:

p - the Predicate to test values against

elseComposable - the optional Composable to pass rejected values

Returns:

a new Composable containing only values that pass the predicate test

filter

public Promise<java.lang.Boolean> filter()

Description copied from class: Composable

Evaluate each accepted boolean value. If the predicate test succeeds, the value is passed into the new Composable. If the predicate test fails, the value is ignored.

Overrides:

filter in class Composable<T>

Returns:

a new Composable containing only values that pass the predicate test

filter

public Promise<java.lang.Boolean> filter(@Nonnull
                                         Composable<java.lang.Boolean> elseComposable)

Description copied from class: Composable

Evaluate each accepted boolean value. If the predicate test succeeds, the value is passed into the new Composable. the value is propagated into the .

Overrides:

filter in class Composable<T>

Parameters:

elseComposable - the Composable to test values against

Returns:

a new Composable containing only values that pass the predicate test

filter

public Promise<T> filter(@Nonnull
                         Function<T,java.lang.Boolean> fn)

Description copied from class: Composable

Evaluate each accepted value against the given predicate Function. If the predicate test succeeds, the value is passed into the new Composable. If the predicate test fails, an exception is propagated into the new Composable.

Overrides:

filter in class Composable<T>

Parameters:

fn - the predicate Function to test values against

Returns:

a new Composable containing only values that pass the predicate test

merge

public Promise<T> merge(Composable<T>... composables)

Description copied from class: Composable

this#connect(Composable) all the passed to this Composable, merging values streams into the current pipeline.

Overrides:

merge in class Composable<T>

Parameters:

composables - the the composables to connect

Returns:

this composable

timeout

public Promise<T> timeout(long timeout)

Description copied from class: Composable

Flush the parent if any or the current composable otherwise when the last notification occurred before milliseconds. Timeout is run on the environment root timer.

Overrides:

timeout in class Composable<T>

Parameters:

timeout - the timeout in milliseconds between two notifications on this composable

Returns:

this Composable

timeout

public Promise<T> timeout(long timeout,
                          Timer timer)

Description copied from class: Composable

Flush the parent if any or the current composable otherwise when the last notification occurred before milliseconds. Timeout is run on the provided .

Overrides:

timeout in class Composable<T>

Parameters:

timeout - the timeout in milliseconds between two notifications on this composable

timer - the reactor timer to run the timeout on

Returns:

this Composable

propagate

public Promise<T> propagate(Supplier<T> supplier)

Description copied from class: Composable

Create a new Composable whose values will be generated from . Every time flush is triggered, is called.

Overrides:

propagate in class Composable<T>

Parameters:

supplier - the supplier to drain

Returns:

a new Composable whose values are generated on each flush

flush

public Promise<T> flush()

Description copied from class: Composable

Flush any cached or unprocessed values through this Stream.

Specified by:

flush in interface Flushable<T>

Overrides:

flush in class Composable<T>

Returns:

this

add

public Promise<T> add(Action<T> operation)

Description copied from class: Composable

Consume events with the passed Action

Specified by:

add in interface Pipeline<T>

Overrides:

add in class Composable<T>

Parameters:

operation - the action listening for values

Returns:

this

consumeFlush

public Promise<T> consumeFlush(Flushable<?> action)

Description copied from interface: Pipeline

Consume flush with the passed Flushable

Specified by:

consumeFlush in interface Pipeline<T>

Overrides:

consumeFlush in class Composable<T>

Parameters:

action - the action listening for flush

Returns:

this

connectErrors

public Promise<T> connectErrors(Composable<?> composable)

Description copied from class: Composable

Forward any error to the argument.

Overrides:

connectErrors in class Composable<T>

Parameters:

composable - the target sink for errores and flushes

Returns:

this

newComposable

protected <V> Promise<V> newComposable()

Description copied from class: Composable

Create a Composable that is compatible with the subclass of Composable in use.

Specified by:

newComposable in class Composable<T>

Type Parameters:

V - type the Composable handles

Returns:

a new Composable compatible with the current subclass.

errorAccepted

protected void errorAccepted(java.lang.Throwable error)

valueAccepted

protected void valueAccepted(T value)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object