001: /*
002: * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.util;
027:
028: /**
029: * A task that can be scheduled for one-time or repeated execution by a Timer.
030: *
031: * @author Josh Bloch
032: * @version 1.17, 05/05/07
033: * @see Timer
034: * @since 1.3
035: */
036:
037: public abstract class TimerTask implements Runnable {
038: /**
039: * This object is used to control access to the TimerTask internals.
040: */
041: final Object lock = new Object();
042:
043: /**
044: * The state of this task, chosen from the constants below.
045: */
046: int state = VIRGIN;
047:
048: /**
049: * This task has not yet been scheduled.
050: */
051: static final int VIRGIN = 0;
052:
053: /**
054: * This task is scheduled for execution. If it is a non-repeating task,
055: * it has not yet been executed.
056: */
057: static final int SCHEDULED = 1;
058:
059: /**
060: * This non-repeating task has already executed (or is currently
061: * executing) and has not been cancelled.
062: */
063: static final int EXECUTED = 2;
064:
065: /**
066: * This task has been cancelled (with a call to TimerTask.cancel).
067: */
068: static final int CANCELLED = 3;
069:
070: /**
071: * Next execution time for this task in the format returned by
072: * System.currentTimeMillis, assuming this task is scheduled for execution.
073: * For repeating tasks, this field is updated prior to each task execution.
074: */
075: long nextExecutionTime;
076:
077: /**
078: * Period in milliseconds for repeating tasks. A positive value indicates
079: * fixed-rate execution. A negative value indicates fixed-delay execution.
080: * A value of 0 indicates a non-repeating task.
081: */
082: long period = 0;
083:
084: /**
085: * Creates a new timer task.
086: */
087: protected TimerTask() {
088: }
089:
090: /**
091: * The action to be performed by this timer task.
092: */
093: public abstract void run();
094:
095: /**
096: * Cancels this timer task. If the task has been scheduled for one-time
097: * execution and has not yet run, or has not yet been scheduled, it will
098: * never run. If the task has been scheduled for repeated execution, it
099: * will never run again. (If the task is running when this call occurs,
100: * the task will run to completion, but will never run again.)
101: *
102: * <p>Note that calling this method from within the <tt>run</tt> method of
103: * a repeating timer task absolutely guarantees that the timer task will
104: * not run again.
105: *
106: * <p>This method may be called repeatedly; the second and subsequent
107: * calls have no effect.
108: *
109: * @return true if this task is scheduled for one-time execution and has
110: * not yet run, or this task is scheduled for repeated execution.
111: * Returns false if the task was scheduled for one-time execution
112: * and has already run, or if the task was never scheduled, or if
113: * the task was already cancelled. (Loosely speaking, this method
114: * returns <tt>true</tt> if it prevents one or more scheduled
115: * executions from taking place.)
116: */
117: public boolean cancel() {
118: synchronized (lock) {
119: boolean result = (state == SCHEDULED);
120: state = CANCELLED;
121: return result;
122: }
123: }
124:
125: /**
126: * Returns the <i>scheduled</i> execution time of the most recent
127: * <i>actual</i> execution of this task. (If this method is invoked
128: * while task execution is in progress, the return value is the scheduled
129: * execution time of the ongoing task execution.)
130: *
131: * <p>This method is typically invoked from within a task's run method, to
132: * determine whether the current execution of the task is sufficiently
133: * timely to warrant performing the scheduled activity:
134: * <pre>
135: * public void run() {
136: * if (System.currentTimeMillis() - scheduledExecutionTime() >=
137: * MAX_TARDINESS)
138: * return; // Too late; skip this execution.
139: * // Perform the task
140: * }
141: * </pre>
142: * This method is typically <i>not</i> used in conjunction with
143: * <i>fixed-delay execution</i> repeating tasks, as their scheduled
144: * execution times are allowed to drift over time, and so are not terribly
145: * significant.
146: *
147: * @return the time at which the most recent execution of this task was
148: * scheduled to occur, in the format returned by Date.getTime().
149: * The return value is undefined if the task has yet to commence
150: * its first execution.
151: * @see Date#getTime()
152: */
153: public long scheduledExecutionTime() {
154: synchronized (lock) {
155: return (period < 0 ? nextExecutionTime + period
156: : nextExecutionTime - period);
157: }
158: }
159: }
| 