ClosingFuture (Guava: Google Core Libraries for Java HEAD-jre-SNAPSHOT API)

java.lang.Object
- com.google.common.util.concurrent.ClosingFuture<V>

Type Parameters:

V - the type of the value of this step
```
@Beta
 @DoNotMock(value="Use ClosingFuture.from(Futures.immediate*Future)")
public final class ClosingFuture<V>
extends Object
```
A step in a pipeline of an asynchronous computation. When the last step in the computation is complete, some objects captured during the computation are closed.
A pipeline of ClosingFutures is a tree of steps. Each step represents either an asynchronously-computed intermediate value, or else an exception that indicates the failure or cancellation of the operation so far. The only way to extract the value or exception from a step is by declaring that step to be the last step of the pipeline. Nevertheless, we refer to the "value" of a successful step or the "result" (value or exception) of any step.
1. A pipeline starts at its leaf step (or steps), which is created from either a callable block or a ListenableFuture.
2. Each other step is derived from one or more input steps. At each step, zero or more objects can be captured for later closing.
3. There is one last step (the root of the tree), from which you can extract the final result of the computation. After that result is available (or the computation fails), all objects captured by any of the steps in the pipeline are closed.
Starting a pipeline
Start a ClosingFuture pipeline from a callable block that may capture objects for later closing. To start a pipeline from a ListenableFuture that doesn't create resources that should be closed later, you can use from(ListenableFuture) instead.
Derived steps
A ClosingFuture step can be derived from one or more input ClosingFuture steps in ways similar to FluentFutures:
- by transforming the value from a successful input step,
- by catching the exception from a failed input step, or
- by combining the results of several input steps.
Each derivation can capture the next value or any intermediate objects for later closing.
A step can be the input to at most one derived step. Once you transform its value, catch its exception, or combine it with others, you cannot do anything else with it, including declare it to be the last step of the pipeline.
Transforming
To derive the next step by asynchronously applying a function to an input step's value, call transform(ClosingFunction, Executor) or transformAsync(AsyncClosingFunction, Executor) on the input step.
Catching
To derive the next step from a failed input step, call catching(Class, ClosingFunction, Executor) or catchingAsync(Class, AsyncClosingFunction, Executor) on the input step.
Combining
To derive a ClosingFuture from two or more input steps, pass the input steps to whenAllComplete(Iterable) or whenAllSucceed(Iterable) or its overloads.
Cancelling
Any step in a pipeline can be cancelled, even after another step has been derived, with the same semantics as cancelling a Future. In addition, a successfully cancelled step will immediately start closing all objects captured for later closing by it and by its input steps.
Ending a pipeline
Each ClosingFuture pipeline must be ended. To end a pipeline, decide whether you want to close the captured objects automatically or manually.
Automatically closing
You can extract a Future that represents the result of the last step in the pipeline by calling finishToFuture(). When that final Future is done, all objects captured by all steps in the pipeline will be closed.
```
 FluentFuture<UserName> userName =
     ClosingFuture.submit(
             closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor),
             executor)
         .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor)
         .transform((closer, result) -> result.get("userName"), directExecutor())
         .catching(DBException.class, e -> "no user", directExecutor())
         .finishToFuture();
 
```
In this example, when the userName Future is done, the transaction and the query result cursor will both be closed, even if the operation is cancelled or fails.
Manually closing
If you want to close the captured objects manually, after you've used the final result, call finishToValueAndCloser(ValueAndCloserConsumer, Executor) to get an object that holds the final result. You then call ClosingFuture.ValueAndCloser.closeAsync() to close the captured objects.
```
     ClosingFuture.submit(
             closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor),
             executor)
     .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor)
     .transform((closer, result) -> result.get("userName"), directExecutor())
     .catching(DBException.class, e -> "no user", directExecutor())
     .finishToValueAndCloser(
         valueAndCloser -> this.userNameValueAndCloser = valueAndCloser, executor);

 // later
 try { // get() will throw if the operation failed or was cancelled.
   UserName userName = userNameValueAndCloser.get();
   // do something with userName
 } finally {
   userNameValueAndCloser.closeAsync();
 }
 
```
In this example, when userNameValueAndCloser.closeAsync() is called, the transaction and the query result cursor will both be closed, even if the operation is cancelled or fails.
Note that if you don't call closeAsync(), the captured objects will not be closed. The automatic-closing approach described above is safer.
Since:

NEXT

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`ClosingFuture.AsyncClosingFunction<T,U>` A function from an input to a `ClosingFuture` of a result.
`static interface`	`ClosingFuture.ClosingCallable<V>` An operation that computes a result.
`static interface`	`ClosingFuture.ClosingFunction<T,U>` A function from an input to a result.
`static class`	`ClosingFuture.Combiner` A builder of a `ClosingFuture` step that is derived from more than one input step.
`static class`	`ClosingFuture.Combiner2<V1,V2>` A generic `ClosingFuture.Combiner` that lets you use a lambda or method reference to combine two `ClosingFuture`s.
`static class`	`ClosingFuture.Combiner3<V1,V2,V3>` A generic `ClosingFuture.Combiner` that lets you use a lambda or method reference to combine three `ClosingFuture`s.
`static class`	`ClosingFuture.Combiner4<V1,V2,V3,V4>` A generic `ClosingFuture.Combiner` that lets you use a lambda or method reference to combine four `ClosingFuture`s.
`static class`	`ClosingFuture.Combiner5<V1,V2,V3,V4,V5>` A generic `ClosingFuture.Combiner` that lets you use a lambda or method reference to combine five `ClosingFuture`s.
`static class`	`ClosingFuture.DeferredCloser` An object that can capture objects to be closed later, when a `ClosingFuture` pipeline is done.
`static class`	`ClosingFuture.Peeker` An object that can return the value of the `ClosingFuture`s that are passed to `whenAllComplete(Iterable)` or `whenAllSucceed(Iterable)`.
`static class`	`ClosingFuture.ValueAndCloser<V>` An object that holds the final result of an asynchronous `ClosingFuture` operation and allows the user to close all the closeable objects that were captured during it for later closing.
`static interface`	`ClosingFuture.ValueAndCloserConsumer<V>` Represents an operation that accepts a `ClosingFuture.ValueAndCloser` for the last step in a `ClosingFuture` pipeline.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`cancel(boolean mayInterruptIfRunning)` Attempts to cancel execution of this step.
`<X extends Throwable> ClosingFuture<V>`	`catching(Class<X> exceptionType, ClosingFuture.ClosingFunction<? super X,? extends V> fallback, Executor executor)` Returns a new `ClosingFuture` pipeline step derived from this one by applying a function to its exception if it is an instance of a given exception type.
`<X extends Throwable> ClosingFuture<V>`	`catchingAsync(Class<X> exceptionType, ClosingFuture.AsyncClosingFunction<? super X,? extends V> fallback, Executor executor)` Returns a new `ClosingFuture` pipeline step derived from this one by applying a function that returns a `ClosingFuture` to its exception if it is an instance of a given exception type.
`static <C extends Object & AutoCloseable> ClosingFuture<C>`	`eventuallyClosing(ListenableFuture<C> future, Executor closingExecutor)` Deprecated. Creating `Future`s of closeable types is dangerous in general because the underlying value may never be closed if the `Future` is canceled after its operation begins. Consider replacing code that creates `ListenableFuture`s of closeable types, including those that pass them to this method, with `submit(ClosingCallable, Executor)` in order to ensure that resources do not leak. Or, to start a pipeline with a `ListenableFuture` that doesn't create values that should be closed, use `from(com.google.common.util.concurrent.ListenableFuture<V>)`.
`protected void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`FluentFuture<V>`	`finishToFuture()` Marks this step as the last step in the `ClosingFuture` pipeline.
`void`	`finishToValueAndCloser(ClosingFuture.ValueAndCloserConsumer<? super V> consumer, Executor executor)` Marks this step as the last step in the `ClosingFuture` pipeline.
`static <V> ClosingFuture<V>`	`from(ListenableFuture<V> future)` Starts a `ClosingFuture` pipeline with a `ListenableFuture`.
`ListenableFuture<?>`	`statusFuture()` Returns a future that finishes when this step does.
`static <V> ClosingFuture<V>`	`submit(ClosingFuture.ClosingCallable<V> callable, Executor executor)` Starts a `ClosingFuture` pipeline by submitting a callable block to an executor.
`String`	`toString()` Returns a string representation of the object.
`<U> ClosingFuture<U>`	`transform(ClosingFuture.ClosingFunction<? super V,U> function, Executor executor)` Returns a new `ClosingFuture` pipeline step derived from this one by applying a function to its value.
`<U> ClosingFuture<U>`	`transformAsync(ClosingFuture.AsyncClosingFunction<? super V,U> function, Executor executor)` Returns a new `ClosingFuture` pipeline step derived from this one by applying a function that returns a `ClosingFuture` to its value.
`static ClosingFuture.Combiner`	`whenAllComplete(ClosingFuture<?> future1, ClosingFuture<?>... moreFutures)` Starts specifying how to combine `ClosingFuture`s into a single pipeline.
`static ClosingFuture.Combiner`	`whenAllComplete(Iterable<? extends ClosingFuture<?>> futures)` Starts specifying how to combine `ClosingFuture`s into a single pipeline.
`static ClosingFuture.Combiner`	`whenAllSucceed(ClosingFuture<?> future1, ClosingFuture<?> future2, ClosingFuture<?> future3, ClosingFuture<?> future4, ClosingFuture<?> future5, ClosingFuture<?> future6, ClosingFuture<?>... moreFutures)` Starts specifying how to combine `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static <V1,V2> ClosingFuture.Combiner2<V1,V2>`	`whenAllSucceed(ClosingFuture<V1> future1, ClosingFuture<V2> future2)` Starts specifying how to combine two `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static <V1,V2,V3> ClosingFuture.Combiner3<V1,V2,V3>`	`whenAllSucceed(ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3)` Starts specifying how to combine three `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static <V1,V2,V3,V4> ClosingFuture.Combiner4<V1,V2,V3,V4>`	`whenAllSucceed(ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3, ClosingFuture<V4> future4)` Starts specifying how to combine four `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static <V1,V2,V3,V4,V5> ClosingFuture.Combiner5<V1,V2,V3,V4,V5>`	`whenAllSucceed(ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3, ClosingFuture<V4> future4, ClosingFuture<V5> future5)` Starts specifying how to combine five `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static ClosingFuture.Combiner`	`whenAllSucceed(Iterable<? extends ClosingFuture<?>> futures)` Starts specifying how to combine `ClosingFuture`s into a single pipeline, assuming they all succeed.
`static <V,U> ClosingFuture.AsyncClosingFunction<V,U>`	`withoutCloser(AsyncFunction<V,U> function)` Returns an `ClosingFuture.AsyncClosingFunction` that applies an `AsyncFunction` to an input, ignoring the DeferredCloser and returning a `ClosingFuture` derived from the returned `ListenableFuture`.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - submit
```
public static <V> ClosingFuture<V> submit(ClosingFuture.ClosingCallable<V> callable,
                                          Executor executor)
```
    Starts a ClosingFuture pipeline by submitting a callable block to an executor.
    
    Throws:
    
    RejectedExecutionException - if the task cannot be scheduled for execution
  - from
```
public static <V> ClosingFuture<V> from(ListenableFuture<V> future)
```
    Starts a ClosingFuture pipeline with a ListenableFuture.
    future's value will not be closed when the pipeline is done even if V implements Closeable. In order to start a pipeline with a value that will be closed when the pipeline is done, use submit(ClosingCallable, Executor) instead.
  - eventuallyClosing
```
@Deprecated
public static <C extends Object & AutoCloseable> ClosingFuture<C> eventuallyClosing(ListenableFuture<C> future,
                                                                                                Executor closingExecutor)
```
    Deprecated. Creating Futures of closeable types is dangerous in general because the underlying value may never be closed if the Future is canceled after its operation begins. Consider replacing code that creates ListenableFutures of closeable types, including those that pass them to this method, with submit(ClosingCallable, Executor) in order to ensure that resources do not leak. Or, to start a pipeline with a ListenableFuture that doesn't create values that should be closed, use from(com.google.common.util.concurrent.ListenableFuture<V>).
    
    Starts a ClosingFuture pipeline with a ListenableFuture.
    If future succeeds, its value will be closed (using closingExecutor) when the pipeline is done, even if the pipeline is canceled or fails.
    Cancelling the pipeline will not cancel future, so that the pipeline can access its value in order to close it.
    
    Parameters:
    
    future - the future to create the ClosingFuture from. For discussion of the future's result type C, see DeferredCloser#eventuallyClose(Closeable, Executor).
    
    closingExecutor - the future's result will be closed on this executor
  - whenAllComplete
```
public static ClosingFuture.Combiner whenAllComplete(Iterable<? extends ClosingFuture<?>> futures)
```
    Starts specifying how to combine ClosingFutures into a single pipeline.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the futures, or if any has already been finished
  - whenAllComplete
```
public static ClosingFuture.Combiner whenAllComplete(ClosingFuture<?> future1,
                                                     ClosingFuture<?>... moreFutures)
```
    Starts specifying how to combine ClosingFutures into a single pipeline.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - whenAllSucceed
```
public static ClosingFuture.Combiner whenAllSucceed(Iterable<? extends ClosingFuture<?>> futures)
```
    Starts specifying how to combine ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the futures, or if any has already been finished
  - whenAllSucceed
```
public static <V1,V2> ClosingFuture.Combiner2<V1,V2> whenAllSucceed(ClosingFuture<V1> future1,
                                                                    ClosingFuture<V2> future2)
```
    Starts specifying how to combine two ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    Calling this method allows you to use lambdas or method references typed with the types of the input ClosingFutures.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - whenAllSucceed
```
public static <V1,V2,V3> ClosingFuture.Combiner3<V1,V2,V3> whenAllSucceed(ClosingFuture<V1> future1,
                                                                          ClosingFuture<V2> future2,
                                                                          ClosingFuture<V3> future3)
```
    Starts specifying how to combine three ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    Calling this method allows you to use lambdas or method references typed with the types of the input ClosingFutures.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - whenAllSucceed
```
public static <V1,V2,V3,V4> ClosingFuture.Combiner4<V1,V2,V3,V4> whenAllSucceed(ClosingFuture<V1> future1,
                                                                                ClosingFuture<V2> future2,
                                                                                ClosingFuture<V3> future3,
                                                                                ClosingFuture<V4> future4)
```
    Starts specifying how to combine four ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    Calling this method allows you to use lambdas or method references typed with the types of the input ClosingFutures.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - whenAllSucceed
```
public static <V1,V2,V3,V4,V5> ClosingFuture.Combiner5<V1,V2,V3,V4,V5> whenAllSucceed(ClosingFuture<V1> future1,
                                                                                      ClosingFuture<V2> future2,
                                                                                      ClosingFuture<V3> future3,
                                                                                      ClosingFuture<V4> future4,
                                                                                      ClosingFuture<V5> future5)
```
    Starts specifying how to combine five ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    Calling this method allows you to use lambdas or method references typed with the types of the input ClosingFutures.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - whenAllSucceed
```
public static ClosingFuture.Combiner whenAllSucceed(ClosingFuture<?> future1,
                                                    ClosingFuture<?> future2,
                                                    ClosingFuture<?> future3,
                                                    ClosingFuture<?> future4,
                                                    ClosingFuture<?> future5,
                                                    ClosingFuture<?> future6,
                                                    ClosingFuture<?>... moreFutures)
```
    Starts specifying how to combine ClosingFutures into a single pipeline, assuming they all succeed. If any fail, the resulting pipeline will fail.
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from any of the arguments, or if any has already been finished
  - statusFuture
```
public ListenableFuture<?> statusFuture()
```
    Returns a future that finishes when this step does. Calling get() on the returned future returns null if the step is successful or throws the same exception that would be thrown by calling finishToFuture().get() if this were the last step. Calling cancel() on the returned future has no effect on the ClosingFuture pipeline.
    statusFuture differs from most methods on ClosingFuture: You can make calls to statusFuture in addition to the call you make to finishToFuture() or a derivation method on the same instance. This is important because calling statusFuture alone does not provide a way to close the pipeline.
  - transform
```
public <U> ClosingFuture<U> transform(ClosingFuture.ClosingFunction<? super V,U> function,
                                      Executor executor)
```
    Returns a new ClosingFuture pipeline step derived from this one by applying a function to its value. The function can use a ClosingFuture.DeferredCloser to capture objects to be closed when the pipeline is done.
    If this ClosingFuture fails, the function will not be called, and the derived ClosingFuture will be equivalent to this one.
    If the function throws an exception, that exception is used as the result of the derived ClosingFuture.
    Example usage:
```
 ClosingFuture<List<Row>> rowsFuture =
     queryFuture.transform((closer, result) -> result.getRows(), executor);
 
```
    When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor) documentation. All its warnings about heavyweight listeners are also applicable to heavyweight functions passed to this method.
    After calling this method, you may not call finishToFuture(), finishToValueAndCloser(ValueAndCloserConsumer, Executor), or any other derivation method on this ClosingFuture.
    Parameters:
    
    function - transforms the value of this step to the value of the derived step
    
    executor - executor to run the function in
    
    Returns:
    
    the derived step
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from this one, or if this ClosingFuture has already been finished
  - transformAsync
```
public <U> ClosingFuture<U> transformAsync(ClosingFuture.AsyncClosingFunction<? super V,U> function,
                                           Executor executor)
```
    Returns a new ClosingFuture pipeline step derived from this one by applying a function that returns a ClosingFuture to its value. The function can use a ClosingFuture.DeferredCloser to capture objects to be closed when the pipeline is done (other than those captured by the returned ClosingFuture).
    If this ClosingFuture succeeds, the derived one will be equivalent to the one returned by the function.
    If this ClosingFuture fails, the function will not be called, and the derived ClosingFuture will be equivalent to this one.
    If the function throws an exception, that exception is used as the result of the derived ClosingFuture. But if the exception is thrown after the function creates a ClosingFuture, then none of the closeable objects in that ClosingFuture will be closed.
    Usage guidelines for this method:
    - Use this method only when calling an API that returns a ListenableFuture or a ClosingFuture. If possible, prefer calling transform(ClosingFunction, Executor) instead, with a function that returns the next value directly.
    - Call closer.eventuallyClose() for every closeable object this step creates in order to capture it for later closing.
    - Return a ClosingFuture. To turn a ListenableFuture into a ClosingFuture call from(ListenableFuture).
    - In case this step doesn't create new closeables, you can adapt an API that returns a ListenableFuture to return a ClosingFuture by wrapping it with a call to withoutCloser(AsyncFunction)
    Example usage:
```
 // Result.getRowsClosingFuture() returns a ClosingFuture.
 ClosingFuture<List<Row>> rowsFuture =
     queryFuture.transformAsync((closer, result) -> result.getRowsClosingFuture(), executor);

 // Result.writeRowsToOutputStreamFuture() returns a ListenableFuture that resolves to the
 // number of written rows. openOutputFile() returns a FileOutputStream (which implements
 // Closeable).
 ClosingFuture<Integer> rowsFuture2 =
     queryFuture.transformAsync(
         (closer, result) -> {
           FileOutputStream fos = closer.eventuallyClose(openOutputFile(), closingExecutor);
           return ClosingFuture.from(result.writeRowsToOutputStreamFuture(fos));
      },
      executor);

 // Result.getRowsFuture() returns a ListenableFuture (no new closeables are created).
 ClosingFuture<List<Row>> rowsFuture3 =
     queryFuture.transformAsync(withoutCloser(Result::getRowsFuture), executor);

 
```
    When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor) documentation. All its warnings about heavyweight listeners are also applicable to heavyweight functions passed to this method. (Specifically, directExecutor functions should avoid heavyweight operations inside AsyncClosingFunction.apply. Any heavyweight operations should occur in other threads responsible for completing the returned ClosingFuture.)
    After calling this method, you may not call finishToFuture(), finishToValueAndCloser(ValueAndCloserConsumer, Executor), or any other derivation method on this ClosingFuture.
    Parameters:
    
    function - transforms the value of this step to a ClosingFuture with the value of the derived step
    
    executor - executor to run the function in
    
    Returns:
    
    the derived step
    
    Throws:
    
    IllegalStateException - if a ClosingFuture has already been derived from this one, or if this ClosingFuture has already been finished
  - withoutCloser
```
public static <V,U> ClosingFuture.AsyncClosingFunction<V,U> withoutCloser(AsyncFunction<V,U> function)
```
    Returns an ClosingFuture.AsyncClosingFunction that applies an AsyncFunction to an input, ignoring the DeferredCloser and returning a ClosingFuture derived from the returned ListenableFuture.
    Use this method to pass a transformation to transformAsync(AsyncClosingFunction, Executor) or to catchingAsync(Class, AsyncClosingFunction, Executor) as long as it meets these conditions:
    - It does not need to capture any Closeable objects by calling DeferredCloser#eventuallyClose(Closeable, Executor).
    - It returns a ListenableFuture.
    Example usage:
```
 // Result.getRowsFuture() returns a ListenableFuture.
 ClosingFuture<List<Row>> rowsFuture =
     queryFuture.transformAsync(withoutCloser(Result::getRowsFuture), executor);
 
```
    Parameters:
    
    function - transforms the value of a ClosingFuture step to a ListenableFuture with the value of a derived step
  - catching
```
public <X extends Throwable> ClosingFuture<V> catching(Class<X> exceptionType,
                                                       ClosingFuture.ClosingFunction<? super X,? extends V> fallback,
                                                       Executor executor)
```
    Returns a new ClosingFuture pipeline step derived from this one by applying a function to its exception if it is an instance of a given exception type. The function can use a ClosingFuture.DeferredCloser to capture objects to be closed when the pipeline is done.
    If this ClosingFuture succeeds or fails with a different exception type, the function will not be called, and the derived ClosingFuture will be equivalent to this one.
    If the function throws an exception, that exception is used as the result of the derived ClosingFuture.
    Example usage:
```
 ClosingFuture<QueryResult> queryFuture =
     queryFuture.catching(
         QueryException.class, (closer, x) -> Query.emptyQueryResult(), executor);
 
```
    When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor) documentation. All its warnings about heavyweight listeners are also applicable to heavyweight functions passed to this method.
    After calling this method, you may not call finishToFuture(), finishToValueAndCloser(ValueAndCloserConsumer, Executor), or any other derivation method on this ClosingFuture.
    Parameters:
    
    exceptionType - the exception type that triggers use of fallback. The exception type is matched against this step's exception. "This step's exception" means the cause of the ExecutionException thrown by Future.get() on the Future underlying this step or, if get() throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.
    
    fallback - the function to be called if this step fails with the expected exception type. The function's argument is this step's exception. "This step's exception" means the cause of the ExecutionException thrown by Future.get() on the Future underlying this step or, if get() throws a different kind of exception, that exception itself.
    
    executor - the executor that runs fallback if the input fails
  - catchingAsync
```
public <X extends Throwable> ClosingFuture<V> catchingAsync(Class<X> exceptionType,
                                                            ClosingFuture.AsyncClosingFunction<? super X,? extends V> fallback,
                                                            Executor executor)
```
    Returns a new ClosingFuture pipeline step derived from this one by applying a function that returns a ClosingFuture to its exception if it is an instance of a given exception type. The function can use a ClosingFuture.DeferredCloser to capture objects to be closed when the pipeline is done (other than those captured by the returned ClosingFuture).
    If this ClosingFuture fails with an exception of the given type, the derived ClosingFuture will be equivalent to the one returned by the function.
    If this ClosingFuture succeeds or fails with a different exception type, the function will not be called, and the derived ClosingFuture will be equivalent to this one.
    If the function throws an exception, that exception is used as the result of the derived ClosingFuture. But if the exception is thrown after the function creates a ClosingFuture, then none of the closeable objects in that ClosingFuture will be closed.
    Usage guidelines for this method:
    - Use this method only when calling an API that returns a ListenableFuture or a ClosingFuture. If possible, prefer calling catching(Class, ClosingFunction, Executor) instead, with a function that returns the next value directly.
    - Call closer.eventuallyClose() for every closeable object this step creates in order to capture it for later closing.
    - Return a ClosingFuture. To turn a ListenableFuture into a ClosingFuture call from(ListenableFuture).
    - In case this step doesn't create new closeables, you can adapt an API that returns a ListenableFuture to return a ClosingFuture by wrapping it with a call to withoutCloser(AsyncFunction)
    Example usage:
```
 // Fall back to a secondary input stream in case of IOException.
 ClosingFuture<InputStream> inputFuture =
     firstInputFuture.catchingAsync(
         IOException.class, (closer, x) -> secondaryInputStreamClosingFuture(), executor);
 
 }
```
    When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor) documentation. All its warnings about heavyweight listeners are also applicable to heavyweight functions passed to this method. (Specifically, directExecutor functions should avoid heavyweight operations inside AsyncClosingFunction.apply. Any heavyweight operations should occur in other threads responsible for completing the returned ClosingFuture.)
    After calling this method, you may not call finishToFuture(), finishToValueAndCloser(ValueAndCloserConsumer, Executor), or any other derivation method on this ClosingFuture.
    Parameters:
    
    exceptionType - the exception type that triggers use of fallback. The exception type is matched against this step's exception. "This step's exception" means the cause of the ExecutionException thrown by Future.get() on the Future underlying this step or, if get() throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.
    
    fallback - the function to be called if this step fails with the expected exception type. The function's argument is this step's exception. "This step's exception" means the cause of the ExecutionException thrown by Future.get() on the Future underlying this step or, if get() throws a different kind of exception, that exception itself.
    
    executor - the executor that runs fallback if the input fails
  - finishToFuture
```
public FluentFuture<V> finishToFuture()
```
    Marks this step as the last step in the ClosingFuture pipeline. When the returned Future is done, all objects captured for closing during the pipeline's computation will be closed.
    After calling this method, you may not call finishToValueAndCloser(ValueAndCloserConsumer, Executor), this method, or any other derivation method on this ClosingFuture.
    
    Returns:
    
    a Future that represents the final value or exception of the pipeline
  - finishToValueAndCloser
```
public void finishToValueAndCloser(ClosingFuture.ValueAndCloserConsumer<? super V> consumer,
                                   Executor executor)
```
    Marks this step as the last step in the ClosingFuture pipeline. When this step is done, receiver will be called with an object that contains the result of the operation. The receiver can store the ClosingFuture.ValueAndCloser outside the receiver for later synchronous use.
    After calling this method, you may not call finishToFuture(), this method again, or any other derivation method on this ClosingFuture.
    
    Parameters:
    
    consumer - a callback whose method will be called (using executor) when this operation is done
  - cancel
```
public boolean cancel(boolean mayInterruptIfRunning)
```
    Attempts to cancel execution of this step. This attempt will fail if the step has already completed, has already been cancelled, or could not be cancelled for some other reason. If successful, and this step has not started when cancel is called, this step should never run.
    If successful, causes the objects captured by this step (if already started) and its input step(s) for later closing to be closed on their respective Executors. If any such calls specified MoreExecutors.directExecutor(), those objects will be closed synchronously.
    
    Parameters:
    
    mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete, but the step will be cancelled regardless
    
    Returns:
    
    false if the step could not be cancelled, typically because it has already completed normally; true otherwise
  - toString
```
public String toString()
```
    Description copied from class: java.lang.Object
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.
    The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
    getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of the object.
  - finalize
```
protected void finalize()
```
    Description copied from class: java.lang.Object
    
    Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.
    The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.
    The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.
    The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.
    After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.
    The finalize method is never invoked more than once by a Java virtual machine for any given object.
    Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.
    
    Overrides:
    
    finalize in class Object
    
    See Also:
    
    WeakReference, PhantomReference

Class ClosingFuture<V>

Starting a pipeline

Derived steps

Transforming

Catching

Combining

Cancelling

Ending a pipeline

Automatically closing

Manually closing

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

submit

from

eventuallyClosing

whenAllComplete

whenAllComplete

whenAllSucceed

whenAllSucceed

whenAllSucceed

whenAllSucceed

whenAllSucceed

whenAllSucceed

statusFuture

transform

transformAsync

withoutCloser

catching

catchingAsync

finishToFuture

finishToValueAndCloser

cancel

toString

finalize