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