/* * @(#)Timer.java	1.20 01/08/21 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information").  You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. */package java.util;import java.util.Date;/** * A facility for threads to schedule tasks for future execution in a * background thread.  Tasks may be scheduled for one-time execution, or for * repeated execution at regular intervals. * * <p>Corresponding to each <tt>Timer</tt> object is a single background * thread that is used to execute all of the timer's tasks, sequentially. * Timer tasks should complete quickly.  If a timer task takes excessive time * to complete, it "hogs" the timer's task execution thread.  This can, in * turn, delay the execution of subsequent tasks, which may "bunch up" and * execute in rapid succession when (and if) the offending task finally * completes. * * <p>After the last live reference to a <tt>Timer</tt> object goes away * <i>and</i> all outstanding tasks have completed execution, the timer's task * execution thread terminates gracefully (and becomes subject to garbage * collection).  However, this can take arbitrarily long to occur.  By * default, the task execution thread does not run as a <i>daemon thread</i>, * so it is capable of keeping an application from terminating.  If a caller * wants to terminate a timer's task execution thread rapidly, the caller * should invoke the timer's <tt>cancel</tt> method. * * <p>If the timer's task execution thread terminates unexpectedly, for * example, because its <tt>stop</tt> method is invoked, any further * attempt to schedule a task on the timer will result in an * <tt>IllegalStateException</tt>, as if the timer's <tt>cancel</tt> * method had been invoked. * * <p>This class is thread-safe: multiple threads can share a single * <tt>Timer</tt> object without the need for external synchronization. * * <p>This class does <i>not</i> offer real-time guarantees: it schedules * tasks using the <tt>Object.wait(long)</tt> method. * <p> * Timers function only within a single VM and are cancelled when the VM exits. * When the VM is started no timers exist, they are created only by * application request. * * @see     TimerTask * @see     Object#wait(long) * @since   1.3 */public class Timer {    /**     * The timer task queue.  This data structure is shared with the timer     * thread.  The timer produces tasks, via its various schedule calls,     * and the timer thread consumes, executing timer tasks as appropriate,     * and removing them from the queue when they're obsolete.     */    private TaskQueue queue = new TaskQueue();    /**     * The timer thread.     */    private TimerThread thread = new TimerThread(queue);    /**     * Creates a new timer.  The associated thread does <i>not</i> run as     * a daemon thread, which may prevent an application from terminating.     *     * @see Thread     * @see #cancel()     */    public Timer() {        thread.start();    }    /**     * Schedules the specified task for execution after the specified delay.     *     * @param task  task to be scheduled.     * @param delay delay in milliseconds before task is to be executed.     * @throws IllegalArgumentException if <tt>delay</tt> is negative, or     *         <tt>delay + System.currentTimeMillis()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, or timer was cancelled.     */    public void schedule(TimerTask task, long delay) {        if (delay < 0)            throw new IllegalArgumentException("Negative delay.");        sched(task, System.currentTimeMillis()+delay, 0);    }    /**     * Schedules the specified task for execution at the specified time.  If     * the time is in the past, the task is scheduled for immediate execution.     *     * @param task task to be scheduled.     * @param time time at which task is to be executed.     * @throws IllegalArgumentException if <tt>time.getTime()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    public void schedule(TimerTask task, Date time) {        sched(task, time.getTime(), 0);    }    /**     * Schedules the specified task for repeated <i>fixed-delay execution</i>,     * beginning after the specified delay.  Subsequent executions take place     * at approximately regular intervals separated by the specified period.     *     * <p>In fixed-delay execution, each execution is scheduled relative to     * the actual execution time of the previous execution.  If an execution     * is delayed for any reason (such as garbage collection or other     * background activity), subsequent executions will be delayed as well.     * In the long run, the frequency of execution will generally be slightly     * lower than the reciprocal of the specified period (assuming the system     * clock underlying <tt>Object.wait(long)</tt> is accurate).     *     * <p>Fixed-delay execution is appropriate for recurring activities     * that require "smoothness."  In other words, it is appropriate for     * activities where it is more important to keep the frequency accurate     * in the short run than in the long run.  This includes most animation     * tasks, such as blinking a cursor at regular intervals.  It also includes     * tasks wherein regular activity is performed in response to human     * input, such as automatically repeating a character as long as a key     * is held down.     *     * @param task   task to be scheduled.     * @param delay  delay in milliseconds before task is to be executed.     * @param period time in milliseconds between successive task executions.     * @throws IllegalArgumentException if <tt>delay</tt> is negative, or     *         <tt>delay + System.currentTimeMillis()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    public void schedule(TimerTask task, long delay, long period) {        if (delay < 0)            throw new IllegalArgumentException("Negative delay.");        if (period <= 0)            throw new IllegalArgumentException("Non-positive period.");        sched(task, System.currentTimeMillis()+delay, -period);    }    /**     * Schedules the specified task for repeated <i>fixed-delay execution</i>,     * beginning at the specified time. Subsequent executions take place at     * approximately regular intervals, separated by the specified period.     *     * <p>In fixed-delay execution, each execution is scheduled relative to     * the actual execution time of the previous execution.  If an execution     * is delayed for any reason (such as garbage collection or other     * background activity), subsequent executions will be delayed as well.     * In the long run, the frequency of execution will generally be slightly     * lower than the reciprocal of the specified period (assuming the system     * clock underlying <tt>Object.wait(long)</tt> is accurate).     *     * <p>Fixed-delay execution is appropriate for recurring activities     * that require "smoothness."  In other words, it is appropriate for     * activities where it is more important to keep the frequency accurate     * in the short run than in the long run.  This includes most animation     * tasks, such as blinking a cursor at regular intervals.  It also includes     * tasks wherein regular activity is performed in response to human     * input, such as automatically repeating a character as long as a key     * is held down.     *     * @param task   task to be scheduled.     * @param firstTime First time at which task is to be executed.     * @param period time in milliseconds between successive task executions.     * @throws IllegalArgumentException if <tt>time.getTime()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    public void schedule(TimerTask task, Date firstTime, long period) {        if (period <= 0)            throw new IllegalArgumentException("Non-positive period.");        sched(task, firstTime.getTime(), -period);    }    /**     * Schedules the specified task for repeated <i>fixed-rate execution</i>,     * beginning after the specified delay.  Subsequent executions take place     * at approximately regular intervals, separated by the specified period.     *     * <p>In fixed-rate execution, each execution is scheduled relative to the     * scheduled execution time of the initial execution.  If an execution is     * delayed for any reason (such as garbage collection or other background     * activity), two or more executions will occur in rapid succession to     * "catch up."  In the long run, the frequency of execution will be     * exactly the reciprocal of the specified period (assuming the system     * clock underlying <tt>Object.wait(long)</tt> is accurate).     *     * <p>Fixed-rate execution is appropriate for recurring activities that     * are sensitive to <i>absolute</i> time, such as ringing a chime every     * hour on the hour, or running scheduled maintenance every day at a     * particular time.  It is also appropriate for for recurring activities     * where the total time to perform a fixed number of executions is     * important, such as a countdown timer that ticks once every second for     * ten seconds.  Finally, fixed-rate execution is appropriate for     * scheduling multiple repeating timer tasks that must remain synchronized     * with respect to one another.     *     * @param task   task to be scheduled.     * @param delay  delay in milliseconds before task is to be executed.     * @param period time in milliseconds between successive task executions.     * @throws IllegalArgumentException if <tt>delay</tt> is negative, or     *         <tt>delay + System.currentTimeMillis()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    public void scheduleAtFixedRate(TimerTask task, long delay, long period) {        if (delay < 0)            throw new IllegalArgumentException("Negative delay.");        if (period <= 0)            throw new IllegalArgumentException("Non-positive period.");        sched(task, System.currentTimeMillis()+delay, period);    }    /**     * Schedules the specified task for repeated <i>fixed-rate execution</i>,     * beginning at the specified time. Subsequent executions take place at     * approximately regular intervals, separated by the specified period.     *     * <p>In fixed-rate execution, each execution is scheduled relative to the     * scheduled execution time of the initial execution.  If an execution is     * delayed for any reason (such as garbage collection or other background     * activity), two or more executions will occur in rapid succession to     * "catch up."  In the long run, the frequency of execution will be     * exactly the reciprocal of the specified period (assuming the system     * clock underlying <tt>Object.wait(long)</tt> is accurate).     *     * <p>Fixed-rate execution is appropriate for recurring activities that     * are sensitive to <i>absolute</i> time, such as ringing a chime every     * hour on the hour, or running scheduled maintenance every day at a     * particular time.  It is also appropriate for for recurring activities     * where the total time to perform a fixed number of executions is     * important, such as a countdown timer that ticks once every second for     * ten seconds.  Finally, fixed-rate execution is appropriate for     * scheduling multiple repeating timer tasks that must remain synchronized     * with respect to one another.     *     * @param task   task to be scheduled.     * @param firstTime First time at which task is to be executed.     * @param period time in milliseconds between successive task executions.     * @throws IllegalArgumentException if <tt>time.getTime()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    public void scheduleAtFixedRate(TimerTask task, Date firstTime,                                    long period) {        if (period <= 0)            throw new IllegalArgumentException("Non-positive period.");        sched(task, firstTime.getTime(), period);    }    /**     * Schedule the specified timer task for execution at the specified     * time with the specified period, in milliseconds.  If period is     * positive, the task is scheduled for repeated execution; if period is     * zero, the task is scheduled for one-time execution. Time is specified     * in Date.getTime() format.  This method checks timer state, task state,     * and initial execution time, but not period.     *     * @param task   task to be scheduled.     * @param time time at which task is to be executed.     * @param period time in milliseconds between successive task executions.     * @throws IllegalArgumentException if <tt>time()</tt> is negative.     * @throws IllegalStateException if task was already scheduled or     *         cancelled, timer was cancelled, or timer thread terminated.     */    private void sched(TimerTask task, long time, long period) {        if (time < 0)            throw new IllegalArgumentException("Illegal execution time.");                synchronized (queue) {            if (!thread.newTasksMayBeScheduled) {                throw new IllegalStateException("Timer already cancelled.");            }	    /*	     * If the TimerThread has exited without an error	     * it is restarted. See the commentary in TimerThread.run.	     */