View Javadoc
1   /*
2    * Copyright (C) 2008 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.util.concurrent;
16  
17  import com.google.common.annotations.Beta;
18  import com.google.common.annotations.GwtCompatible;
19  import com.google.errorprone.annotations.CanIgnoreReturnValue;
20  import java.util.concurrent.CancellationException;
21  import java.util.concurrent.ExecutionException;
22  import java.util.concurrent.Future;
23  import java.util.concurrent.TimeUnit;
24  import java.util.concurrent.TimeoutException;
25  
26  /**
27   * A {@code CheckedFuture} is a {@link ListenableFuture} that includes versions of the {@code get}
28   * methods that can throw a checked exception. This makes it easier to create a future that executes
29   * logic which can throw an exception.
30   *
31   * <p><b>Warning:</b> We recommend against using {@code CheckedFuture} in new projects. {@code
32   * CheckedFuture} is difficult to build libraries atop. {@code CheckedFuture} ports of methods like
33   * {@link Futures#transformAsync} have historically had bugs, and some of these bugs are necessary,
34   * unavoidable consequences of the {@code CheckedFuture} API. Additionally, {@code CheckedFuture}
35   * encourages users to take exceptions from one thread and rethrow them in another, producing
36   * confusing stack traces.
37   *
38   * <p>A common implementation is {@link Futures#immediateCheckedFuture}.
39   *
40   * <p>Implementations of this interface must adapt the exceptions thrown by {@code Future#get()}:
41   * {@link CancellationException}, {@link ExecutionException} and {@link InterruptedException} into
42   * the type specified by the {@code X} type parameter.
43   *
44   * <p>This interface also extends the ListenableFuture interface to allow listeners to be added.
45   * This allows the future to be used as a normal {@link Future} or as an asynchronous callback
46   * mechanism as needed. This allows multiple callbacks to be registered for a particular task, and
47   * the future will guarantee execution of all listeners when the task completes.
48   *
49   * <p>For a simpler alternative to CheckedFuture, consider accessing Future values with {@link
50   * Futures#getChecked(Future, Class) Futures.getChecked()}.
51   *
52   * @author Sven Mawson
53   * @since 1.0
54   * @deprecated {@link CheckedFuture} cannot properly support the chained operations that are the
55   *     primary goal of {@link ListenableFuture}. {@code CheckedFuture} also encourages users to
56   *     rethrow exceptions from one thread in another thread, producing misleading stack traces.
57   *     Additionally, it has a surprising policy about which exceptions to map and which to leave
58   *     untouched. Guava users who want a {@code CheckedFuture} can fork the classes for their own
59   *     use, possibly specializing them to the particular exception type they use. We recommend that
60   *     most people use {@code ListenableFuture} and perform any exception wrapping themselves. This
61   *     class is scheduled for removal from Guava in February 2018.
62   */
63  @Beta
64  @CanIgnoreReturnValue
65  @Deprecated
66  @GwtCompatible
67  public interface CheckedFuture<V, X extends Exception> extends ListenableFuture<V> {
68  
69    /**
70     * Exception checking version of {@link Future#get()} that will translate {@link
71     * InterruptedException}, {@link CancellationException} and {@link ExecutionException} into
72     * application-specific exceptions.
73     *
74     * @return the result of executing the future.
75     * @throws X on interruption, cancellation or execution exceptions.
76     */
77    V checkedGet() throws X;
78  
79    /**
80     * Exception checking version of {@link Future#get(long, TimeUnit)} that will translate {@link
81     * InterruptedException}, {@link CancellationException} and {@link ExecutionException} into
82     * application-specific exceptions.  On timeout this method throws a normal {@link
83     * TimeoutException}.
84     *
85     * @return the result of executing the future.
86     * @throws TimeoutException if retrieving the result timed out.
87     * @throws X on interruption, cancellation or execution exceptions.
88     */
89    V checkedGet(long timeout, TimeUnit unit) throws TimeoutException, X;
90  }