CheckedFuture
Date: 2016-05-24

com.google.common.util.concurrent

## Interface CheckedFuture<V,X extends java.lang.Exception>

- All Superinterfaces:
    java.util.concurrent.Future<V>, ListenableFuture<V>
  All Known Implementing Classes:
    AbstractCheckedFuture, ForwardingCheckedFuture, ForwardingCheckedFuture.SimpleForwardingCheckedFuture

      @Beta
      @GwtCompatible
      public interface CheckedFuture<V,X extends java.lang.Exception>
      extends ListenableFuture<V>

  A `CheckedFuture` is a `ListenableFuture` that includes versions of the `get` methods that can throw a checked exception. This makes it easier to create a future that executes logic which can throw an exception.

  Warning: We recommend against using `CheckedFuture` in new projects. `CheckedFuture` is difficult to build libraries atop. `CheckedFuture` ports of methods like `Futures.transformAsync(com.google.common.util.concurrent.ListenableFuture<I>, com.google.common.util.concurrent.AsyncFunction<? super I, ? extends O>)` have historically had bugs, and some of these bugs are necessary, unavoidable consequences of the `CheckedFuture` API. Additionally, `CheckedFuture` encourages users to take exceptions from one thread and rethrow them in another, producing confusing stack traces.

  A common implementation is `Futures.immediateCheckedFuture(V)`.

  Implementations of this interface must adapt the exceptions thrown by `Future#get()`: `CancellationException`, `ExecutionException` and `InterruptedException` into the type specified by the `X` type parameter.

  This interface also extends the ListenableFuture interface to allow listeners to be added. This allows the future to be used as a normal `Future` or as an asynchronous callback mechanism as needed. This allows multiple callbacks to be registered for a particular task, and the future will guarantee execution of all listeners when the task completes.

  For a simpler alternative to CheckedFuture, consider accessing Future values with `Futures.getChecked()`.

  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `V` | `checkedGet()` Exception checking version of `Future.get()` that will translate `InterruptedException`, `CancellationException` and `ExecutionException` into application-specific exceptions.
    `V` | `checkedGet(long timeout, java.util.concurrent.TimeUnit unit)` Exception checking version of `Future.get(long, TimeUnit)` that will translate `InterruptedException`, `CancellationException` and `ExecutionException` into application-specific exceptions.

    - ### 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

    - #### checkedGet

          V checkedGet()
                       throws X extends java.lang.Exception

      Exception checking version of `Future.get()` that will translate `InterruptedException`, `CancellationException` and `ExecutionException` into application-specific exceptions.
      Returns:
        the result of executing the future.
      Throws:
        `X` - on interruption, cancellation or execution exceptions.
        `X extends java.lang.Exception`

    - #### checkedGet

          V checkedGet(long timeout,
                     java.util.concurrent.TimeUnit unit)
                       throws java.util.concurrent.TimeoutException,
                              X extends java.lang.Exception

      Exception checking version of `Future.get(long, TimeUnit)` that will translate `InterruptedException`, `CancellationException` and `ExecutionException` into application-specific exceptions. On timeout this method throws a normal `TimeoutException`.
      Returns:
        the result of executing the future.
      Throws:
        `java.util.concurrent.TimeoutException` - if retrieving the result timed out.
        `X` - on interruption, cancellation or execution exceptions.
        `X extends java.lang.Exception`