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