More agent services: monitors and timers - JMX in Action - page 303

Users add notifications to the timer by invoking one of its addNotification()
methods. (We will examine these methods more closely in a moment.) Through
these methods, a user configures the behavior of the timer surrounding a partic-
ular notification.
For example, you add a notification to the timer by specifying a notification
type, a message, user data, and a date. Apart from the normal notification data
(type, message, and user data) the date is the only behavior-controlling parame-
ter: it tells the timer to send a notification with the provided data on the pro-
vided date. In addition to the date, you can specify the following:
■ Pe r i o d — If specified, indicates that a notification is to be sent repeatedly.
This value supplies the timer with an interval in milliseconds between noti-
fication occurrences. If no period is given, the timer assumes that the noti-
fication should be sent only once.
■ Number of occurrences— Tells the timer how many times to send a particular
notification once its date has been reached.
Each notification added to a Timer MBean should have a date later than the
current date (where date refers to date and time). If you add a notification with
an earlier date, one of three things will happen, depending on the configuration
supplied with the notification:
■ If a period was specified for the notification, the timer will keep adding the
period to the notification date until the date is later than the current date.
When the date is corrected, the notification is added to the timer for sending.
■ If a period and a number of occurrences were specified for the notifica-
tion, then the timer will add the period value to the date as many times as
the number of occurrences value will allow. Each time the period value is
added to the date, the number of occurrences is reduced by one. If the
number of occurrences is reduced to zero, and the date is still earlier than
the current date, an IllegalArgumentException is thrown.
■ An IllegalArgumentException is thrown if no period was specified for the
notification. Without a period value, the timer cannot correct the date.
When a notification is finally added to the timer's notification list, a unique id is
returned to the user. This id identifies the newly added notification and is sent
with each emitted occurrence of the notification. In addition, this id should be
used when retrieving information about a notification to be sent via the other
Timer methods. You will see this as we examine the methods of the Timer class.