Package edu.rit.util

Class Timer

java.lang.Object
edu.rit.util.Timer
public class Timer extends Object
Class Timer controls the execution of a TimerTask's timed actions.

A timer is in one of three states as shown by this state diagram: 

       +---+                   +---+
       |   | stop              |   | start
       |   v                   |   v
    +---------+    start    +---------+   timeout   +-----------+
    |         |------------>|         |------------>|           |
 -->| STOPPED |             | STARTED |             | TRIGGERED |
    |         |<------------|         |<------------|           |
    +---------+     stop    +---------+    start    +-----------+
       ^   ^                     ^                     |     |
       |   |                     |            action() |     | stop
       |   |                     |           performed |     |
       |   |                     |                     |     |
       |   |                     | periodic timeout    |     |
       |   |                     +---------------------+     |
       |   |                       one-shot timeout    |     |
       |   +-------------------------------------------+     |
       |                                                     |
       +-----------------------------------------------------+

When a timer is created, it is associated with a TimerTask. The timer is initially stopped. The timer can then be started in various ways. The timer will then time out at some instant, depending on how it was started. When the timer times out, the timer becomes triggered, and the timer's timer task's action() method is called. The timer task can stop the timer, or it can start the timer again for a different timeout, or it can leave the timer alone. If the timer task does not start or stop the timer, the timer goes into a state determined by the way the timer was originally started. If the timer was started with a periodic timeout, the timer automatically starts itself to time out again after a certain interval. If the timer was started with a one-shot timeout, the timer automatically stops itself.

By calling the appropriate method, a timer may be started to do timeouts in any of the following ways:

  • One-shot timeout. The timer task's action is performed just once at a certain point in time, specified either as an absolute time or as an interval from now.
     
  • Periodic fixed-rate timeout. The timer task's action is performed repeatedly at a given interval. The first action happens at a certain point in time, specified either as an absolute time or as an interval from now. Thereafter, each subsequent action starts at the given repetition interval after the scheduled start of the previous action. Thus, the interval between the scheduled starts of successive actions is always the same, regardless of how long each action takes to complete, and the interval between successive actions may vary, depending on how long each action takes to complete.
     
  • Periodic fixed-interval timeout. The timer task's action is performed repeatedly at a given interval. The first action happens at a certain point in time, specified either as an absolute time or as an interval from now. Thereafter, each subsequent action starts at the given repetition interval after the end of the previous action. Thus, the interval between the starts of successive actions may vary, depending on how long each action takes to complete, and the interval between successive actions is always the same, regardless of how long each action takes to complete.

A Timer object is not constructed directly. Rather, a timer object is created by calling a TimerThread's createTimer() method, giving a timer task to associate with the timer. A single timer thread can control any number of timers. The timer thread is responsible for doing all the timers' timeouts and causing the timers to call the timer tasks' action() methods at the proper times. Since a timer thread does not provide real-time guarantees, the time at which a timer task's action actually starts may be later than when the timeout occurred.

Classes Timer, TimerTask, and TimerThread provide capabilities similar to classes java.util.Timer and java.util.TimerTask. Unlike the latter, they also provide the ability to stop and restart a timer and the ability to deal with race conditions in multithreaded programs.

Version:
15-Dec-2002
Author:
Alan Kaminsky

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    getTimeout()
    Determine the time when this timer is or was scheduled to time out.
    TimerTask
    getTimerTask()
    Returns this timer's timer task.
    boolean
    isStarted()
    Determine whether this timer is started.
    boolean
    isStopped()
    Determine whether this timer is stopped.
    boolean
    isTriggered()
    Determine whether this timer is triggered.
    void
    start(long theInterval)
    Start this timer with a one-shot timeout at the given interval from now.
    void
    start(long theFirstInterval, long theRepetitionInterval)
    Start this timer with a periodic fixed-rate timeout starting at the given interval from now.
    void
    start(Date theTime)
    Start this timer with a one-shot timeout at the given absolute time.
    void
    start(Date theFirstTime, long theRepetitionInterval)
    Start this timer with a periodic fixed-rate timeout starting at the given absolute time.
    void
    startFixedIntervalTimeout(long theFirstInterval, long theRepetitionInterval)
    Start this timer with a periodic fixed-interval timeout starting at the given interval from now.
    void
    startFixedIntervalTimeout(Date theFirstTime, long theRepetitionInterval)
    Start this timer with a periodic fixed-interval timeout starting at the given absolute time.
    void
    stop()
    Stop this timer.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • start

      public void start(Date theTime)
      Start this timer with a one-shot timeout at the given absolute time. If the time denotes a point in the past, the action is performed immediately.
      Parameters:
      theTime - Absolute time at which to perform the action.

    • start

      public void start(long theInterval)
      Start this timer with a one-shot timeout at the given interval from now. If the interval is less than or equal to zero, the action is performed immediately.
      Parameters:
      theInterval - Timeout interval before performing the action (milliseconds).

    • start

      public void start(Date theFirstTime, long theRepetitionInterval)
      Start this timer with a periodic fixed-rate timeout starting at the given absolute time. If the start time denotes a point in the past, the first action is performed immediately. Each subsequent action is started at the given repetition interval after the scheduled start of the previous action.
      Parameters:
      theFirstTime - Absolute time at which to perform the first action.
      theRepetitionInterval - Interval between successive actions (milliseconds).
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theRepetitionInterval <= 0.

    • start

      public void start(long theFirstInterval, long theRepetitionInterval)
      Start this timer with a periodic fixed-rate timeout starting at the given interval from now. If the interval is less than or equal to zero, the first action is performed immediately. Each subsequent action is started at the given repetition interval after the scheduled start of the previous action.
      Parameters:
      theFirstInterval - Timeout interval before performing the first action (milliseconds).
      theRepetitionInterval - Interval between successive actions (milliseconds).
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theRepetitionInterval <= 0.

    • startFixedIntervalTimeout

      public void startFixedIntervalTimeout(Date theFirstTime, long theRepetitionInterval)
      Start this timer with a periodic fixed-interval timeout starting at the given absolute time. If the start time denotes a point in the past, the first action is performed immediately. Each subsequent action is started at the given repetition interval after the end of the previous action.
      Parameters:
      theFirstTime - Absolute time at which to perform the first action.
      theRepetitionInterval - Interval between successive actions (milliseconds).
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theRepetitionInterval <= 0.

    • startFixedIntervalTimeout

      public void startFixedIntervalTimeout(long theFirstInterval, long theRepetitionInterval)
      Start this timer with a periodic fixed-interval timeout starting at the given interval from now. If the interval is less than or equal to zero, the first action is performed immediately. Each subsequent action is started at the given repetition interval after the end of the previous action.
      Parameters:
      theFirstInterval - Timeout interval before performing the first action (milliseconds).
      theRepetitionInterval - Interval between successive actions (milliseconds).
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theRepetitionInterval <= 0.

    • stop

      public void stop()
      Stop this timer.

    • isStopped

      public boolean isStopped()
      Determine whether this timer is stopped.
      Returns:
      True if this timer is in the stopped state, false otherwise.

    • isStarted

      public boolean isStarted()
      Determine whether this timer is started.
      Returns:
      True if this timer is in the started state, false otherwise.

    • isTriggered

      public boolean isTriggered()
      Determine whether this timer is triggered.
      Returns:
      True if this timer is in the triggered state, false otherwise.

    • getTimeout

      public long getTimeout()
      Determine the time when this timer is or was scheduled to time out.

      If the getTimeout() method is called when this timer is in the stopped state, then Long.MAX_VALUE is returned.

      If the getTimeout() method is called when this timer is in the started state, then the getTimeout() method returns the time when the next timeout will occur.

      If the getTimeout() method is called when this timer is in the triggered state, such as by this timer's timer task's action() method, then the getTimeout() method returns the time when the present timeout was scheduled to occur. Since a timer thread provides no real-time guarantees, the time when the timeout actually occurred may be some time later. If desired, the caller can compare the scheduled timeout to the actual time and decide whether it's too late to perform the action.

      Returns:
      Time of scheduled timeout (milliseconds since midnight 01-Jan-1970 UTC).

    • getTimerTask

      public TimerTask getTimerTask()
      Returns this timer's timer task.
      Returns:
      a TimerTask object.