Future


1   /*
2    * @(#)Future.java  1.6 04/02/09
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.util.concurrent;
9   
10  /**
11   * A <tt>Future</tt> represents the result of an asynchronous
12   * computation.  Methods are provided to check if the computation is
13   * complete, to wait for its completion, and to retrieve the result of
14   * the computation.  The result can only be retrieved using method
15   * <tt>get</tt> when the computation has completed, blocking if
16   * necessary until it is ready.  Cancellation is performed by the
17   * <tt>cancel</tt> method.  Additional methods are provided to
18   * determine if the task completed normally or was cancelled. Once a
19   * computation has completed, the computation cannot be cancelled.
20   * If you would like to use a <tt>Future</tt> for the sake
21   * of cancellability but not provide a usable result, you can
22   * declare types of the form <tt>Future&lt;?&gt;</tt> and
23   * return <tt>null</tt> as a result of the underlying task.
24   *
25   * <p>
26   * <b>Sample Usage</b> (Note that the following classes are all
27   * made-up.) <p>
28   * <pre>
29   * interface ArchiveSearcher { String search(String target); }
30   * class App {
31   *   ExecutorService executor = ...
32   *   ArchiveSearcher searcher = ...
33   *   void showSearch(final String target) throws InterruptedException {
34   *     Future&lt;String&gt; future = executor.submit(new Callable&lt;String&gt;() {
35   *         public String call() { return searcher.search(target); }
36   *     });
37   *     displayOtherThings(); // do other things while searching
38   *     try {
39   *       displayText(future.get()); // use future
40   *     } catch (ExecutionException ex) { cleanup(); return; }
41   *   }
42   * }
43   * </pre>
44   *
45   * The {@link FutureTask} class is an implementation of <tt>Future</tt> that 
46   * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>. 
47   * For example, the above construction with <tt>submit</tt> could be replaced by:
48   * <pre>
49   *     FutureTask&lt;String&gt; future =
50   *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
51   *         public String call() {
52   *           return searcher.search(target);
53   *       }});
54   *     executor.execute(future);
55   * </pre>
56   * @see FutureTask
57   * @see Executor
58   * @since 1.5
59   * @author Doug Lea
60   * @param <V> The result type returned by this Future's <tt>get</tt> method
61   */
62  public interface Future<V> {
63  
64      /**
65       * Attempts to cancel execution of this task.  This attempt will
66       * fail if the task has already completed, already been cancelled,
67       * or could not be cancelled for some other reason. If successful,
68       * and this task has not started when <tt>cancel</tt> is called,
69       * this task should never run.  If the task has already started,
70       * then the <tt>mayInterruptIfRunning</tt> parameter determines
71       * whether the thread executing this task should be interrupted in
72       * an attempt to stop the task.
73       *
74       * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
75       * task should be interrupted; otherwise, in-progress tasks are allowed
76       * to complete
77       * @return <tt>false</tt> if the task could not be cancelled,
78       * typically because it has already completed normally;
79       * <tt>true</tt> otherwise
80       */
81      boolean cancel(boolean mayInterruptIfRunning);
82  
83      /**
84       * Returns <tt>true</tt> if this task was cancelled before it completed
85       * normally.
86       *
87       * @return <tt>true</tt> if task was cancelled before it completed
88       */
89      boolean isCancelled();
90  
91      /**
92       * Returns <tt>true</tt> if this task completed.  
93       *
94       * Completion may be due to normal termination, an exception, or
95       * cancellation -- in all of these cases, this method will return
96       * <tt>true</tt>.
97       * 
98       * @return <tt>true</tt> if this task completed.
99       */
100     boolean isDone();
101 
102     /**
103      * Waits if necessary for the computation to complete, and then
104      * retrieves its result.
105      *
106      * @return the computed result
107      * @throws CancellationException if the computation was cancelled
108      * @throws ExecutionException if the computation threw an
109      * exception
110      * @throws InterruptedException if the current thread was interrupted
111      * while waiting
112      */
113     V get() throws InterruptedException  , ExecutionException  ;
114 
115     /**
116      * Waits if necessary for at most the given time for the computation
117      * to complete, and then retrieves its result, if available.
118      *
119      * @param timeout the maximum time to wait
120      * @param unit the time unit of the timeout argument
121      * @return the computed result
122      * @throws CancellationException if the computation was cancelled
123      * @throws ExecutionException if the computation threw an
124      * exception
125      * @throws InterruptedException if the current thread was interrupted
126      * while waiting
127      * @throws TimeoutException if the wait timed out
128      */
129     V get(long timeout, TimeUnit   unit)
130         throws InterruptedException  , ExecutionException  , TimeoutException  ;
131 }
132 
133 
134 
135
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags