001/* 002 * Copyright (C) 2008 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.util.concurrent; 018 019import com.google.common.annotations.Beta; 020import com.google.common.annotations.GwtCompatible; 021 022import java.util.concurrent.CancellationException; 023import java.util.concurrent.ExecutionException; 024import java.util.concurrent.Future; 025import java.util.concurrent.TimeUnit; 026import java.util.concurrent.TimeoutException; 027 028/** 029 * A {@code CheckedFuture} is a {@link ListenableFuture} that includes versions 030 * of the {@code get} methods that can throw a checked exception. This makes it 031 * easier to create a future that executes logic which can throw an exception. 032 * 033 * <p>A common implementation is {@link Futures#immediateCheckedFuture}. 034 * 035 * <p>Implementations of this interface must adapt the exceptions thrown by 036 * {@code Future#get()}: {@link CancellationException}, 037 * {@link ExecutionException} and {@link InterruptedException} into the type 038 * specified by the {@code X} type parameter. 039 * 040 * <p>This interface also extends the ListenableFuture interface to allow 041 * listeners to be added. This allows the future to be used as a normal 042 * {@link Future} or as an asynchronous callback mechanism as needed. This 043 * allows multiple callbacks to be registered for a particular task, and the 044 * future will guarantee execution of all listeners when the task completes. 045 * 046 * <p>For a simpler alternative to CheckedFuture, consider accessing Future 047 * values with {@link Futures#getChecked(Future, Class) Futures.getChecked()}. 048 * 049 * @author Sven Mawson 050 * @since 1.0 051 */ 052@Beta 053@GwtCompatible 054public interface CheckedFuture<V, X extends Exception> 055 extends ListenableFuture<V> { 056 057 /** 058 * Exception checking version of {@link Future#get()} that will translate 059 * {@link InterruptedException}, {@link CancellationException} and 060 * {@link ExecutionException} into application-specific exceptions. 061 * 062 * @return the result of executing the future. 063 * @throws X on interruption, cancellation or execution exceptions. 064 */ 065 V checkedGet() throws X; 066 067 /** 068 * Exception checking version of {@link Future#get(long, TimeUnit)} that will 069 * translate {@link InterruptedException}, {@link CancellationException} and 070 * {@link ExecutionException} into application-specific exceptions. On 071 * timeout this method throws a normal {@link TimeoutException}. 072 * 073 * @return the result of executing the future. 074 * @throws TimeoutException if retrieving the result timed out. 075 * @throws X on interruption, cancellation or execution exceptions. 076 */ 077 V checkedGet(long timeout, TimeUnit unit) throws TimeoutException, X; 078}