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 017 package com.google.common.util.concurrent; 018 019 import com.google.common.annotations.Beta; 020 021 import java.util.concurrent.CancellationException; 022 import java.util.concurrent.ExecutionException; 023 import java.util.concurrent.Future; 024 import java.util.concurrent.TimeUnit; 025 import java.util.concurrent.TimeoutException; 026 027 /** 028 * A {@code CheckedFuture} is an extension of {@link Future} that includes 029 * versions of the {@code get} methods that can throw a checked exception and 030 * allows listeners to be attached to the future. This makes it easier to 031 * create a future that executes logic which can throw an exception. 032 * 033 * <p>Common implementations include {@link 034 * com.google.common.labs.concurrent.ValueCheckedFuture} and {@link 035 * Futures#immediateCheckedFuture}. 036 * 037 * <p>Implementations of this interface must adapt the exceptions thrown by 038 * {@code Future#get()}: {@link CancellationException}, 039 * {@link ExecutionException} and {@link InterruptedException} into the type 040 * specified by the {@code E} type parameter. 041 * 042 * <p>This interface also extends the ListenableFuture interface to allow 043 * listeners to be added. This allows the future to be used as a normal 044 * {@link Future} or as an asynchronous callback mechanism as needed. This 045 * allows multiple callbacks to be registered for a particular task, and the 046 * future will guarantee execution of all listeners when the task completes. 047 * 048 * @author Sven Mawson 049 * @since 1 050 */ 051 @Beta 052 public interface CheckedFuture<V, X extends Exception> 053 extends ListenableFuture<V> { 054 055 /** 056 * Exception checking version of {@link Future#get()} that will translate 057 * {@link InterruptedException}, {@link CancellationException} and 058 * {@link ExecutionException} into application-specific exceptions. 059 * 060 * @return the result of executing the future. 061 * @throws X on interruption, cancellation or execution exceptions. 062 */ 063 V checkedGet() throws X; 064 065 /** 066 * Exception checking version of {@link Future#get(long, TimeUnit)} that will 067 * translate {@link InterruptedException}, {@link CancellationException} and 068 * {@link ExecutionException} into application-specific exceptions. On 069 * timeout this method throws a normal {@link TimeoutException}. 070 * 071 * @return the result of executing the future. 072 * @throws TimeoutException if retrieving the result timed out. 073 * @throws X on interruption, cancellation or execution exceptions. 074 */ 075 V checkedGet(long timeout, TimeUnit unit) throws TimeoutException, X; 076 }