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.

An SBB obtains access to a TimerFacility object via its JNDI environment. The Timer Facility is bound into JNDI using the name specified by JNDI_NAME.

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.

See Also:

TimerOptions, TimerEvent

Field Summary

Fields

Modifier and Type	Field and Description
static String	JNDI_NAME Constant declaring the JNDI name where a TimerFacility object is bound into an SBB's JNDI environment.

Method Summary

Methods

Modifier and Type	Method and Description
void	cancelTimer(TimerID timerID) Cancel a previously set timer.
ActivityContextInterface	getActivityContextInterface(TimerID timerID) Get a reference to the Activity Context on which a timer was set.
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.

Field Detail

JNDI_NAME

static final String JNDI_NAME

Constant declaring the JNDI name where a TimerFacility object is bound into an SBB's JNDI environment.

The value of this constant is "java:comp/env/slee/facilities/timer".

Since:

SLEE 1.1

See Also:

Constant Field Values

Method Detail

setTimer

TimerID setTimer(ActivityContextInterface aci,
               Address address,
               long expireTime,
               TimerOptions options)
                 throws NullPointerException,
                        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.

Returns:

the timer ID of the timer that was set.

Throws:

NullPointerException - if aci or options is null.

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

TimerID setTimer(ActivityContextInterface aci,
               Address address,
               long startTime,
               long period,
               int numRepetitions,
               TimerOptions options)
                 throws NullPointerException,
                        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.

Returns:

the timer ID of the timer that was set.

Throws:

NullPointerException - if aci or options is null.

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

void cancelTimer(TimerID timerID)
                 throws 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:

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.

getActivityContextInterface

ActivityContextInterface getActivityContextInterface(TimerID timerID)
                                                     throws NullPointerException,
                                                            TransactionRequiredLocalException,
                                                            FacilityException

Get a reference to the Activity Context on which a timer was set. It is possible to obtain a reference to the Activity Context for timers which have expired, however it is not possible to obtain an Activity Context for activities that have already ended in the SLEE.

This method is a mandatory transactional method.

Parameters:

timerID - the timer ID of the timer.

Returns:

an ActivityContextInterface object that encapsulates the Activity Context on which the timer was set. If the underlying activity has already ended, this method returns null.

Throws:

NullPointerException - if timerID is null.

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

FacilityException - if the Activity Context could not be obtained due to a system-level failure.

Since:

SLEE 1.1

getResolution

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

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.