util/concurrent/Future.java

/*
 * @(#)Future.java
 */

package java.util.concurrent;

/**
 * A <tt>Future</tt> represents the result of an asynchronous computation.
 * Methods are provided to check if the computation is complete,
 * to wait for its completion, and to retrieve the result of the
 * computation.  The result can only be retrieved when the computation
 * has completed.  The <tt>get</tt> method will block until the computation
 * has completed.  Once the computation has completed, the result cannot
 * be changed, nor can the computation be restarted or cancelled.
 *
 * <p>
 * <b>Sample Usage</b> (Note that the following classes are all
 * made-up.) <p>
 * <pre>
 * class ArchiveSearcher { String search(String target); }
 * class App {
 *   Executor executor = ...
 *   ArchiveSearcher searcher = ...
 *   void showSearch(final String target) throws InterruptedException {
 *     Future&lt;String&gt; future =
 *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
 *         public String call() {
 *           return searcher.search(target);
 *       }});
 *     executor.execute(future);
 *     displayOtherThings(); // do other things while searching
 *     try {
 *       displayText(future.get()); // use future
 *     }
 *     catch (ExecutionException ex) { cleanup(); return; }
 *   }
 * }
 * </pre>
 *
 * @since 1.5
 * @see FutureTask
 * @see Executor
 *
 * @spec JSR-166
 * @revised $Date: 2003/08/06 00:20:00 $
 * @editor $Author: dl $
 * @author Doug Lea
 */
public interface Future<V> {

    /**
     * Returns <tt>true</tt> if the underlying task has completed.
     *
     * Completion may be due to normal termination, an exception, or
     * cancellation -- in all of these cases, this method will return
     * <tt>true</tt>.
     *
     * @return <tt>true</tt> if the underlying task has completed
     */
    boolean isDone();

    /**
     * Waits if necessary for computation to complete, and then
     * retrieves its result.
     *
     * @return computed result
     * @throws CancellationException here???
     * @throws ExecutionException if underlying computation threw an
     * exception
     * @throws InterruptedException if current thread was interrupted
     * while waiting
     */
    V get() throws InterruptedException, ExecutionException;

    /**
     * Waits if necessary for at most the given time for the computation
     * to complete, and then retrieves its result.
     *
     * @param timeout the maximum time to wait
     * @param granularity the time unit of the timeout argument
     * @return computed result
     * @throws ExecutionException if underlying computation threw an
     * exception
     * @throws InterruptedException if current thread was interrupted
     * while waiting
     * @throws TimeoutException if the wait timed out
     */
    V get(long timeout, TimeUnit granularity)
        throws InterruptedException, ExecutionException, TimeoutException;
}


Revision:	1.7
Committed:	Wed Aug 6 18:22:09 2003 UTC (20 years, 10 months ago) by tim
Branch:	MAIN
CVS Tags:	JSR166_CR1
Changes since 1.6:	+3 -3 lines
Log Message:	Fixes to minor errors found by DocCheck
#	Content
1	/*
2	* @(#)Future.java
3	*/
4
5	package java.util.concurrent;
6
7	/**
8	* A <tt>Future</tt> represents the result of an asynchronous computation.
9	* Methods are provided to check if the computation is complete,
10	* to wait for its completion, and to retrieve the result of the
11	* computation. The result can only be retrieved when the computation
12	* has completed. The <tt>get</tt> method will block until the computation
13	* has completed. Once the computation has completed, the result cannot
14	* be changed, nor can the computation be restarted or cancelled.
15	*
16	* <p>
17	* <b>Sample Usage</b> (Note that the following classes are all
18	* made-up.) <p>
19	* <pre>
20	* class ArchiveSearcher { String search(String target); }
21	* class App {
22	* Executor executor = ...
23	* ArchiveSearcher searcher = ...
24	* void showSearch(final String target) throws InterruptedException {
25	* Future<String> future =
26	* new FutureTask<String>(new Callable<String>() {
27	* public String call() {
28	* return searcher.search(target);
29	* }});
30	* executor.execute(future);
31	* displayOtherThings(); // do other things while searching
32	* try {
33	* displayText(future.get()); // use future
34	* }
35	* catch (ExecutionException ex) { cleanup(); return; }
36	* }
37	* }
38	* </pre>
39	*
40	* @since 1.5
41	* @see FutureTask
42	* @see Executor
43	*
44	* @spec JSR-166
45	* @revised $Date: 2003/08/06 00:20:00 $
46	* @editor $Author: dl $
47	* @author Doug Lea
48	*/
49	public interface Future<V> {
50
51	/**
52	* Returns <tt>true</tt> if the underlying task has completed.
53	*
54	* Completion may be due to normal termination, an exception, or
55	* cancellation -- in all of these cases, this method will return
56	* <tt>true</tt>.
57	*
58	* @return <tt>true</tt> if the underlying task has completed
59	*/
60	boolean isDone();
61
62	/**
63	* Waits if necessary for computation to complete, and then
64	* retrieves its result.
65	*
66	* @return computed result
67	* @throws CancellationException here???
68	* @throws ExecutionException if underlying computation threw an
69	* exception
70	* @throws InterruptedException if current thread was interrupted
71	* while waiting
72	*/
73	V get() throws InterruptedException, ExecutionException;
74
75	/**
76	* Waits if necessary for at most the given time for the computation
77	* to complete, and then retrieves its result.
78	*
79	* @param timeout the maximum time to wait
80	* @param granularity the time unit of the timeout argument
81	* @return computed result
82	* @throws ExecutionException if underlying computation threw an
83	* exception
84	* @throws InterruptedException if current thread was interrupted
85	* while waiting
86	* @throws TimeoutException if the wait timed out
87	*/
88	V get(long timeout, TimeUnit granularity)
89	throws InterruptedException, ExecutionException, TimeoutException;
90	}
91
92
93