Source for javax.swing.Timer

   1: /* Timer.java --
   2:    Copyright (C) 2002, 2004, 2005, 2006,  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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.  This is
  50:  * a specialised version of <code>java.util.Timer</code> just for
  51:  * firing <code>ActionEvent</code>s. All Timers share one (daemon)
  52:  * Thread (or java.util.Timer). All events are fired from the event
  53:  * queue.
  54:  * 
  55:  * @author Ronald Veldema
  56:  * @author Audrius Meskauskas (audriusa@Bionformatics.org) - bug fixes
  57:  * and documentation comments
  58:  */
  59: public class Timer
  60:   implements Serializable
  61: {
  62:   /**
  63:    * Given to the shared java.util.Timer to (possibly repeatedly) call
  64:    * queueEvent().
  65:    */
  66:   private class Task extends java.util.TimerTask
  67:   {
  68:     public void run()
  69:     {
  70:       if (logTimers)
  71:         System.out.println("javax.swing.Timer -> queueEvent()");
  72:       queueEvent();
  73: 
  74:       if (!repeats)
  75:         task = null;
  76:     }
  77:   }
  78: 
  79:   /**
  80:    * Use serialVersionUID for interoperability.
  81:    */
  82:   private static final long serialVersionUID = -1116180831621385484L;
  83: 
  84:   /**
  85:    * The encloding class, used with {@link SwingUtilities#invokeLater}
  86:    * to invoke the {@link #drainEvents()}.
  87:    */
  88:   private Runnable drainer = new Runnable()
  89:     {
  90:       public void run()
  91:       {
  92:         drainEvents();
  93:       }
  94:     };
  95: 
  96:   /**
  97:    * The static java.util.Timer daemon which will be used to schedule
  98:    * all javax.swing.Timer.Task objects. The daemon will always be
  99:    * 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: }