com.aquenos.cassandra.pvarchiver.server.util

Class FutureUtils

java.lang.Object

com.aquenos.cassandra.pvarchiver.server.util.FutureUtils

public abstract class FutureUtils
extends Object

Helper methods for dealing with futures without having to take care of checked exceptions.

Author:

Sebastian Marsching

Constructor Summary

Constructors

Constructor and Description
FutureUtils()

Method Summary

Modifier and Type	Method and Description
static <T> ListenableFuture<T>	asListenableFuture(ListenableFuture<? extends T> future) Wraps a ListenableFuture in a ListenableFuture.
static <T> ListenableFuture<T>	asSpringListenableFuture(ListenableFuture<? extends T> future) Wraps a ListenableFuture in a ListenableFuture.
static <V> void	forward(ListenableFuture<? extends V> source, SettableFuture<? super V> target) Forwards the result of a listenable future to another (settable) future.
static <T> T	getUnchecked(Future<? extends T> future) Returns the result of calling the future's get() method.
static <I,O> ListenableFuture<O>	transform(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> successFunction, AsyncFunction<? super Throwable,? extends O> errorFunction) Transforms a listenable future using the specified asynchronous functions.
static <I,O> ListenableFuture<O>	transform(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> successFunction, AsyncFunction<? super Throwable,? extends O> errorFunction, Executor executor) Transforms a listenable future using the specified asynchronous functions.
static <I,O> ListenableFuture<O>	transform(ListenableFuture<I> input, Function<? super I,? extends O> successFunction, Function<? super Throwable,? extends O> errorFunction) Transforms a listenable future using the specified synchronous functions.
static <I,O> ListenableFuture<O>	transform(ListenableFuture<I> input, Function<? super I,? extends O> successFunction, Function<? super Throwable,? extends O> errorFunction, Executor executor) Transforms a listenable future using the specified synchronous functions.
static ListenableFuture<Void>	transformAnyToVoid(ListenableFuture<?> future) Transforms a listenable future that returns any type to a listenable future that returns Void.

Methods inherited from class java.lang.Object

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

Constructor Detail

FutureUtils

public FutureUtils()

Method Detail

asListenableFuture

public static <T> ListenableFuture<T> asListenableFuture(ListenableFuture<? extends T> future)

Wraps a ListenableFuture in a ListenableFuture. This way, a listenable future that was created by code using Spring can be used with code that expects a listenable future that is compatible with Guava. All methods from the Future interface are directly delegated to the original future. The method for adding callbacks registers callbacks internally that are executed when the original future executes its callbacks.

Type Parameters:

T - type of the value provided by the returned future.

Parameters:

future - listenable future from the Spring library.

Returns:

listenable future compatible with Guava, that wraps the specified future.

Throws:

NullPointerException - if future is null.

asSpringListenableFuture

public static <T> ListenableFuture<T> asSpringListenableFuture(ListenableFuture<? extends T> future)

Wraps a ListenableFuture in a ListenableFuture. This way, a listenable future that was created by code using Guava can be used with code that expects a listenable future that is compatible with Spring. All methods from the Future interface are directly delegated to the original future. The methods for adding callbacks register callbacks internally that are executed when the original future executes its callbacks.

Type Parameters:

T - type of the value provided by the returned future.

Parameters:

future - listenable future from the Guava library.

Returns:

listenable future compatible with Spring, that wraps the specified future.

Throws:

NullPointerException - if future is null.

forward

public static <V> void forward(ListenableFuture<? extends V> source,
                               SettableFuture<? super V> target)

Forwards the result of a listenable future to another (settable) future. When the source future succeeds, the target future succeeds with the result value of the source future. When the source future fails, the target future fails with the exception of the source future.

When the source future is cancelled successfully (and it throws a CancellationException), the target future is cancelled as well. If the target future is cancelled, however, this does not have any effect on the source future.

Type Parameters:

V - type of the value provided by the futures. The type returned by the source must be compatible with the type expected by the target.

Parameters:

source - listenable future that provides the source (result or error).

target - settable future that is updated with the result or error of the source future, once the source future completes.

getUnchecked

public static <T> T getUnchecked(Future<? extends T> future)

Returns the result of calling the future's get() method.

If the get() method throws an ExecutionException, the cause attached to this exception is extracted. If the cause is a RuntimeException or an Error, the cause is rethrown. If it is a checked exception, it is wrapped in a RuntimeException and thrown. If the cause is null, the ExecutionException is wrapped in a RuntimeException and thrown.

If the get() method throws an InterruptedException, the current thread's interruption state is restored by calling Thread.interrupt() and the InterruptedException is wrapped in a RuntimeException and thrown.

Type Parameters:

T - type of the value provided by the future.

Parameters:

future - future from which the result shall be retrieved.

Returns:

return value of Future.get().

Throws:

NullPointerException - if future is null.

RuntimeException - if Future.get() throws an exception.

transform

public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
                                                  Function<? super I,? extends O> successFunction,
                                                  Function<? super Throwable,? extends O> errorFunction)

Transforms a listenable future using the specified synchronous functions. This is very similar to Futures.transform(ListenableFuture, Function, Executor), but in addition to providing a transformation of a result value, exceptions thrown by the original future can be transformed as well.

If the specified future completes successfully, the successFunction is called with the value of the original future and the value returned by that function is provided by the returned future. If the specified future completes with an exception, the errorFunction is called, passing the exception. This function can then convert this exception to a value that is returned by the future returned by this method.

The successFunction and errorFunction are executed in the thread that executes the listeners attached to the original input future. Therefore, the functions should only perform short, non-blocking tasks.

If the successFunction or the errorFunction throw an exception, that exception is thrown by the future returned by this method.

The implementation tries to keep the cancellation state between the original future and the transformed future in sync. It cancels the returned future when it detects that the original future has been cancelled and it tries to cancel the original future when the returned future is cancelled. Cancellation of the original future does not result in the errorFunction being called.

Type Parameters:

I - type of the value provided by the input future.

O - type of the value provided by the output (resulting) future. Typically, this type is inferred from the returned types of the successFunction and errorFunction.

Parameters:

input - future to be transformed.

successFunction - function called when the input future completes successfully. The function gets the result of the input future passed to it.

errorFunction - function called when the input future completes with an exception. The functions gets the exception thrown by the input future passed to it.

Returns:

future that completes when the successFunction or errorFunction completes and providing the value or exception returned by that function.

Throws:

NullPointerException - if any of the arguments are null.

transform

public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
                                                  Function<? super I,? extends O> successFunction,
                                                  Function<? super Throwable,? extends O> errorFunction,
                                                  Executor executor)

Transforms a listenable future using the specified synchronous functions. This is very similar to Futures.transform(ListenableFuture, Function, Executor), but in addition to providing a transformation of a result value, exceptions thrown by the original future can be transformed as well.

If the specified future completes successfully, the successFunction is called with the value of the original future and the value returned by that function is provided by the returned future. If the specified future completes with an exception, the errorFunction is called, passing the exception. This function can then convert this exception to a value that is returned by the future returned by this method.

The successFunction and errorFunction are executed through the means of the specified executor.

If the successFunction or the errorFunction throw an exception, that exception is thrown by the future returned by this method.

The implementation tries to keep the cancellation state between the original future and the transformed future in sync. It cancels the returned future when it detects that the original future has been cancelled and it tries to cancel the original future when the returned future is cancelled. Cancellation of the original future does not result in the errorFunction being called.

Type Parameters:

I - type of the value provided by the input future.

O - type of the value provided by the output (resulting) future. Typically, this type is inferred from the returned types of the successFunction and errorFunction.

Parameters:

input - future to be transformed.

successFunction - function called when the input future completes successfully. The function gets the result of the input future passed to it.

errorFunction - function called when the input future completes with an exception. The functions gets the exception thrown by the input future passed to it.

executor - executor used to run the sucessFunction and errorFunction.

Returns:

future that completes when the successFunction or errorFunction completes and providing the value or exception returned by that function.

Throws:

NullPointerException - if any of the arguments are null.

transform

public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
                                                  AsyncFunction<? super I,? extends O> successFunction,
                                                  AsyncFunction<? super Throwable,? extends O> errorFunction)

Transforms a listenable future using the specified asynchronous functions. This is very similar to Futures.transform(ListenableFuture, AsyncFunction), but in addition to providing a transformation of a result value, exceptions thrown by the original future can be transformed as well.

If the specified future completes successfully, the successFunction is called with the value of the original future and the value returned by that function is provided by the returned future. If the specified future completes with an exception, the errorFunction is called, passing the exception. This function can then convert this exception to a value that is returned by the future returned by this method.

The successFunction and errorFunction are executed in the thread that executes the listeners attached to the original input future. Therefore, the functions should only perform short, non-blocking tasks.

If the successFunction or the errorFunction throw an exception, that exception is thrown by the future returned by this method.

The implementation tries to keep the cancellation state between the original future and the transformed future in sync. It cancels the returned future when it detects that the original future has been cancelled and it tries to cancel the original future when the returned future is cancelled. Cancellation of the original future does not result in the errorFunction being called.

Type Parameters:

I - type of the value provided by the input future.

O - type of the value provided by the output (resulting) future. Typically, this type is inferred from the returned types of the successFunction and errorFunction.

Parameters:

input - future to be transformed.

successFunction - function called when the input future completes successfully. The function gets the result of the input future passed to it.

errorFunction - function called when the input future completes with an exception. The functions gets the exception thrown by the input future passed to it.

Returns:

future that completes when the future returned by the successFunction or errorFunction completes and providing the value or exception returned by that future.

Throws:

NullPointerException - if any of the arguments are null.

transform

public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
                                                  AsyncFunction<? super I,? extends O> successFunction,
                                                  AsyncFunction<? super Throwable,? extends O> errorFunction,
                                                  Executor executor)

Transforms a listenable future using the specified asynchronous functions. This is very similar to Futures.transform(ListenableFuture, AsyncFunction, Executor), but in addition to providing a transformation of a result value, exceptions thrown by the original future can be transformed as well.

If the specified future completes successfully, the successFunction is called with the value of the original future and the value returned by that function is provided by the returned future. If the specified future completes with an exception, the errorFunction is called, passing the exception. This function can then convert this exception to a value that is returned by the future returned by this method.

The successFunction and errorFunction are executed through the means of the specified executor.

If the successFunction or the errorFunction throw an exception, that exception is thrown by the future returned by this method.

The implementation tries to keep the cancellation state between the original future and the transformed future in sync. It cancels the returned future when it detects that the original future has been cancelled and it tries to cancel the original future when the returned future is cancelled. Cancellation of the original future does not result in the errorFunction being called.

Type Parameters:

I - type of the value provided by the input future.

O - type of the value provided by the output (resulting) future. Typically, this type is inferred from the returned types of the successFunction and errorFunction.

Parameters:

input - future to be transformed.

successFunction - function called when the input future completes successfully. The function gets the result of the input future passed to it.

errorFunction - function called when the input future completes with an exception. The functions gets the exception thrown by the input future passed to it.

executor - executor used to run the sucessFunction and errorFunction.

Returns:

future that completes when the future returned by the successFunction or errorFunction completes and providing the value or exception returned by that future.

Throws:

NullPointerException - if any of the arguments are null.

transformAnyToVoid

public static ListenableFuture<Void> transformAnyToVoid(ListenableFuture<?> future)

Transforms a listenable future that returns any type to a listenable future that returns Void. The future returned will always return a value of null. Such a future is typically desirable, if one has a future that returns an unknown type (or access to the actual result is not supposed to be exposed in the API) and one only wants to use the future to check when the operation has finished and to get any error state associated with the operation.

The implementation tries to keep the cancellation state between the original future and the transformed future in sync. It cancels the returned future when it detects that the original future has been cancelled and it tries to cancel the original future when the returned future is cancelled.

Parameters:

future - listenable future of any type.

Returns:

listenable future returning null that finishes when the passed future finishes. If the passed future throws an exception, this future will throw the same exception.