java/util/TimerTask.java

/*
 * %W% %E%
 *
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.util;

/**
 * A task that can be scheduled for one-time or repeated execution by a Timer.
 *
 * @author  Josh Bloch
 * @version %I%, %G%
 * @see     Timer
 * @since   1.3
 */

public abstract class TimerTask implements Runnable {
    /**
     * This object is used to control access to the TimerTask internals.
     */
    final Object lock = new Object();

    /**
     * The state of this task, chosen from the constants below.
     */
    int state = VIRGIN;

    /**
     * This task has not yet been scheduled.
     */
    static final int VIRGIN = 0;

    /**
     * This task is scheduled for execution.  If it is a non-repeating task,
     * it has not yet been executed.
     */
    static final int SCHEDULED   = 1;

    /**
     * This non-repeating task has already executed (or is currently
     * executing) and has not been cancelled.
     */
    static final int EXECUTED    = 2;

    /**
     * This task has been cancelled (with a call to TimerTask.cancel).
     */
    static final int CANCELLED   = 3;

    /**
     * Next execution time for this task in the format set by Timer
     * schedule methods (nanoseconds since the Timer class was initialized),
     * assuming this task is scheduled for execution.  For repeating
     * tasks, this field is updated prior to each task execution.
     */
    long nextExecutionTime;

    /**
     * Period in nanoseconds for repeating tasks.  A positive value indicates
     * fixed-rate execution.  A negative value indicates fixed-delay execution.
     * A value of 0 indicates a non-repeating task.
     */
    long period = 0;

    /**
     * Creates a new timer task.
     */
    protected TimerTask() {
    }

    /**
     * The action to be performed by this timer task.
     */
    public abstract void run();

    /**
     * Cancels this timer task.  If the task has been scheduled for one-time
     * execution and has not yet run, or has not yet been scheduled, it will
     * never run.  If the task has been scheduled for repeated execution, it
     * will never run again.  (If the task is running when this call occurs,
     * the task will run to completion, but will never run again.)
     *
     * <p>Note that calling this method from within the <tt>run</tt> method of
     * a repeating timer task absolutely guarantees that the timer task will
     * not run again.
     *
     * <p>This method may be called repeatedly; the second and subsequent 
     * calls have no effect.
     *
     * @return true if this task is scheduled for one-time execution and has
     *         not yet run, or this task is scheduled for repeated execution.
     *         Returns false if the task was scheduled for one-time execution
     *         and has already run, or if the task was never scheduled, or if
     *         the task was already cancelled.  (Loosely speaking, this method
     *         returns <tt>true</tt> if it prevents one or more scheduled
     *         executions from taking place.)
     */
    public boolean cancel() {
        synchronized(lock) {
            boolean result = (state == SCHEDULED);
            state = CANCELLED;
            return result;
        }
    }

    /**
     * Returns the <i>scheduled</i> execution time of the most recent
     * <i>actual</i> execution of this task.  (If this method is invoked
     * while task execution is in progress, the return value is the scheduled
     * execution time of the ongoing task execution.)
     *
     * <p>This method is typically invoked from within a task's run method, to
     * determine whether the current execution of the task is sufficiently
     * timely to warrant performing the scheduled activity:
     * <pre>
     *   public void run() {
     *       if (System.currentTimeMillis() - scheduledExecutionTime() >=
     *           MAX_TARDINESS)
     *               return;  // Too late; skip this execution.
     *       // Perform the task
     *   }
     * </pre>
     *
     * This method is typically <i>not</i> used in conjunction with
     * <i>fixed-delay execution</i> repeating tasks, as their scheduled
     * execution times are allowed to drift over time, and so are not terribly
     * significant.
     *
     * @return the time at which the most recent execution of this task was
     *         scheduled to occur, in the format returned by Date.getTime().
     *         The return value is undefined if the task has yet to commence
     *         its first execution.
     * @see Date#getTime()
     */
    public long scheduledExecutionTime() {
        synchronized(lock) {
            return Timer.executionTimeToMillis
                (period < 0 ? 
                 nextExecutionTime + period :
                 nextExecutionTime - period);
        }
    }
}
Revision:	1.3
Committed:	Fri Apr 16 22:47:28 2004 UTC (20 years ago) by dl
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.2:	+0 -0 lines
State:	*FILE REMOVED*
Log Message:	Removing incomplete changes to classes that won't make tiger
#	Content
1	/*
2	* %W% %E%
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;
9
10	/**
11	* A task that can be scheduled for one-time or repeated execution by a Timer.
12	*
13	* @author Josh Bloch
14	* @version %I%, %G%
15	* @see Timer
16	* @since 1.3
17	*/
18
19	public abstract class TimerTask implements Runnable {
20	/**
21	* This object is used to control access to the TimerTask internals.
22	*/
23	final Object lock = new Object();
24
25	/**
26	* The state of this task, chosen from the constants below.
27	*/
28	int state = VIRGIN;
29
30	/**
31	* This task has not yet been scheduled.
32	*/
33	static final int VIRGIN = 0;
34
35	/**
36	* This task is scheduled for execution. If it is a non-repeating task,
37	* it has not yet been executed.
38	*/
39	static final int SCHEDULED = 1;
40
41	/**
42	* This non-repeating task has already executed (or is currently
43	* executing) and has not been cancelled.
44	*/
45	static final int EXECUTED = 2;
46
47	/**
48	* This task has been cancelled (with a call to TimerTask.cancel).
49	*/
50	static final int CANCELLED = 3;
51
52	/**
53	* Next execution time for this task in the format set by Timer
54	* schedule methods (nanoseconds since the Timer class was initialized),
55	* assuming this task is scheduled for execution. For repeating
56	* tasks, this field is updated prior to each task execution.
57	*/
58	long nextExecutionTime;
59
60	/**
61	* Period in nanoseconds for repeating tasks. A positive value indicates
62	* fixed-rate execution. A negative value indicates fixed-delay execution.
63	* A value of 0 indicates a non-repeating task.
64	*/
65	long period = 0;
66
67	/**
68	* Creates a new timer task.
69	*/
70	protected TimerTask() {
71	}
72
73	/**
74	* The action to be performed by this timer task.
75	*/
76	public abstract void run();
77
78	/**
79	* Cancels this timer task. If the task has been scheduled for one-time
80	* execution and has not yet run, or has not yet been scheduled, it will
81	* never run. If the task has been scheduled for repeated execution, it
82	* will never run again. (If the task is running when this call occurs,
83	* the task will run to completion, but will never run again.)
84	*
85	* <p>Note that calling this method from within the <tt>run</tt> method of
86	* a repeating timer task absolutely guarantees that the timer task will
87	* not run again.
88	*
89	* <p>This method may be called repeatedly; the second and subsequent
90	* calls have no effect.
91	*
92	* @return true if this task is scheduled for one-time execution and has
93	* not yet run, or this task is scheduled for repeated execution.
94	* Returns false if the task was scheduled for one-time execution
95	* and has already run, or if the task was never scheduled, or if
96	* the task was already cancelled. (Loosely speaking, this method
97	* returns <tt>true</tt> if it prevents one or more scheduled
98	* executions from taking place.)
99	*/
100	public boolean cancel() {
101	synchronized(lock) {
102	boolean result = (state == SCHEDULED);
103	state = CANCELLED;
104	return result;
105	}
106	}
107
108	/**
109	* Returns the <i>scheduled</i> execution time of the most recent
110	* <i>actual</i> execution of this task. (If this method is invoked
111	* while task execution is in progress, the return value is the scheduled
112	* execution time of the ongoing task execution.)
113	*
114	* <p>This method is typically invoked from within a task's run method, to
115	* determine whether the current execution of the task is sufficiently
116	* timely to warrant performing the scheduled activity:
117	* <pre>
118	* public void run() {
119	* if (System.currentTimeMillis() - scheduledExecutionTime() >=
120	* MAX_TARDINESS)
121	* return; // Too late; skip this execution.
122	* // Perform the task
123	* }
124	* </pre>
125	*
126	* This method is typically <i>not</i> used in conjunction with
127	* <i>fixed-delay execution</i> repeating tasks, as their scheduled
128	* execution times are allowed to drift over time, and so are not terribly
129	* significant.
130	*
131	* @return the time at which the most recent execution of this task was
132	* scheduled to occur, in the format returned by Date.getTime().
133	* The return value is undefined if the task has yet to commence
134	* its first execution.
135	* @see Date#getTime()
136	*/
137	public long scheduledExecutionTime() {
138	synchronized(lock) {
139	return Timer.executionTimeToMillis
140	(period < 0 ?
141	nextExecutionTime + period :
142	nextExecutionTime - period);
143	}
144	}
145	}