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(). All objects the pipeline has captured for closing will begin to be closed asynchronously after the returned Future is done: the future completes before closing starts, rather than once it has finished.

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