1/*
2 * Copyright (C) 2008 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.google.common.util.concurrent;
18
19import com.google.common.annotations.Beta;
20
21import java.util.concurrent.CancellationException;
22import java.util.concurrent.ExecutionException;
23import java.util.concurrent.Future;
24import java.util.concurrent.TimeUnit;
25import java.util.concurrent.TimeoutException;
26
27/**
28 * A {@code CheckedFuture} is a {@link ListenableFuture} that includes versions
29 * of the {@code get} methods that can throw a checked exception.  This makes it
30 * easier to create a future that executes logic which can throw an exception.
31 *
32 * <p>A common implementation is {@link Futures#immediateCheckedFuture}.
33 *
34 * <p>Implementations of this interface must adapt the exceptions thrown by
35 * {@code Future#get()}: {@link CancellationException},
36 * {@link ExecutionException} and {@link InterruptedException} into the type
37 * specified by the {@code X} type parameter.
38 *
39 * <p>This interface also extends the ListenableFuture interface to allow
40 * listeners to be added. This allows the future to be used as a normal
41 * {@link Future} or as an asynchronous callback mechanism as needed. This
42 * allows multiple callbacks to be registered for a particular task, and the
43 * future will guarantee execution of all listeners when the task completes.
44 *
45 * <p>For a simpler alternative to CheckedFuture, consider accessing Future
46 * values with {@link Futures#get(Future, Class) Futures.get()}.
47 *
48 * @author Sven Mawson
49 * @since 1.0
50 */
51@Beta
52public interface CheckedFuture<V, X extends Exception>
53    extends ListenableFuture<V> {
54
55  /**
56   * Exception checking version of {@link Future#get()} that will translate
57   * {@link InterruptedException}, {@link CancellationException} and
58   * {@link ExecutionException} into application-specific exceptions.
59   *
60   * @return the result of executing the future.
61   * @throws X on interruption, cancellation or execution exceptions.
62   */
63  V checkedGet() throws X;
64
65  /**
66   * Exception checking version of {@link Future#get(long, TimeUnit)} that will
67   * translate {@link InterruptedException}, {@link CancellationException} and
68   * {@link ExecutionException} into application-specific exceptions.  On
69   * timeout this method throws a normal {@link TimeoutException}.
70   *
71   * @return the result of executing the future.
72   * @throws TimeoutException if retrieving the result timed out.
73   * @throws X on interruption, cancellation or execution exceptions.
74   */
75  V checkedGet(long timeout, TimeUnit unit) throws TimeoutException, X;
76}
77