Package com.google.common.util.concurrent

Class ClosingFuture.Combiner

java.lang.Object

com.google.common.util.concurrent.ClosingFuture.Combiner

Direct Known Subclasses:

ClosingFuture.Combiner2, ClosingFuture.Combiner3, ClosingFuture.Combiner4, ClosingFuture.Combiner5

Enclosing class:

ClosingFuture<V extends @Nullable Object>

@DoNotMock("Use ClosingFuture.whenAllSucceed() or .whenAllComplete() instead.")
public static class ClosingFuture.Combiner
extends Object

A builder of a ClosingFuture step that is derived from more than one input step.

See ClosingFuture.whenAllComplete(Iterable) and ClosingFuture.whenAllSucceed(Iterable) for how to instantiate this class.

Example:

ClosingFuture<BufferedReader> file1ReaderFuture = ...;
ClosingFuture<BufferedReader> file2ReaderFuture = ...;
ListenableFuture<Integer> numberOfDifferentLines =
    ClosingFuture.whenAllSucceed(file1ReaderFuture, file2ReaderFuture)
        .call(
            (closer, peeker) -> {
              BufferedReader file1Reader = peeker.getDone(file1ReaderFuture);
              BufferedReader file2Reader = peeker.getDone(file2ReaderFuture);
              return countDifferentLines(file1Reader, file2Reader);
            },
            executor)
        .finishToFuture();

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ClosingFuture.Combiner.AsyncCombiningCallable<V extends @Nullable Object>	An operation that returns a ClosingFuture result and may throw an exception.
static interface	ClosingFuture.Combiner.CombiningCallable<V extends @Nullable Object>	An operation that returns a result and may throw an exception.

Method Summary

Modifier and Type	Method	Description
final <V extends @Nullable Object> ClosingFuture<V>	call(ClosingFuture.Combiner.CombiningCallable<V> combiningCallable, Executor executor)	Returns a new ClosingFuture pipeline step derived from the inputs by applying a combining function to their values.
final <V extends @Nullable Object> ClosingFuture<V>	callAsync(ClosingFuture.Combiner.AsyncCombiningCallable<V> combiningCallable, Executor executor)	Returns a new ClosingFuture pipeline step derived from the inputs by applying a ClosingFuture-returning function to their values.

Methods inherited from class java.lang.Object

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

Method Details

call

public final <V extends @Nullable Object>
ClosingFuture<V> call(ClosingFuture.Combiner.CombiningCallable<V> combiningCallable,
 Executor executor)

Returns a new ClosingFuture pipeline step derived from the inputs by applying a combining function to their values. The function can use a ClosingFuture.DeferredCloser to capture objects to be closed when the pipeline is done.

If this combiner was returned by a ClosingFuture.whenAllSucceed(java.lang.Iterable<? extends com.google.common.util.concurrent.ClosingFuture<?>>) method and any of the inputs fail, so will the returned step.

If the combiningCallable throws a CancellationException, the pipeline will be cancelled.

If the combiningCallable throws an ExecutionException, the cause of the thrown ExecutionException will be extracted and used as the failure of the derived step.

callAsync

public final <V extends @Nullable Object>
ClosingFuture<V> callAsync(ClosingFuture.Combiner.AsyncCombiningCallable<V> combiningCallable,
 Executor executor)

Returns a new ClosingFuture pipeline step derived from the inputs by applying a ClosingFuture-returning function to their values. 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 combiner was returned by a ClosingFuture.whenAllSucceed(java.lang.Iterable<? extends com.google.common.util.concurrent.ClosingFuture<?>>) method and any of the inputs fail, so will the returned step.

If the combiningCallable throws a CancellationException, the pipeline will be cancelled.

If the combiningCallable throws an ExecutionException, the cause of the thrown ExecutionException will be extracted and used as the failure of the derived step.

If the combiningCallable throws any other exception, it will be used as the failure of the derived step.

If an exception is thrown after the combiningCallable 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 call(CombiningCallable, 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 ClosingFuture.from(ListenableFuture).

The same warnings about doing heavyweight operations within ClosingFuture.transformAsync(AsyncClosingFunction, Executor) apply here.