javax.slee.facilities
Interface TimerFacility


public interface TimerFacility

The Timer Facility allows an SBB entity to set and cancel timers. Timers are identified by a serializable TimerID object. When a new timer is set, the Timer Facility generates a TimerID that identifies the timer. The timer can be cancelled at a later time by passing this TimerID to the cancelTimer(javax.slee.facilities.TimerID) method.

This facility is transactional in nature. Timers are only set or cancelled if the transaction in which their setup or cancellation took place commits successfully. A timer may be set and cancelled in the same transaction, in which case the Timer Facility can consider it never set.

Timer Resolution
Although the unit for the period of a periodic timer is specified in milliseconds, a Timer Facility implementation may be limited by the available clock resolution and/or scheduler implementation of the underlying platform. The approximate timer resolution of the Timer Facility can be obtained via getResolution(), allowing SBB entities to create timers that take into account the timer resolution of the Timer Facility.

SBB JNDI Location:
java:comp/env/slee/facilities/timer

See Also:
TimerOptions, TimerEvent

Method Summary
 void cancelTimer(TimerID timerID)
          Cancel a previously set timer.
 long getDefaultTimeout()
          Get the default timeout period of the Timer Facility.
 long getResolution()
          Get the approximate timer resolution of the Timer Facility.
 TimerID setTimer(ActivityContextInterface aci, Address address, long startTime, long period, int numRepetitions, TimerOptions options)
          Set a periodic timer.
 TimerID setTimer(ActivityContextInterface aci, Address address, long expireTime, TimerOptions options)
          Set a non-periodic timer.
 

Method Detail

setTimer

public TimerID setTimer(ActivityContextInterface aci,
                        Address address,
                        long expireTime,
                        TimerOptions options)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        TransactionRolledbackLocalException,
                        FacilityException
Set a non-periodic timer. A single timer event is generated when the timer expires, after which the timer ceases to exist. The timer event is delivered on the specified Activity Context.

If the expiry time is in the past, the timer event is fired immediately after the transaction commits (subject to the options specified for the timer).

This method is a required transactional method.

Parameters:
aci - the Activity Context on which the timer event should be fired.
address - the optional default address on which the timer event should be fired.
expireTime - the time (in ms since January 1, 1970 UTC) that the timer event should be fired.
options - the desired behavior of the timer.
Throws:
java.lang.NullPointerException - if aci or options is null.
java.lang.IllegalArgumentException - if expireTime is less than zero.
TransactionRolledbackLocalException - if this method was invoked without a valid transaction context and the transaction started by this method failed to commit.
FacilityException - if the timer could not be set due to a system-level failure.

setTimer

public TimerID setTimer(ActivityContextInterface aci,
                        Address address,
                        long startTime,
                        long period,
                        int numRepetitions,
                        TimerOptions options)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        TransactionRolledbackLocalException,
                        FacilityException
Set a periodic timer. When the start time of a periodic timer has been reached, a timer event is generated and the timer continues, generating further timer events at the rate specified by the timer's period. A periodic timer may have either a finite or infinite number of repetitions. Timer events are delivered on the specified Activity Context.

If the start time is in the past, the initial timer event is fired immediately after the transaction commits (subject to the options specified for the timer). Further timer events may be generated (subject to the options specified for the timer) while the timer catches up with the current system time.

This method is a required transactional method.

Parameters:
aci - the Activity Context on which timer events should be fired.
address - the optional default address on which timer events should be fired.
startTime - the time (in ms since January 1, 1970 UTC) at which the periodic timer should first fire.
period - the period (in milliseconds) between timer events.
numRepetitions - the maximum number of timer events that should be generated by the timer. If this argument is 0 an infinitely repeating timer is set.
options - the desired behavior of the timer.
Throws:
java.lang.NullPointerException - if aci or options is null.
java.lang.IllegalArgumentException - if startTime or numRepetitions is less than zero, period is not greater than zero, or the timeout specified in options is greater than period.
TransactionRolledbackLocalException - if this method was invoked without a valid transaction context and the transaction started by this method failed to commit.
FacilityException - if the timer could not be set due to a system-level failure.

cancelTimer

public void cancelTimer(TimerID timerID)
                 throws java.lang.NullPointerException,
                        TransactionRolledbackLocalException,
                        FacilityException
Cancel a previously set timer.

This method has no effect if the timer has already been cancelled.

This method is a required transactional method.

Parameters:
timerID - the timer ID of the timer to cancel.
Throws:
java.lang.NullPointerException - if timerID is null.
TransactionRolledbackLocalException - if this method was invoked without a valid transaction context and the transaction started by this method failed to commit.
FacilityException - if the timer could not be cancelled due to a system-level failure.

getResolution

public long getResolution()
                   throws FacilityException
Get the approximate timer resolution of the Timer Facility.

This method is a non-transactional method.

Returns:
the approximate timer resolution (in milliseconds).
Throws:
FacilityException - if the timer resolution could not be obtained due to a system-level failure.

getDefaultTimeout

public long getDefaultTimeout()
                       throws FacilityException
Get the default timeout period of the Timer Facility.

This method is a non-transactional method.

Returns:
the default timeout period (in milliseconds).
Throws:
FacilityException - if the default timeout period could not be obtained due to a system-level failure.