001    /* Timer.java --
002       Copyright (C) 2002, 2004, 2005, 2006,  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath 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 for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing;
040    
041    import java.awt.event.ActionEvent;
042    import java.awt.event.ActionListener;
043    import java.io.Serializable;
044    import java.util.EventListener;
045    
046    import javax.swing.event.EventListenerList;
047    
048    /**
049     * Fires one or more action events after the specified delay.  This is
050     * a specialised version of <code>java.util.Timer</code> just for
051     * firing <code>ActionEvent</code>s. All Timers share one (daemon)
052     * Thread (or java.util.Timer). All events are fired from the event
053     * queue.
054     *
055     * @author Ronald Veldema
056     * @author Audrius Meskauskas (audriusa@Bionformatics.org) - bug fixes
057     * and documentation comments
058     */
059    public class Timer
060      implements Serializable
061    {
062      /**
063       * Given to the shared java.util.Timer to (possibly repeatedly) call
064       * queueEvent().
065       */
066      private class Task extends java.util.TimerTask
067      {
068        public void run()
069        {
070          if (logTimers)
071            System.out.println("javax.swing.Timer -> queueEvent()");
072          queueEvent();
073    
074          if (!repeats)
075            task = null;
076        }
077      }
078    
079      /**
080       * Use serialVersionUID for interoperability.
081       */
082      private static final long serialVersionUID = -1116180831621385484L;
083    
084      /**
085       * The encloding class, used with {@link SwingUtilities#invokeLater}
086       * to invoke the {@link #drainEvents()}.
087       */
088      private Runnable drainer = new Runnable()
089        {
090          public void run()
091          {
092            drainEvents();
093          }
094        };
095    
096      /**
097       * The static java.util.Timer daemon which will be used to schedule
098       * all javax.swing.Timer.Task objects. The daemon will always be
099       * running, even if there's no task scheduled in it.
100       */
101      private static java.util.Timer timer = new java.util.Timer("swing.Timer",
102                                                                 true);
103    
104      /**
105       * If <code>true</code>, the timer prints a message to
106       * {@link System#out} when firing each event.
107       */
108      static boolean logTimers;
109    
110      /**
111       * A field to store all listeners who are listening to this timer.
112       */
113      protected EventListenerList listenerList = new EventListenerList();
114    
115      /**
116       * <code>true</code> if the timer coalesces events.
117       */
118      boolean coalesce = true;
119    
120      /**
121       * <code>true</code> if the timer is firing repetetive events.
122       */
123      boolean repeats = true;
124    
125      /**
126       * The delay between subsequent repetetive events.
127       */
128      int delay;
129    
130      /**
131       * The initial delay before the first event.
132       */
133      int initialDelay;
134    
135      /**
136       * The number of events that have been already fired by this timer.
137       * This is used as a numeric identifier for the next event that would
138       * be fired.
139       */
140      int ticks;
141    
142      /**
143       * The task that calls queueEvent(). When null this Timer is stopped.
144       * This is package private to avoid synthetic accessor method.
145       */
146      Task task;
147    
148      /**
149       * This object manages a "queue" of virtual actionEvents, maintained as a
150       * simple long counter. When the timer expires, a new event is queued,
151       * and a dispatcher object is pushed into the system event queue. When
152       * the system thread runs the dispatcher, it will fire as many
153       * ActionEvents as have been queued, unless the timer is set to
154       * coalescing mode, in which case it will fire only one ActionEvent.
155       */
156      private long queue;
157    
158      /**
159       * <code>synchronized(queueLock)</code> replaces
160       * <code>synchronized(queue)</code> that is not supported by this language.
161       */
162      private Object queueLock = new Object();
163    
164      /**
165       * Creates a new Timer object.
166       *
167       * @param d the default value for both initial and between event delay, in
168       * milliseconds.
169       * @param listener the first action listener, can be <code>null</code>.
170       */
171      public Timer(int d, ActionListener listener)
172      {
173        delay = d;
174        initialDelay = d;
175    
176        if (listener != null)
177          addActionListener(listener);
178      }
179    
180      /**
181       * Get the array of action listeners.
182       *
183       * @return the array of action listeners that are listening for the events,
184       * fired by this timer
185       *
186       * @since 1.4
187       */
188      public ActionListener[] getActionListeners()
189      {
190        return (ActionListener[]) listenerList.getListeners(ActionListener.class);
191      }
192    
193      /**
194       * Sets whether the Timer coalesces multiple pending event firings.
195       * If the coalescing is enabled, the multiple events that have not been
196       * fired on time are replaced by the single event. The events may not
197       * be fired on time if the application is busy.
198       *
199       * @param c <code>true</code> (default) to enable the event coalescing,
200       * <code>false</code> otherwise
201       */
202      public void setCoalesce(boolean c)
203      {
204        coalesce = c;
205      }
206    
207      /**
208       * Checks if the Timer coalesces multiple pending event firings.
209       * If the coalescing is enabled, the multiple events that have not been
210       * fired on time are replaced by the single event. The events may not
211       * be fired on time if the application is busy.
212       *
213       * @return <code>true</code> if the coalescing is enabled,
214       * <code>false</code> otherwise
215       */
216      public boolean isCoalesce()
217      {
218        return coalesce;
219      }
220    
221      /**
222       * Get the event listeners of the given type that are listening for the
223       * events, fired by this timer.
224       *
225       * @param listenerType the listener type (for example, ActionListener.class)
226       *
227       * @return the array of event listeners that are listening for the events,
228       * fired by this timer
229       * @since 1.3
230       */
231      public <T extends EventListener> T[] getListeners(Class<T> listenerType)
232      {
233        return listenerList.getListeners(listenerType);
234      }
235    
236      /**
237       * Set the timer logging state. If it is set to <code>true</code>, the
238       * timer prints a message to {@link System#out} when firing each
239       * action event.
240       *
241       * @param lt <code>true</code> if logging is enabled, <code>false</code>
242       * (default value) otherwise
243       */
244      public static void setLogTimers(boolean lt)
245      {
246        logTimers = lt;
247      }
248    
249      /**
250       * Return the logging state.
251       *
252       * @return <code>true</code> if the timer is printing a message to
253       * {@link System#out}
254       * when firing each action event
255       */
256      public static boolean getLogTimers()
257      {
258        return logTimers;
259      }
260    
261      /**
262       * Set the delay between firing the subsequent events.
263       * This parameter does not change the value of the initial delay before
264       * firing the first event.
265       *
266       * @param d The time gap between the subsequent events, in milliseconds
267       *
268       * @throws IllegalArgumentException if <code>d</code> is less than zero.
269       */
270      public void setDelay(int d)
271      {
272        if (d < 0)
273          throw new IllegalArgumentException("Invalid delay: " + d);
274        delay = d;
275      }
276    
277      /**
278       * Get the delay between firing the subsequent events.
279       *
280       * @return The delay between subsequent events, in milliseconds
281       */
282      public int getDelay()
283      {
284        return delay;
285      }
286    
287      /**
288       * Set the intial delay before firing the first event since calling
289       * the {@link #start()} method. If the initial delay has not been
290       * set, it is assumed having the same value as the delay between the
291       * subsequent events.
292       *
293       * @param i the initial delay, in milliseconds
294       *
295       * @throws IllegalArgumentException if <code>i</code> is less than zero.
296       */
297      public void setInitialDelay(int i)
298      {
299        if (i < 0)
300          throw new IllegalArgumentException("Invalid initial delay: " + i);
301        initialDelay = i;
302      }
303    
304      /**
305       * Get the intial delay before firing the first event since calling
306       * the {@link #start()} method. If the initial delay has not been
307       * set, returns the same value as {@link #getDelay()}.
308       *
309       * @return the initial delay before firing the first action event.
310       */
311      public int getInitialDelay()
312      {
313        return initialDelay;
314      }
315    
316      /**
317       * Enable firing the repetetive events.
318       *
319       * @param r <code>true</code> (default value) to fire repetetive events.
320       * <code>false</code> to fire
321       * only one event after the initial delay
322       */
323      public void setRepeats(boolean r)
324      {
325        repeats = r;
326      }
327    
328      /**
329       * Check is this timer fires repetetive events.
330       *
331       * @return <code>true</code> if the timer fires repetetive events,
332       * <code>false</code> if it fires
333       * only one event after the initial delay
334       */
335      public boolean isRepeats()
336      {
337        return repeats;
338      }
339    
340      /**
341       * Get the timer state.
342       *
343       * @return <code>true</code> if the timer has been started and is firing
344       * the action events as scheduled. <code>false</code>
345       * if the timer is inactive.
346       */
347      public boolean isRunning()
348      {
349        return task != null;
350      }
351    
352      /**
353       * Add the action listener
354       *
355       * @param listener the action listener to add
356       */
357      public void addActionListener(ActionListener listener)
358      {
359        listenerList.add(ActionListener.class, listener);
360      }
361    
362      /**
363       * Remove the action listener.
364       *
365       * @param listener the action listener to remove
366       */
367      public void removeActionListener(ActionListener listener)
368      {
369        listenerList.remove(ActionListener.class, listener);
370      }
371    
372      /**
373       * Cancel all pending tasks and fire the first event after the initial
374       * delay.
375       */
376      public void restart()
377      {
378        stop();
379        start();
380      }
381    
382      /**
383       * Start firing the action events.
384       */
385      public void start()
386      {
387        Task t = task;
388        if (t == null)
389          {
390            t = new Task();
391            if (isRepeats())
392              timer.schedule(t, getInitialDelay(), getDelay());
393            else
394              timer.schedule(t, getInitialDelay());
395            task = t;
396          }
397      }
398    
399      /**
400       * Stop firing the action events.
401       */
402      public void stop()
403      {
404        Task t = task;
405        if (t != null)
406          {
407            t.cancel();
408            task = null;
409          }
410      }
411    
412      /**
413       * Fire the given action event to the action listeners.
414       *
415       * @param event the event to fire
416       */
417      protected void fireActionPerformed(ActionEvent event)
418      {
419        ActionListener[] listeners = getActionListeners();
420    
421        for (int i = 0; i < listeners.length; i++)
422          listeners [ i ].actionPerformed(event);
423      }
424    
425      /**
426       * Fire the action event, named "Timer" and having the numeric
427       * identifier, equal to the numer of events that have been
428       * already fired before.
429       */
430      void fireActionPerformed()
431      {
432        fireActionPerformed(new ActionEvent(this, ticks++, "Timer"));
433      }
434    
435      /**
436       * Fire the queued action events.
437       * In the coalescing mode, a single event is fired as a replacement
438       * for all queued events. In non coalescing mode, a series of
439       * all queued events is fired.
440       * This is package-private to avoid an accessor method.
441       */
442      void drainEvents()
443      {
444        synchronized (queueLock)
445          {
446            if (isCoalesce())
447              {
448                if (queue > 0)
449                  fireActionPerformed();
450              }
451            else
452              {
453                while (queue > 0)
454                  {
455                    fireActionPerformed();
456                    queue--;
457                  }
458              }
459            queue = 0;
460          }
461      }
462    
463      /**
464      * Post a scheduled event to the event queue.
465      * Package-private to avoid an accessor method.
466      */
467      void queueEvent()
468      {
469        synchronized(queueLock)
470          {
471            queue++;
472            if (queue == 1)
473              SwingUtilities.invokeLater(drainer);
474          }
475      }
476    }