ServletTimer

The ServletTimer interface provides a mechanism for SIP servlet applications to schedule and manage future tasks. Created through the TimerService, it enables applications to handle events based on time, such as expiring sessions, delayed actions, or periodic tasks.

This interface offers methods to retrieve information about a timer: unique identifier, associated application session, and the scheduled execution time. It also includes functionality to cancel timers, query remaining time until expiration, and access metadata passed during timer creation.

By supporting both one-time and recurring timers, ServletTimer ensures flexibility to implement time-driven logic in SIP applications. Enhances the ability to manage session lifecycle, optimize resource usage, and create time-dependent workflows.

Methods:

getId
java.lang.String getId()
The method retrieves the unique identifier assigned to a specific timer task. This identifier is generated by the servlet container and may vary across implementations.
Returns:
A string representing the unique identifier of the timer task.

getApplicationSession
SipApplicationSession getApplicationSession()
The method enables access to the application session related to the timer, allowing the application to manage session-specific operations or data when the timer expires.
Returns:
The SipApplicationSession object that is linked to this ServletTimer.

getInfo
java.io.Serializable getInfo()
The getInfo method retrieves the information associated with the timer at the time of its creation. This information is a user-defined, serializable object that was passed as an argument when the timer was created. This method allows applications to retrieve custom metadata or context-specific information that was associated with the timer during its initialization.
Returns:

• A Serializable object containing the user-defined information associated with the timer.
• Returns null if no information was provided at the timer's creation.

scheduledExecutionTime
long scheduledExecutionTime()
The method retrieves the scheduled expiration time of the most recent actual expiration of this timer. It provides the exact time when the timer was supposed to expire. This method is often used with time-sensitive tasks to ensure the callback is executed within a tolerable delay. It is generally not used for fixed-delay repeating tasks since their scheduled execution times may drift over time. If the callback is delayed beyond a certain threshold, the scheduled task may be skipped to avoid outdated operations.
Returns:
A long value representing the scheduled expiration time of the most recent expiration, in milliseconds since the epoch (as returned by Date.getTime()).
The return value is undefined if the timer has not expired yet for the first time.

cancel
void cancel()
The method stops a timer from triggering any further scheduled expirations. This applies to both one-time and repeating timers.
For one-time timers: If the timer has not yet expired or been scheduled, it will not execute.
For repeating timers: The timer will not trigger any further expirations after cancellation, even if the method is called during an active timerFired callback.
Calling this method on a repeating ServletTimer from within the timerFired method ensures that the timer does not fire again unless it is explicitly rescheduled.
The method can be called multiple times. Any calls after the first will have no additional effect.

getTimeRemaining
long getTimeRemaining()
The method calculates the remaining time, in milliseconds, until the next scheduled expiration of a timer. Works for both one-time and repeating timers. For one-time timers that have already expired, it returns a negative value representing how long ago the expiration occurred. For repeating timers, it calculates the time remaining for the next scheduled occurrence.
Returns:
A positive number indicates the time remaining until the next expiration. A negative number indicates the timer has already expired, and the value represents the elapsed time since expiration.