* Sample Usage (Note that the following classes are all * made-up.)
*
* interface ArchiveSearcher { String search(String target); }
* class App {
* ExecutorService executor = ...
* ArchiveSearcher searcher = ...
* void showSearch(final String target)
* throws InterruptedException {
* Future<String> future
* = executor.submit(new Callable<String>() {
* public String call() {
* return searcher.search(target);
* }});
* displayOtherThings(); // do other things while searching
* try {
* displayText(future.get()); // use future
* } catch (ExecutionException ex) { cleanup(); return; }
* }
* }
*
*
* The {@link FutureTask} class is an implementation of Future that
* implements Runnable, and so may be executed by an Executor.
* For example, the above construction with submit could be replaced by:
*
* FutureTask<String> future =
* new FutureTask<String>(new Callable<String>() {
* public String call() {
* return searcher.search(target);
* }});
* executor.execute(future);
*
*
* Memory consistency effects: Actions taken by the asynchronous computation * happen-before * actions following the corresponding {@code Future.get()} in another thread. * * @see FutureTask * @see Executor * @since 1.5 * @author Doug Lea */ public interface Future { /** * Attempts to cancel execution of this task. This attempt will * fail if the task has already completed, has already been cancelled, * or could not be cancelled for some other reason. If successful, * and this task has not started when cancel is called, * this task should never run. If the task has already started, * then the mayInterruptIfRunning parameter determines * whether the thread executing this task should be interrupted in * an attempt to stop the task. * *
After this method returns, subsequent calls to {@link #isDone} will * always return true. Subsequent calls to {@link #isCancelled} * will always return true if this method returned true. * * @param mayInterruptIfRunning true if the thread executing this * task should be interrupted; otherwise, in-progress tasks are allowed * to complete * @return false if the task could not be cancelled, * typically because it has already completed normally; * true otherwise */ boolean cancel(boolean mayInterruptIfRunning); /** * Returns true if this task was cancelled before it completed * normally. * * @return true if this task was cancelled before it completed */ boolean isCancelled(); /** * Returns true if this task completed. * * Completion may be due to normal termination, an exception, or * cancellation -- in all of these cases, this method will return * true. * * @return true if this task completed */ boolean isDone(); /** * Waits if necessary for the computation to complete, and then * retrieves its result. * * @return the computed result * @throws CancellationException if the computation was cancelled * @throws ExecutionException if the computation threw an * exception * @throws InterruptedException if the current thread was interrupted * while waiting */ Object get() throws InterruptedException, ExecutionException; /** * Waits if necessary for at most the given time for the computation * to complete, and then retrieves its result, if available. * * @param timeout the maximum time to wait * @param unit the time unit of the timeout argument * @return the computed result * @throws CancellationException if the computation was cancelled * @throws ExecutionException if the computation threw an * exception * @throws InterruptedException if the current thread was interrupted * while waiting * @throws TimeoutException if the wait timed out */ Object get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException; }