/*

 * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import java.util.*;

import java.util.concurrent.atomic.AtomicBoolean;

import java.util.concurrent.locks.*;

import java.awt.*;

import java.awt.event.*;

import java.io.Serializable;

import javax.swing.event.EventListenerList;

/**

 * Fires one or more {@code ActionEvent}s at specified

 * intervals. An example use is an animation object that uses a

 * <code>Timer</code> as the trigger for drawing its frames.

 *<p>

 * Setting up a timer

 * involves creating a <code>Timer</code> object,

 * registering one or more action listeners on it,

 * and starting the timer using

 * the <code>start</code> method.

 * For example,

 * the following code creates and starts a timer

 * that fires an action event once per second

 * (as specified by the first argument to the <code>Timer</code> constructor).

 * The second argument to the <code>Timer</code> constructor

 * specifies a listener to receive the timer's action events.

 *

 *<pre>

 *  int delay = 1000; //milliseconds

 *  ActionListener taskPerformer = new ActionListener() {

 *      public void actionPerformed(ActionEvent evt) {

 *          <em>//...Perform a task...</em>

 *      }

 *  };

 *  new Timer(delay, taskPerformer).start();</pre>

 *

 * <p>

 * {@code Timers} are constructed by specifying both a delay parameter

 * and an {@code ActionListener}. The delay parameter is used

 * to set both the initial delay and the delay between event

 * firing, in milliseconds. Once the timer has been started,

 * it waits for the initial delay before firing its

 * first <code>ActionEvent</code> to registered listeners.

 * After this first event, it continues to fire events

 * every time the between-event delay has elapsed, until it

 * is stopped.

 * <p>

 * After construction, the initial delay and the between-event

 * delay can be changed independently, and additional

 * <code>ActionListeners</code> may be added.

 * <p>

 * If you want the timer to fire only the first time and then stop,

 * invoke <code>setRepeats(false)</code> on the timer.

 * <p>

 * Although all <code>Timer</code>s perform their waiting

 * using a single, shared thread

 * (created by the first <code>Timer</code> object that executes),

 * the action event handlers for <code>Timer</code>s

 * execute on another thread -- the event-dispatching thread.

 * This means that the action handlers for <code>Timer</code>s

 * can safely perform operations on Swing components.

 * However, it also means that the handlers must execute quickly

 * to keep the GUI responsive.

 *

 * <p>

 * In v 1.3, another <code>Timer</code> class was added

 * to the Java platform: <code>java.util.Timer</code>.

 * Both it and <code>javax.swing.Timer</code>

 * provide the same basic functionality,

 * but <code>java.util.Timer</code>

 * is more general and has more features.

 * The <code>javax.swing.Timer</code> has two features

 * that can make it a little easier to use with GUIs.

 * First, its event handling metaphor is familiar to GUI programmers

 * and can make dealing with the event-dispatching thread

 * a bit simpler.

 * Second, its

 * automatic thread sharing means that you don't have to

 * take special steps to avoid spawning

 * too many threads.

 * Instead, your timer uses the same thread

 * used to make cursors blink,

 * tool tips appear,

 * and so on.

 *

 * <p>

 * You can find further documentation

 * and several examples of using timers by visiting

 * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/timer.html"

 * target = "_top">How to Use Timers</a>,

 * a section in <em>The Java Tutorial.</em>

 * For more examples and help in choosing between

 * this <code>Timer</code> class and

 * <code>java.util.Timer</code>,

 * see

 * <a href="http://java.sun.com/products/jfc/tsc/articles/timer/"

 * target="_top">Using Timers in Swing Applications</a>,

 * an article in <em>The Swing Connection.</em>

 * <p>

 * <strong>Warning:</strong>

 * Serialized objects of this class will not be compatible with

 * future Swing releases. The current serialization support is

 * appropriate for short term storage or RMI between applications running

 * the same version of Swing.  As of 1.4, support for long term storage

 * of all JavaBeans<sup><font size="-2">TM</font></sup>

 * has been added to the <code>java.beans</code> package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @see java.util.Timer <code>java.util.Timer</code>

 *

 *

 * @author Dave Moore

 */

public class Timer implements Serializable

{

    /*

     * NOTE: all fields need to be handled in readResolve

     */

    protected EventListenerList listenerList = new EventListenerList();

    // The following field strives to maintain the following:

    //    If coalesce is true, only allow one Runnable to be queued on the

    //    EventQueue and be pending (ie in the process of notifying the

    //    ActionListener). If we didn't do this it would allow for a

    //    situation where the app is taking too long to process the

    //    actionPerformed, and thus we'ld end up queing a bunch of Runnables

    //    and the app would never return: not good. This of course implies

    //    you can get dropped events, but such is life.

    // notify is used to indicate if the ActionListener can be notified, when

    // the Runnable is processed if this is true it will notify the listeners.

    // notify is set to true when the Timer fires and the Runnable is queued.

    // It will be set to false after notifying the listeners (if coalesce is

    // true) or if the developer invokes stop.

    private transient final AtomicBoolean notify = new AtomicBoolean(false);

    private volatile int     initialDelay, delay;

    private volatile boolean repeats = true, coalesce = true;

    private transient final Runnable doPostEvent;

    private static volatile boolean logTimers;

    private transient final Lock lock = new ReentrantLock();

    // This field is maintained by TimerQueue.

    // eventQueued can also be reset by the TimerQueue, but will only ever

    // happen in applet case when TimerQueues thread is destroyed.

    // access to this field is synchronized on getLock() lock.

    transient TimerQueue.DelayedTimer delayedTimer = null;

    private volatile String actionCommand;

    /**

     * Creates a {@code Timer} and initializes both the initial delay and

     * between-event delay to {@code delay} milliseconds. If {@code delay}

     * is less than or equal to zero, the timer fires as soon as it

     * is started. If <code>listener</code> is not <code>null</code>,

     * it's registered as an action listener on the timer.

     *

     * @param delay milliseconds for the initial and between-event delay

     * @param listener  an initial listener; can be <code>null</code>

     *

     * @see #addActionListener

     * @see #setInitialDelay

     * @see #setRepeats

     */

    public Timer(int delay, ActionListener listener) {

        super();

        this.delay = delay;

        this.initialDelay = delay;

        doPostEvent = new DoPostEvent();

        if (listener != null) {

            addActionListener(listener);

        }

    }

    /**

     * DoPostEvent is a runnable class that fires actionEvents to

     * the listeners on the EventDispatchThread, via invokeLater.

     * @see Timer#post

     */

    class DoPostEvent implements Runnable

    {

        public void run() {

            if (logTimers) {

                System.out.println("Timer ringing: " + Timer.this);

            }

            if(notify.get()) {

                fireActionPerformed(new ActionEvent(Timer.this, 0, getActionCommand(),

                                                    System.currentTimeMillis(),

                                                    0));

                if (coalesce) {

                    cancelEvent();

                }

            }

        }

        Timer getTimer() {

            return Timer.this;

        }

    }

    /**

     * Adds an action listener to the <code>Timer</code>.

     *

     * @param listener the listener to add

     *

     * @see #Timer

     */

    public void addActionListener(ActionListener listener) {

        listenerList.add(ActionListener.class, listener);

    }

    /**

     * Removes the specified action listener from the <code>Timer</code>.

     *

     * @param listener the listener to remove

     */

    public void removeActionListener(ActionListener listener) {

        listenerList.remove(ActionListener.class, listener);

    }

    /**

     * Returns an array of all the action listeners registered

     * on this timer.

     *

     * @return all of the timer's <code>ActionListener</code>s or an empty

     *         array if no action listeners are currently registered

     *

     * @see #addActionListener

     * @see #removeActionListener

     *

     * @since 1.4

     */

    public ActionListener[] getActionListeners() {

        return (ActionListener[])listenerList.getListeners(

                ActionListener.class);

    }

    /**

     * Notifies all listeners that have registered interest for

     * notification on this event type.

     *

     * @param e the action event to fire

     * @see EventListenerList

     */

    protected void fireActionPerformed(ActionEvent e) {

        // Guaranteed to return a non-null array

        Object[] listeners = listenerList.getListenerList();

        // Process the listeners last to first, notifying

        // those that are interested in this event

        for (int i=listeners.length-2; i>=0; i-=2) {

            if (listeners[i]==ActionListener.class) {

                ((ActionListener)listeners[i+1]).actionPerformed(e);

            }

        }

    }

    /**

     * Returns an array of all the objects currently registered as

     * <code><em>Foo</em>Listener</code>s

     * upon this <code>Timer</code>.

     * <code><em>Foo</em>Listener</code>s

     * are registered using the <code>add<em>Foo</em>Listener</code> method.

     * <p>

     * You can specify the <code>listenerType</code> argument

     * with a class literal, such as <code><em>Foo</em>Listener.class</code>.

     * For example, you can query a <code>Timer</code>

     * instance <code>t</code>

     * for its action listeners

     * with the following code:

     *

     * <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));</pre>

     *

     * If no such listeners exist,

     * this method returns an empty array.

     *

     * @param listenerType  the type of listeners requested;

     *          this parameter should specify an interface

     *          that descends from <code>java.util.EventListener</code>

     * @return an array of all objects registered as

     *          <code><em>Foo</em>Listener</code>s

     *          on this timer,

     *          or an empty array if no such

     *          listeners have been added

     * @exception ClassCastException if <code>listenerType</code> doesn't

     *          specify a class or interface that implements

     *          <code>java.util.EventListener</code>

     *

     * @see #getActionListeners

     * @see #addActionListener

     * @see #removeActionListener

     *

     * @since 1.3

     */

    public <T extends EventListener> T[] getListeners(Class<T> listenerType) {

        return listenerList.getListeners(listenerType);

    }

    /**

     * Returns the timer queue.

     */

    private TimerQueue timerQueue() {

        return TimerQueue.sharedInstance();

    }

    /**

     * Enables or disables the timer log. When enabled, a message

     * is posted to <code>System.out</code> whenever the timer goes off.

     *

     * @param flag  <code>true</code> to enable logging

     * @see #getLogTimers

     */

    public static void setLogTimers(boolean flag) {

        logTimers = flag;

    }

    /**

     * Returns <code>true</code> if logging is enabled.

     *

     * @return <code>true</code> if logging is enabled; otherwise, false

     * @see #setLogTimers

     */

    public static boolean getLogTimers() {

        return logTimers;

    }

    /**

     * Sets the <code>Timer</code>'s between-event delay, the number of milliseconds

     * between successive action events. This does not affect the initial delay

     * property, which can be set by the {@code setInitialDelay} method.

     *

     * @param delay the delay in milliseconds

     * @see #setInitialDelay

     */

    public void setDelay(int delay) {

        if (delay < 0) {

            throw new IllegalArgumentException("Invalid delay: " + delay);

        }

        else {

            this.delay = delay;

        }

    }

    /**

     * Returns the delay, in milliseconds,

     * between firings of action events.

     *

     * @see #setDelay

     * @see #getInitialDelay

     */

    public int getDelay() {

        return delay;

    }

    /**

     * Sets the <code>Timer</code>'s initial delay, the time

     * in milliseconds to wait after the timer is started

     * before firing the first event. Upon construction, this

     * is set to be the same as the between-event delay,

     * but then its value is independent and remains unaffected

     * by changes to the between-event delay.

     *

     * @param initialDelay the initial delay, in milliseconds

     * @see #setDelay

     */

    public void setInitialDelay(int initialDelay) {

        if (initialDelay < 0) {

            throw new IllegalArgumentException("Invalid initial delay: " +

                                               initialDelay);

        }

        else {

            this.initialDelay = initialDelay;

        }

    }

    /**

     * Returns the <code>Timer</code>'s initial delay.

     *

     * @see #setInitialDelay

     * @see #setDelay

     */

    public int getInitialDelay() {

        return initialDelay;

    }

    /**

     * If <code>flag</code> is <code>false</code>,

     * instructs the <code>Timer</code> to send only one

     * action event to its listeners.

     *

     * @param flag specify <code>false</code> to make the timer

     *             stop after sending its first action event

     */

    public void setRepeats(boolean flag) {

        repeats = flag;

    }

    /**

     * Returns <code>true</code> (the default)

     * if the <code>Timer</code> will send

     * an action event

     * to its listeners multiple times.

     *

     * @see #setRepeats

     */

    public boolean isRepeats() {

        return repeats;

    }

    /**

     * Sets whether the <code>Timer</code> coalesces multiple pending

     * <code>ActionEvent</code> firings.

     * A busy application may not be able

     * to keep up with a <code>Timer</code>'s event generation,

     * causing multiple

     * action events to be queued.  When processed,

     * the application sends these events one after the other, causing the

     * <code>Timer</code>'s listeners to receive a sequence of

     * events with no delay between them. Coalescing avoids this situation

     * by reducing multiple pending events to a single event.

     * <code>Timer</code>s

     * coalesce events by default.

     *

     * @param flag specify <code>false</code> to turn off coalescing

     */

    public void setCoalesce(boolean flag) {

        boolean old = coalesce;

        coalesce = flag;

        if (!old && coalesce) {

            // We must do this as otherwise if the Timer once notified

            // in !coalese mode notify will be stuck to true and never

            // become false.

            cancelEvent();

        }

    }

    /**

     * Returns <code>true</code> if the <code>Timer</code> coalesces

     * multiple pending action events.

     *

     * @see #setCoalesce

     */

    public boolean isCoalesce() {

        return coalesce;

    }

    /**

     * Sets the string that will be delivered as the action command

     * in <code>ActionEvent</code>s fired by this timer.

     * <code>null</code> is an acceptable value.

     *

     * @param command the action command

     * @since 1.6

     */

    public void setActionCommand(String command) {

        this.actionCommand = command;

    }

    /**

     * Returns the string that will be delivered as the action command

     * in <code>ActionEvent</code>s fired by this timer. May be

     * <code>null</code>, which is also the default.

     *

     * @return the action command used in firing events

     * @since 1.6

     */

    public String getActionCommand() {

        return actionCommand;

    }

    /**

     * Starts the <code>Timer</code>,

     * causing it to start sending action events

     * to its listeners.

     *