-
Notifications
You must be signed in to change notification settings - Fork 0
Promises
A Promise is a stateful event processor that accepts either a single value or an error. Once either of these values has been accepted, the Promise
is considered complete.
When a Promise
is populated with a value, the onSuccess
Consumers are invoked. When populated with an error, the onError
Consumers are invoked. When either a success or an error is set, the onComplete
Consumers are invoked.
Promises aren’t created directly. They’re meant to handle future values when they are available. Promises only provide methods for setting Consumers—you can’t publish a value to a Promise. Instead you use a Deferred
, which produces a Promise
from its compose()
method. The Deferred has an accept()
method on it which is used to populate the Promise.
Promises also need to be aware of a Dispatcher
to use when publishing events. There are static helper methods on the Promises class for creating them.
Environment env = new Environment();
// Create a deferred for accepting future values Deferred<String, Promise<String>> deferred = Promises.<String>defer() .env(env) .dispatcher(RING_BUFFER) .get();
// Set a Consumer for the value deferred.compose().onSuccess(new Consumer<String>() { public void accept(String s) { // handle string when available } });
// When a value is available, set it on the Deferred deferred.accept("Hello World!");
Promises can also be created in a success or error state right away if the value is already known. This is useful when a Promise should be returned from a method but the value (or error) is immediately available.
// Create a completed Promise Promise<String> p = Promises.success("Hello World!").get();
// Consumers assigned on a complete Promise will be submitted immediately p.onSuccess(new Consumer<String>() { public void accept(String s) { // handle string when available } });
// Create a Promise in an error state Promise<String> p = Promises.<String>error(new IllegalStateException()).get();
A key feature of Promises is that they are composable. The map(Function<T,V> fn) function can be used to assign a Function<T,V> that will transform the result value T
into a V
and populate a new Promise<V>
with the return value.
Deferred<String, Promise<String>> deferred = Promises.<String>defer().get();
// Transform the String into a Float using map() Promise<Float> p2 = p1.map(new Function<String, Float>() { public Float apply(String s) { return Float.parseFloat(s); } }); p2.onSuccess(new Consumer<Float>() { public void accept(Float f) { // handle transformed value } });
deferred.accept("12.2");
A Promise can also be filtered. A call to the filter(Predicate<T> p) method will return a new Promise<T>
that will, depending on the Predicate check, either be poplated with the result value or be in error if the Predicate test fails.
Deferred<Float, Promise<Float>> deferred = Promises.<Float>defer().get();
// Filter based on a Predicate Promise<Float> p2 = p1.filter(new Predicate<Float>() { public boolean test(Float f) { return f > 100f; } }); p2.then( // onSuccess new Consumer<Float>() { public void accept(Float f) { // handle value } }, // onError new Consumer<Throwable>() { public void accept(Throwable t) { // predicate test failed } } );
deferred.accept("12.2");
Since Promises are designed to be stateful, they also provide methods for getting the value of the Promise. Promises are Suppliers, so a call to the get()
method will return the current value of the Promise, whether it is complete or not (Promises also provide methods for checking whether the Promise is complete, a success, or in error).
Promises can block the calling thread waiting for a result. Call one of the await()
methods to block until a value is available or the Promise is notified of an error.
Note that the zero-arg await()
method does not block indefinitely. It will only block for a period of milliseconds as defined in the System property reactor.await.defaultTimeout
. This value is 30 seconds by default. It can be changed by setting this property in the META-INF/reactor/default.properties
(or any other active profileName.properties
).
Home | Usage Guide | Tuples | Streams | Promises | API Javadoc