libjava/javax/swing/Timer.java

   1 /* Timer.java --
   2    Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.swing;
  40
  41 import java.awt.event.ActionEvent;
  42 import java.awt.event.ActionListener;
  43 import java.io.Serializable;
  44 import java.util.EventListener;
  45
  46 import javax.swing.event.EventListenerList;
  47
  48 /**
  49  * Fires one or more action events after the specified delay.
  50  * @author Ronald Veldema
  51  * @author Audrius Meskauskas (audriusa@Bionformatics.org) - bug fixes
  52  * and documentation comments
  53  */
  54 public class Timer
  55   implements Serializable
  56 {
  57   /**
  58    * The timer thread
  59    */
  60   private class Waker
  61     extends Thread
  62   {
  63     /**
  64      * Fires events, pausing for required intervals.
  65      */
  66     public void run()
  67     {
  68       running = true;
  69       try
  70         {
  71           sleep(initialDelay);
  72
  73           while (running)
  74             {
  75               try
  76                 {
  77                   sleep(delay);
  78                 }
  79               catch (InterruptedException e)
  80                 {
  81                   return;
  82                 }
  83               queueEvent();
  84
  85               if (logTimers)
  86                 System.out.println("javax.swing.Timer -> clocktick");
  87
  88               if ( ! repeats)
  89                 break;
  90             }
  91           running = false;
  92         }
  93       catch (Exception e)
  94         {
  95         }
  96     }
  97   }
  98
  99   /**
 100    * Use serialVersionUID for interoperability.
 101    */
 102   private static final long serialVersionUID = -1116180831621385484L;
 103
 104   /**
 105    * The encloding class, used with {@link SwingUtilities#invokeLater}
 106    * to invoke the {@link #drainEvents()}.
 107    */
 108   private Runnable drainer = new Runnable()
 109     {
 110       public void run()
 111       {
 112         drainEvents();
 113       }
 114     };
 115
 116   /**
 117    * If <code>true</code>, the timer prints a message to
 118    * {@link System#out} when firing each event.
 119    */
 120   static boolean logTimers;
 121
 122   /**
 123    * A field to store all listeners who are listening to this timer.
 124    */
 125   protected EventListenerList listenerList = new EventListenerList();
 126
 127   /**
 128    * <code>true</code> if the timer coalesces events.
 129    */
 130   boolean coalesce = true;
 131
 132   /**
 133    * <code>true</code> if the timer is firing repetetive events.
 134    */
 135   boolean repeats = true;
 136
 137   /**
 138    * <code>true</code> if the timer is currently active, firing events
 139    * as scheduled.
 140    */
 141   boolean running;
 142
 143   /**
 144    * The delay between subsequent repetetive events.
 145    */
 146   int delay;
 147
 148   /**
 149    * The initial delay before the first event.
 150    */
 151   int initialDelay;
 152
 153   /**
 154    * The number of events that have been already fired by this timer.
 155    * This is used as a numeric identifier for the next event that would
 156    * be fired.
 157    */
 158   int ticks;
 159
 160   /**
 161    * Stores the thread that posts events to the queue at required time
 162    * intervals.
 163    */
 164   private Waker waker;
 165
 166   /**
 167    * This object manages a "queue" of virtual actionEvents, maintained as a
 168    * simple long counter. When the timer expires, a new event is queued,
 169    * and a dispatcher object is pushed into the system event queue. When
 170    * the system thread runs the dispatcher, it will fire as many
 171    * ActionEvents as have been queued, unless the timer is set to
 172    * coalescing mode, in which case it will fire only one ActionEvent.
 173    */
 174   private long queue;
 175
 176   /**
 177    * <code>synchronized(queueLock)</code> replaces
 178    * <code>synchronized(queue)</code> that is not supported by this language.
 179    */
 180   private Object queueLock = new Object();
 181
 182   /**
 183    * Creates a new Timer object.
 184    *
 185    * @param d the default value for both initial and between event delay, in
 186    * milliseconds.
 187    * @param listener the first action listener, can be <code>null</code>.
 188    */
 189   public Timer(int d, ActionListener listener)
 190   {
 191     delay = d;
 192
 193     if (listener != null)
 194       addActionListener(listener);
 195   }
 196
 197   /**
 198    * Get the array of action listeners.
 199    *
 200    * @return the array of action listeners that are listening for the events,
 201    * fired by this timer
 202    *
 203    * @since 1.4
 204    */
 205   public ActionListener[] getActionListeners()
 206   {
 207     return (ActionListener[]) listenerList.getListeners(ActionListener.class);
 208   }
 209
 210   /**
 211    * Sets whether the Timer coalesces multiple pending event firings.
 212    * If the coalescing is enabled, the multiple events that have not been
 213    * fired on time are replaced by the single event. The events may not
 214    * be fired on time if the application is busy.
 215    *
 216    * @param c <code>true</code> (default) to enable the event coalescing,
 217    * <code>false</code> otherwise
 218    */
 219   public void setCoalesce(boolean c)
 220   {
 221     coalesce = c;
 222   }
 223
 224   /**
 225    * Checks if the Timer coalesces multiple pending event firings.
 226    * If the coalescing is enabled, the multiple events that have not been
 227    * fired on time are replaced by the single event. The events may not
 228    * be fired on time if the application is busy.
 229    *
 230    * @return <code>true</code> if the coalescing is enabled,
 231    * <code>false</code> otherwise
 232    */
 233   public boolean isCoalesce()
 234   {
 235     return coalesce;
 236   }
 237
 238   /**
 239    * Get the event listeners of the given type that are listening for the
 240    * events, fired by this timer.
 241    *
 242    * @param listenerType the listener type (for example, ActionListener.class)
 243    *
 244    * @return the array of event listeners that are listening for the events,
 245    * fired by this timer
 246    * @since 1.3
 247    */
 248   public EventListener[] getListeners(Class listenerType)
 249   {
 250     return listenerList.getListeners(listenerType);
 251   }
 252
 253   /**
 254    * Set the timer logging state. If it is set to <code>true</code>, the
 255    * timer prints a message to {@link System#out} when firing each
 256    * action event.
 257    *
 258    * @param lt <code>true</code> if logging is enabled, <code>false</code>
 259    * (default value) otherwise
 260    */
 261   public static void setLogTimers(boolean lt)
 262   {
 263     logTimers = lt;
 264   }
 265
 266   /**
 267    * Return the logging state.
 268    *
 269    * @return <code>true</code> if the timer is printing a message to
 270    * {@link System#out}
 271    * when firing each action event
 272    */
 273   public static boolean getLogTimers()
 274   {
 275     return logTimers;
 276   }
 277
 278   /**
 279    * Set the delay between firing the subsequent events.
 280    * This parameter does not change the value of the initial delay before
 281    * firing the first event.
 282    *
 283    * @param d The time gap between the subsequent events, in milliseconds
 284    */
 285   public void setDelay(int d)
 286   {
 287     delay = d;
 288   }
 289
 290   /**
 291    * Get the delay between firing the subsequent events.
 292    *
 293    * @return The delay between subsequent events, in milliseconds
 294    */
 295   public int getDelay()
 296   {
 297     return delay;
 298   }
 299
 300   /**
 301    * Set the intial delay before firing the first event since calling
 302    * the {@link #start()} method. If the initial delay has not been
 303    * set, it is assumed having the same value as the delay between the
 304    * subsequent events.
 305    *
 306    * @param i the initial delay, in milliseconds
 307    */
 308   public void setInitialDelay(int i)
 309   {
 310     initialDelay = i;
 311   }
 312
 313   /**
 314    * Get the intial delay before firing the first event since calling
 315    * the {@link #start()} method. If the initial delay has not been
 316    * set, returns the same value as {@link #getDelay()}.
 317    *
 318    * @return the initial delay before firing the first action event.
 319    */
 320   public int getInitialDelay()
 321   {
 322     return initialDelay;
 323   }
 324
 325   /**
 326    * Enable firing the repetetive events.
 327    *
 328    * @param r <code>true</code> (default value) to fire repetetive events.
 329    * <code>false</code> to fire
 330    * only one event after the initial delay
 331    */
 332   public void setRepeats(boolean r)
 333   {
 334     repeats = r;
 335   }
 336
 337   /**
 338    * Check is this timer fires repetetive events.
 339    *
 340    * @return <code>true</code> if the timer fires repetetive events,
 341    * <code>false</code> if it fires
 342    * only one event after the initial delay
 343    */
 344   public boolean isRepeats()
 345   {
 346     return repeats;
 347   }
 348
 349   /**
 350    * Get the timer state.
 351    *
 352    * @return <code>true</code> if the timer has been started and is firing
 353    * the action events as scheduled. <code>false</code>
 354    * if the timer is inactive.
 355    */
 356   public boolean isRunning()
 357   {
 358     return running;
 359   }
 360
 361   /**
 362    * Add the action listener
 363    *
 364    * @param listener the action listener to add
 365    */
 366   public void addActionListener(ActionListener listener)
 367   {
 368     listenerList.add(ActionListener.class, listener);
 369   }
 370
 371   /**
 372    * Remove the action listener.
 373    *
 374    * @param listener the action listener to remove
 375    */
 376   public void removeActionListener(ActionListener listener)
 377   {
 378     listenerList.remove(ActionListener.class, listener);
 379   }
 380
 381   /**
 382    * Cancel all pending tasks and fire the first event after the initial
 383    * delay.
 384    */
 385   public void restart()
 386   {
 387     stop();
 388     start();
 389   }
 390
 391   /**
 392    * Start firing the action events.
 393    */
 394   public void start()
 395   {
 396     if (isRunning())
 397       return;
 398     waker = new Waker();
 399     waker.start();
 400   }
 401
 402   /**
 403    * Stop firing the action events.
 404    */
 405   public void stop()
 406   {
 407     running = false;
 408     if (waker != null)
 409       waker.interrupt();
 410     synchronized (queueLock)
 411       {
 412         queue = 0;
 413       }
 414   }
 415
 416   /**
 417    * Fire the given action event to the action listeners.
 418    *
 419    * @param event the event to fire
 420    */
 421   protected void fireActionPerformed(ActionEvent event)
 422   {
 423     ActionListener[] listeners = getActionListeners();
 424
 425     for (int i = 0; i < listeners.length; i++)
 426       listeners [ i ].actionPerformed(event);
 427   }
 428
 429   /**
 430    * Fire the action event, named "Timer" and having the numeric
 431    * identifier, equal to the numer of events that have been
 432    * already fired before.
 433    */
 434   void fireActionPerformed()
 435   {
 436     fireActionPerformed(new ActionEvent(this, ticks++, "Timer"));
 437   }
 438
 439   /**
 440    * Fire the queued action events.
 441    * In the coalescing mode, a single event is fired as a replacement
 442    * for all queued events. In non coalescing mode, a series of
 443    * all queued events is fired.
 444    * This is package-private to avoid an accessor method.
 445    */
 446   void drainEvents()
 447   {
 448     synchronized (queueLock)
 449       {
 450         if (isCoalesce())
 451           {
 452             if (queue > 0)
 453               fireActionPerformed();
 454           }
 455         else
 456           {
 457             while (queue > 0)
 458               {
 459                 fireActionPerformed();
 460                 queue--;
 461               }
 462           }
 463         queue = 0;
 464       }
 465   }
 466
 467   /**
 468   * Post a scheduled event to the event queue.
 469   * Package-private to avoid an accessor method.
 470   */
 471   private void queueEvent()
 472   {
 473     synchronized (queueLock)
 474       {
 475         queue++;
 476         if (queue == 1)
 477           SwingUtilities.invokeLater(drainer);
 478       }
 479   }
 480 }