The XMOJO Project
<< Prev Chapter 3.2.1 Timer Service Next >>

Timer Service


The timer service triggers notifications at specific dates and times; it may also trigger notifications repeatedly at a constant interval. The timer service itself is implemented as an MBean and can be managed. The timer service is capable of sending notification instances of its specific TimerNotification class.

The Timer service is depicted pictorially below to give you a better understanding about how this service works:

How Timer Service Works

Timer Notifications


The timer service manages notifications in two different ways:
  1. Notifications that are triggered only once.
  2. Notifications that are repeated with a definite period and/or number of occurrences.
If a notification has to be triggered from a timer service, that notification has to be added to the list of notifications in the timer service. When a notification is added to the timer service, a unique identifier number will be assigned to that notification.

 Adding Timer Notification 

The timer service maintains an internal list of the dated notifications that it has been asked to send. Notifications can be added to this list using the Timer class addNotification methods. The addNotification method is overloaded. All the addNotification methods take the following notification parameters and a date object:
  1. type -- The notification type string
  2. message -- The notification message string
  3. userData -- The notification's user data object
  4. date -- The date when the notification will occur
public Integer addNotification ( String type, String message, Object userData, Date date ) throws IllegalArgumentException
public Integer addNotification ( String type, String message, Object userData, Date date , long period ) throws IllegalArgumentException  
public Integer addNotification ( String type, String message, Object userData, Date date , long period , long nbOccurences ) throws IllegalArgumentException
public Integer addNotification ( String type, String message, Object userData, Date date , long period , long nbOccurences , boolean fireImmediate ) throws IllegalArgumentException

The overloaded methods, in addition to the notification parameters and date, may take the following optional parameters:
  1. period -- The interval in milliseconds between notification occurrences. If this is zero or null, the notifications will not repeat.
  2. nbOccurences -- The total number of times the notification will occur. If this is zero or null, and if period is not null or non-zero, then notification will repeat indefinitely.
  3. fireImmediate -- If this flag is set true, the first notification will occur at once the notification is added to the timer's list. If this flag is set false, then the first notification will be delayed by the period value specified after the notification is added to the timer's list.
IllegalArgumentException will be thrown either if the date is null, period or nbOccurences is specified with negative values. There are some special cases wherein IllegalArgumentException will be thrown:

 Case 1 

If the date is less than the current date, and if the period is specified zero or null, IllegalArgumentException will be thrown.

 Case 2 

If the date is less than the current date and period is not null. If nbOccurences is specified, the timer updates the date value for every nbOccurence. If the date value does not exceed the current date in the specified number of nbOccurences, IllegalArgumentException will be thrown.

The addNotification method returns the identifier of the new timer notification. This identifier can be used to retrieve information about the notification from the timer or to remove the notification from the timer's list of notifications. However, after a notification has been added to the list of notifications, its associated parameters cannot be updated.

 A Sample code Snippet 

The following code snippet creates a Timer Notification with the following attributes :

Timer Type  :
Register
Timer Message
 : Testing timer service
Timer Date
 : Apr 11, 2002
Timer Interval
 : 5 seconds
No. of Occurrence
 : 2

import javax.management.timer.Timer;
....
....

Timer timer = new Timer ( );

server.registerMBean timer , new ObjectName("Services:type=Timer") );
server.addNotificationListener ( new ObjectName("Services:type=Timer") , notifImpl , nullnew Object( ) );

timer.addNotification "Register" , "Testing timer service" , new String( ) , new Date( 1029244438000L ) , 5000 , 2 );
timer.setSendPastNotifications ( false );
timer.start ( );

In the above code snippet, notifImpl represents a NotificationListener.

After the above notification is registered, the Timer Service sends two notifications to all registered listeners with an interval of five seconds from the date and time specified.

 Receiving Timer Notification 

If a class has to receive timer notifications, it has to register itself as one of the listeners to the timer MBean which is also a notification broadcaster. When the timer is active and the date of a timer notification is due, the timer service broadcasts this notification to all the listeners registered with it. The broadcasted notification contains the notification type, message, userdata, and the notification's identifier within the timer.

 Removing Timer Notification 

When a notification is not repeating or when it has completed its number of occurrences, it is removed from the timer's list of notifications. The notification can also be removed explicitly by calling any of the below methods in the Timer class:
  1. removeNotification(integer) -- The notification identifier number has to be specified. The particular notification matching the identifier number alone will be removed from the list.
  2. removeNotifications(type) -- The notification type has to be specified. All notifications matching the specified type will be removed from the timer's list.
  3. removeAllNotifications -- Empties the timer's list of notifications.

 Starting and Stopping the Timer Service 

The timer service is activated using the start method and deactivated using the stop method. When the timer server is inactive or stopped, no notification will be triggered even if the specified date and time occurs. By setting the sendPastNotifications to true, these lost notifications can be obtained when the timer service is restarted, that is, when it becomes active.

You can determine whether the timer is running or not by invoking the timer method isActive( ). This method returns true, if the timer is running.

Points to Remember
  1. Notifications can be triggered at specified date and time using timer service. Repeated notifications can also be triggered.
  2. Timer service is implemented as a standard MBean and can be managed by registering it with the MBeanServer.
  3. Before the timer service is started and after the timer service is stopped, no notifications will be triggered.
  4. Notifications that are lost when the timer service is inactive can be obtained by setting the sendPastNotifications to true.

<< Prev Home Next >>
Agent Services
Monitor Service