com.atlassian.util.concurrent
Interface Promise<A>

All Superinterfaces:

Future<A>, com.google.common.util.concurrent.ListenableFuture<A>

All Known Implementing Classes:

ForwardingPromise

@Beta
public interface Promise<A>
extends com.google.common.util.concurrent.ListenableFuture<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.

Since:

2.4

Method Summary

A	claim() Blocks the thread waiting for a result.
Promise<A>	done(Effect<? super A> e) Registers a callback to be called when the promised object is available.
Promise<A>	fail(Effect<Throwable> e) Registers a callback to be called when an exception is thrown.
<B> Promise<B>	flatMap(com.google.common.base.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(com.google.common.base.Function<Throwable,? extends B> handleThrowable, com.google.common.base.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(com.google.common.base.Function<? super A,? extends B> function) Transforms this Promise from one type to another by way of a transformation function.
Promise<A>	recover(com.google.common.base.Function<Throwable,? extends A> handleThrowable) Recover from an exception using the supplied exception strategy
Promise<A>	then(com.google.common.util.concurrent.FutureCallback<? super A> callback) Registers a FutureCallback to handle both success and failure (exception) cases.

Methods inherited from interface com.google.common.util.concurrent.ListenableFuture

addListener

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(Effect<? super A> e)

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

Parameters:

e - The effect to perform with the result

Returns:

This object for chaining

fail

Promise<A> fail(Effect<Throwable> e)

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

Parameters:

e - The effect to perform with the throwable

Returns:

This object for chaining

then

Promise<A> then(com.google.common.util.concurrent.FutureCallback<? super A> callback)

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

See Promises.futureCallback(Effect, Effect) Promises.onSuccessDo(Effect) and Promises.onFailureDo(Effect) for easy ways of turning an Effect into a FutureCallback

Parameters:

callback - The future callback

Returns:

This object for chaining

map

<B> Promise<B> map(com.google.common.base.Function<? super A,? extends B> function)

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

Note: This is designed for cases in which the transformation is fast and lightweight, as the method is performed on the same thread as the thing producing this promise. For more details see the note on Futures.transform(Future, Function).

Parameters:

function - The transformation function

Returns:

A new promise resulting from the transformation

flatMap

<B> Promise<B> flatMap(com.google.common.base.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.

Parameters:

function - The transformation function to a new Promise value

Returns:

A new promise resulting from the transformation

recover

Promise<A> recover(com.google.common.base.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(com.google.common.base.Function<Throwable,? extends B> handleThrowable,
                    com.google.common.base.Function<? super A,? extends B> function)

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

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