001 /* 002 * Copyright (C) 2007 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.Executor; 022 import java.util.concurrent.Future; 023 import java.util.concurrent.RejectedExecutionException; 024 025 /** 026 * A {@link Future} that accepts completion listeners. Each listener has an 027 * associated executor, and is invoked using this executor once the future's 028 * computation is {@linkplain Future#isDone() complete}. If the computation has 029 * already completed when the listener is added, the listener will execute 030 * immediately. 031 * 032 * <p>Common {@code ListenableFuture} implementations include {@link 033 * SettableFuture} and the futures returned by a {@link 034 * ListeningExecutorService} (typically {@link ListenableFutureTask} 035 * instances). 036 * 037 * <p>Usage: 038 * <pre> {@code 039 * final ListenableFuture<?> future = myService.async(myRequest); 040 * future.addListener(new Runnable() { 041 * public void run() { 042 * System.out.println("Operation Complete."); 043 * try { 044 * System.out.println("Result: " + future.get()); 045 * } catch (Exception e) { 046 * System.out.println("Error: " + e.message()); 047 * } 048 * } 049 * }, executor);}</pre> 050 * 051 * @author Sven Mawson 052 * @author Nishant Thakkar 053 * @since 1 054 */ 055 @Beta 056 public interface ListenableFuture<V> extends Future<V> { 057 /** 058 * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on 059 * the given executor. The listener will run when the {@code Future}'s 060 * computation is {@linkplain Future#isDone() complete} or, if the computation 061 * is already complete, immediately. 062 * 063 * <p>There is no guaranteed ordering of execution of listeners, but any 064 * listener added through this method is guaranteed to be called once the 065 * computation is complete. 066 * 067 * <p>Listeners cannot throw checked exceptions and should not throw {@code 068 * RuntimeException} unless their executors are prepared to handle it. 069 * Listeners that will execute in {@link MoreExecutors#sameThreadExecutor} 070 * should take special care, since they may run during the call to {@code 071 * addListener} or during the call that sets the future's value. 072 * 073 * @param listener the listener to run when the computation is complete 074 * @param executor the executor to run the listener in 075 * @throws NullPointerException if the executor or listener was null 076 * @throws RejectedExecutionException if we tried to execute the listener 077 * immediately but the executor rejected it. 078 */ 079 void addListener(Runnable listener, Executor executor); 080 }