SIP Timers (The SIP Servlet Tutorial)

The SIP Servlet Tutorial

SIP Timers

The SIP timer service is provided by the SIP servlet container to allow SIP applications to schedule and manage timers, and receive notifications when timers expire. Timers are events that can be scheduled to run once at a specific time, or to repeat at configurable intervals. Timers may be persistent, in which case the timer will be preserved across Communications Application Server 1.5 restarts. Persistent timers will be fired on server startup if the server was shut down when the timer was supposed to fire.

Repeating timers can be either fixed-delay or fixed-rate. Both fixed-delay and fixed-rate timers will fire at approximately regular intervals, but fixed-delay timers will fire regardless of whether previous timer firings were late. Fixed-rate timers are rescheduled based on the absolute time.

Managing SIP Timers

The container provides a javax.servlet.sip.TimerService implementation that allows you to create timers, which are javax.servlet.sip.ServletTimer instances. The TimerService interface defines the following methods for creating timers:

Table 1–15 TimerService Timer Creation Methods


Method	Description
`createTimer(SipApplicationSession session, long delay, boolean isPersistent, Serializable info)`	Creates a single, optionally persistent timer associated with the specified SIP application session. The `delay` parameter is the time in milliseconds before a timer fires. The info parameter is the application information delivered when the timer expires.
`createTimer(SipApplicationSession session, long delay, long period, boolean fixedDelay, boolean isPersistent, Serializable info)`	Creates a recurring, optionally persistent timer associated with the specified SIP application session. The `delay` parameter is the time in milliseconds before the timer first fires. The `period` parameter is the time in milliseconds after the first timer firing that the timer will fire again. The `fixedDelay` parameter specifies whether the timer is fixed-delay or fixed-rate. The info parameter is the application information delivered when the timer expires.

The ServletTimer interface defines the following methods for managing a particular timer:

Table 1–16 TimerService Timer Management Methods


Method	Description
`cancel()`	Cancels the timer.
`getApplicationSession()`	Returns the `SipApplicatonSession` instance the timer is associated with.
`getId()`	Returns the ID of the timer as a String.
`getInfo()`	Returns a `Serializable` object of the information specified when the timer was created.
`getTimeRemaining()`	Returns a `long` representing the number of milliseconds until the timer is scheduled to next fire.
`scheduledExecutionTime()`	Returns a `long` representing the most recent time the timer was scheduled to fire. If the timer has not yet fired, the return value is undefined.

For more information on the TimerService interface, see the SIP Servlet 1.1 Javadocs.