org.esbtools.eventhandler

Interface TransformableFuture<T>

All Superinterfaces:

Future<T>

All Known Implementing Classes:

NestedTransformableFuture, NestedTransformableFutureIgnoringReturn

public interface TransformableFuture<T>
extends Future<T>

An extension of Future which allows chaining FutureTransform functions onto its eventually computed result, returning new TransformableFutures.

Not a general purpose interface, this is entirely meant to optionally support integrating with Future-based APIs like DocumentEvent.lookupDocument() in collaboration with a Requester.

Method Summary

Modifier and Type	Method and Description
static <T> TransformableFuture<T>	immediate(T result)
static <T> TransformableFuture<T>	immediateFailed(Exception exception)
<U> TransformableFuture<U>	transformAsync(FutureTransform<T,TransformableFuture<U>> futureTransform) Creates a new Future which is backed by the Future returned from the provided futureTransform function.
TransformableFuture<Void>	transformAsyncIgnoringReturn(FutureTransform<T,TransformableFuture<?>> futureTransform) Like transformAsync(FutureTransform), except useful in cases where you intentionally do not care about the result value contained in the transform functions returned Future.
<U> TransformableFuture<U>	transformSync(FutureTransform<T,U> futureTransform) Creates a new Future which is completed immediately when this Future completes, with a value that is the result of applying the provided futureTransform function to this Future's result.
TransformableFuture<T>	whenDoneOrCancelled(FutureDoneCallback callback) An asynchronous "finally" block.

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Method Detail

immediate

static <T> TransformableFuture<T> immediate(T result)

immediateFailed

static <T> TransformableFuture<T> immediateFailed(Exception exception)

transformSync

<U> TransformableFuture<U> transformSync(FutureTransform<T,U> futureTransform)

Creates a new Future which is completed immediately when this Future completes, with a value that is the result of applying the provided futureTransform function to this Future's result.

Terminology inspired by Guava's Futures extensions.

Type Parameters:

U - The type of new result.

Parameters:

futureTransform - Function which accepts the result from this future and returns a new result or throws an exception if a result cannot be computed. This new result is what will be returned from the returned Future.

transformAsync

<U> TransformableFuture<U> transformAsync(FutureTransform<T,TransformableFuture<U>> futureTransform)

Creates a new Future which is backed by the Future returned from the provided futureTransform function.

Use this when you need to add a callback on an existing TransformableFuture which returns yet another Future, chaining several asynchronous actions together into one final result Future. If you just used transformSync(FutureTransform) you'd end up with a Future<Future<U>> (a future who's result is another future) which is difficult to work with. By using this API, the result Future is "unwrapped" and you get a more intuitive Future<U> to work with.

Terminology inspired by Guava's Futures extensions such as AsyncFunction.

Type Parameters:

U - The type of the result within the returned Future of the transform function.

Parameters:

futureTransform - Function which accepts the result from this future and returns either a new Future or null.

transformAsyncIgnoringReturn

TransformableFuture<Void> transformAsyncIgnoringReturn(FutureTransform<T,TransformableFuture<?>> futureTransform)

Like transformAsync(FutureTransform), except useful in cases where you intentionally do not care about the result value contained in the transform functions returned Future.

APIs like Message.process() may intentionally require the parameterized type of Future<Void> to clearly document that both the result of the Future is unused (we only care if it succeeded or not) and to prevent an implementor from accidentally returning a Future<Future> which would never have its result Future examined because the consumer is ignoring the return value. This would definitely be a bug.

whenDoneOrCancelled

TransformableFuture<T> whenDoneOrCancelled(FutureDoneCallback callback)

An asynchronous "finally" block.

Use to clean up resources or whatever finishing behavior that needs to happen whenever the future has a result or is cancelled.

If the future is already done or cancelled, the callback is called immediately.