io.atlassian.util.concurrent

Interface Promise<A>

All Superinterfaces:

Future<A>

All Known Subinterfaces:

Promises.SettablePromise<A>

public interface Promise<A>
extends Future<A>

A promise that presents a nicer interface to Future. It can be claimed without needing to catch checked exceptions, and it may be mapped to new types of Promise via the map(Function) and flatMap(Function) methods.

For instance, if you have a Promise<A> and you want to do some operation on the value (an A) you can use map(Function) to turn this into a Promise of some other type. Let's say you get back a Person and you really only need their surname:

 public Promise<String> fetchSurname(PersonId id) {
   Promise<Person> promise asyncClient.fetchPerson(id);
   return promise.map(new Function<Person, String>() {
     public String apply(Person p) {
       return p.surname();
     }
   };
 }
 

If you want to do some further asynchronous operation using the value, you can use flatMap(Function) to turn this into a Promise of some other type. Let's say you get back a Person and you really only need to perform a further query to get their address:

 public Promise<Address> fetchAddress(PersonId id) {
   Promise<Person> promise asyncClient.fetchPerson(id);
   return promise.flatMap(new Function<Person, Promise<Address>>() {
     public Promise<Address> apply(Person p) {
       return asyncClient.fetchAddress(p.addressId());
     }
   };
 }
 

Note that there are a number of handy utility functions for creating Promise objects on the Promises companion.

Cancelling a Promise that hasn't yet been completed will do it with a CancellationException and that will propagate to dependent Promises. But cancelling a dependent Promise will not cancel the original one.

Since:

2.4

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Promise.TryConsumer<A> Consumer interface to be called after a promise is fulfilled with a succesful value or a failure.

Method Summary

Modifier and Type	Method and Description
A	claim() Blocks the thread waiting for a result.
Promise<A>	done(Consumer<? super A> c) Registers a callback to be called when the promised object is available.
Promise<A>	fail(Consumer<Throwable> c) Registers a callback to be called when an exception is thrown.
<B> Promise<B>	flatMap(Function<? super A,? extends Promise<? extends B>> function) Transforms this promise from one type to another by way of a transformation function that returns a new Promise, leaving the strategy for that promise production up to the function.
<B> Promise<B>	fold(Function<Throwable,? extends B> handleThrowable, Function<? super A,? extends B> function) Transform this promise from one type to another, also providing a strategy for dealing with any exceptions encountered.
<B> Promise<B>	map(Function<? super A,? extends B> function) Transforms this Promise from one type to another by way of a transformation function.
Promise<A>	recover(Function<Throwable,? extends A> handleThrowable) Recover from an exception using the supplied exception strategy
Promise<A>	then(Promise.TryConsumer<? super A> callback) Registers a TryConsumer to handle both success and failure (exception) cases.

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Method Detail

claim

A claim()

Blocks the thread waiting for a result. Exceptions are thrown as runtime exceptions.

Returns:

The promised object

done

Promise<A> done(Consumer<? super A> c)

Registers a callback to be called when the promised object is available. May not be executed in the same thread as the caller.

Parameters:

c - The consumer to call with the result

Returns:

This object for chaining

fail

Promise<A> fail(Consumer<Throwable> c)

Registers a callback to be called when an exception is thrown. May not be executed in the same thread as the caller.

Parameters:

c - The consumer to call with the throwable

Returns:

This object for chaining

then

Promise<A> then(Promise.TryConsumer<? super A> callback)

Registers a TryConsumer to handle both success and failure (exception) cases. May not be executed in the same thread as the caller.

See Promises.compose(Consumer, Consumer)

Parameters:

callback - The future callback

Returns:

This object for chaining

map

<B> Promise<B> map(Function<? super A,? extends B> function)

Transforms this Promise from one type to another by way of a transformation function.

Type Parameters:

B - a B.

Parameters:

function - The transformation function

Returns:

A new promise resulting from the transformation

flatMap

<B> Promise<B> flatMap(Function<? super A,? extends Promise<? extends B>> function)

Transforms this promise from one type to another by way of a transformation function that returns a new Promise, leaving the strategy for that promise production up to the function.

Note this is known as flatMap as it first maps to a Promise<Promise<A>> and then flattens that out into a single layer Promise.

Type Parameters:

B - a B.

Parameters:

function - The transformation function to a new Promise value

Returns:

A new promise resulting from the transformation

recover

Promise<A> recover(Function<Throwable,? extends A> handleThrowable)

Recover from an exception using the supplied exception strategy

Parameters:

handleThrowable - rehabilitate the exception with a value of type B

Returns:

A new promise that will not throw an exception (unless handleThrowable itself threw).

fold

<B> Promise<B> fold(Function<Throwable,? extends B> handleThrowable,
                    Function<? super A,? extends B> function)

Transform this promise from one type to another, also providing a strategy for dealing with any exceptions encountered.

Type Parameters:

B - a B.

Parameters:

handleThrowable - rehabilitate the exception with a value of type B

function - mapping function

Returns:

A new promise resulting from the catamorphic transformation. This promise will not throw an exception (unless handleThrowable itself threw).