util/concurrent/Cancellable.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;

/**
 * Something, usually a task, that can be cancelled.  Cancellation is
 * performed by the <tt>cancel</tt> method.  Additional methods are
 * provided to determine if the task completed normally or was
 * cancelled.
 *
 * @see FutureTask
 * @see Executor
 * @since 1.5
 * @author Doug Lea
 */
public interface Cancellable {

    /**
     * Attempt to cancel execution of this task.  This attempt will
     * fail if the task has already completed, already been cancelled,
     * or could not be cancelled for some other reason. If successful,
     * and this task has not started when <tt>cancel</tt> is called,
     * this task should never run.  If the task has already started,
     * then the <tt>interruptIfRunning</tt> parameter determines
     * whether the thread executing this task should be interrupted in
     * an attempt to stop the task.
     *
     * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
     * task should be interrupted; otherwise, in-progress tasks are allowed
     * to complete
     * @return <tt>false</tt> if the task could not be cancelled,
     * typically because is has already completed normally;
     * <tt>true</tt> otherwise
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     * Returns <tt>true</tt> if this task was cancelled before it completed
     * normally.
     *
     * @return <tt>true</tt> if task was cancelled before it completed
     */
    boolean isCancelled();

    /**
     * Returns <tt>true</tt> if this task 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 this task completed.
     */
    boolean isDone();
}
Revision:	1.9
Committed:	Sun Aug 31 13:33:13 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_NOV3_FREEZE
Changes since 1.8:	+2 -6 lines
Log Message:	Removed non-standard tags and misc javadoc cleanup
#	User	Rev	Content
1	tim	1.1	/*
2	dl	1.2	* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5	tim	1.1	*/
6
7			package java.util.concurrent;
8
9			/**
10	brian	1.6	* Something, usually a task, that can be cancelled. Cancellation is
11	dl	1.3	* performed by the <tt>cancel</tt> method. Additional methods are
12			* provided to determine if the task completed normally or was
13			* cancelled.
14	tim	1.1	*
15	brian	1.6	* @see FutureTask
16			* @see Executor
17	dl	1.9	* @since 1.5
18	dl	1.7	* @author Doug Lea
19	tim	1.1	*/
20			public interface Cancellable {
21
22			/**
23	brian	1.6	* Attempt to cancel execution of this task. This attempt will
24	dl	1.7	* fail if the task has already completed, already been cancelled,
25			* or could not be cancelled for some other reason. If successful,
26			* and this task has not started when <tt>cancel</tt> is called,
27	dl	1.9	* this task should never run. If the task has already started,
28	dl	1.7	* then the <tt>interruptIfRunning</tt> parameter determines
29			* whether the thread executing this task should be interrupted in
30			* an attempt to stop the task.
31	tim	1.1	*
32	jozart	1.4	* @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
33	tim	1.1	* task should be interrupted; otherwise, in-progress tasks are allowed
34			* to complete
35	dl	1.5	* @return <tt>false</tt> if the task could not be cancelled,
36			* typically because is has already completed normally;
37			* <tt>true</tt> otherwise
38	tim	1.1	*/
39			boolean cancel(boolean mayInterruptIfRunning);
40
41			/**
42			* Returns <tt>true</tt> if this task was cancelled before it completed
43			* normally.
44			*
45			* @return <tt>true</tt> if task was cancelled before it completed
46			*/
47			boolean isCancelled();
48
49			/**
50	dl	1.8	* Returns <tt>true</tt> if this task completed.
51	tim	1.1	*
52	dl	1.8	* Completion may be due to normal termination, an exception, or
53			* cancellation -- in all of these cases, this method will return
54			* <tt>true</tt>.
55			*
56			* @return <tt>true</tt> if this task completed.
57	tim	1.1	*/
58			boolean isDone();
59			}