Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Management Services with JMX

# Using the WebLogic Timer Service to Generate and Receive Notifications

WebLogic Server includes a timer service that you can configure to emit notifications at specific dates and times or at a constant interval. To listen and respond to these timer notifications, you create a JMX notification listener and register it with the timer service.

The WebLogic timer service extends the standard JMX timer service, enabling it to run within a Weblogic Server execute thread and within the security context of a WebLogic Server user account. (Execute threads enable you to fine-tune your application's use of server resources and optimize performance. For more information, refer to "Using Execute Queues to Control Thread Usage" in WebLogic Server Performance and Tuning.)

The following sections describe how to use the WebLogic timer service:

- Using the WebLogic Timer Service: Main Steps
- Example: Generating a Notification Every Minute
- Removing Notifications

# Using the WebLogic Timer Service: Main Steps

WebLogic Server does not provide a centralized timer service that can be accessed by all resources that are deployed on a specific server instance. Instead, each application constructs and manages instances of the timer service as it requires. Each time you restart a server instance, each application must re-instantiate any timer service configurations it needs.

To configure the WebLogic timer service to emit notifications and to create a listener that receives those notifications, create a class that does the following:

1. Constructs an instance of the `weblogic.management.timer.Timer` MBean.
2. Invokes the `Timer`.`addNotification` API to configure the `Timer` MBean to emit a notification object at a specific time or at a recurring interval.

The class can invoke the `addNotification` API multiple times to configure the `Timer` MBean to emit notification objects at different times and time intervals.

See Configuring a Timer MBean to Emit Notifications.

3. Creates a notification listener with optional filter and registers the listener and filter with the `Timer` MBean.

Your class can register multiple listeners and filters with the `Timer` MBean instance.

For information about creating and registering listeners, refer to Listening for Notifications from WebLogic Server MBeans: Main Steps.

4. Invokes the `Timer.start` method to start an instance of the timer service.

When your listener receives notifications, it can invoke `TimerNotification` methods to retrieve data from the notification.

An application can include multiple classes that construct and configure a `Timer` MBean. Each class uses its own instance of the `Timer` MBean and listens for notifications only from the `Timer` MBean that it instantiated.

# Configuring a Timer MBean to Emit Notifications

To configure a `Timer` MBean instance to emit notifications, you invoke the MBean's `addNotification` method. The method includes parameters that configure the frequency of notifications and specify a handback object.

When you invoke the `addNotification` method, the timer service creates a `TimerNotification` object and returns an identifier for the new object. You can use this identifier to retrieve information about the `TimerNotification` object from the timer or to remove the object from the timer's list of notifications. When the time that you specify arrives, the timer service emits the `TimerNotification` object along with a reference to the handback object.

The method signature for `addNotification` is as follows:

`addNotification (java.lang.String type, java.lang.String message,
java.lang.Object userData,java.util.Date startTime,
long period, long nbOccurences)`

Table 7-1 describes each parameter of the `addNotification` API. For more information, refer to the WebLogic Server Javadoc for `weblogic.management.timer.Timer`.

Table 7-1 Parameters of the addNotification API

Parameter | Description
--- | ---
`java.lang.String type` | A string that you use to identify the event that triggers this notification to be broadcast. For example, you can specify `midnight` for a notification that you configure to be broadcast each day at midnight.
`java.lang.String message` | Specifies the value of the `TimerNotification` object's `message` attribute.
`java.lang.Object userData` | Specifies the name of an object that contains whatever data you want to send to your listeners. Usually, you specify a reference to the class that registered the notification, which functions as a callback.
`java.util.Date startTime` | Specifies a `Date` object that contains the time and day at which the timer emits your notification. For more information, refer to the next section, Specifying Time Intervals.
`long period` | (Optional) Specifies the interval in milliseconds between notification occurrences. Repeating notifications are not enabled if this parameter is zero or is not defined (`null`). For more information, refer to the next section, Specifying Time Intervals.
`long nbOccurences` | (Optional) Specifies the total number of times that the notification will occur. If the value of this parameter is zero or is not defined (`null`) and if the period is not zero or `null`, then the notification will repeat indefinitely. If you specify this parameter, each time the `Timer` MBean emits the associated notification, it decrements the number of occurrences by one. You can use `Timer.getNbOccurrences` method to determine the number of occurrences that remain. When the number of occurrences reaches zero, the `Timer` MBean removes the notification from its list of configured notifications.

## Specifying Time Intervals

To facilitate specifying dates, the `Timer` MBean includes the following integer constants:

- `ONE_SECOND`, which resolves to the number of milliseconds in one second.
- `ONE_MINUTE`, which resolves to the number of milliseconds in one minute.
- `ONE_HOUR`, which resolves to the number of milliseconds in one hour.
- `ONE_DAY`, which resolves to the number of milliseconds in one day.
- `ONE_WEEK`, which resolves to the number of milliseconds in one week.

For example, the following code configures the timer service to emit a `TimerNotification` object once a day at midnight:

java.util.Date`midnight =
` java.util.Calendar.getInstance.set(HOUR_OF_DAY=24:00:00).getTime();
`addNotification (eachMidnight, "the time is midnight",
this,midnight,Timer.ONE_DAY);`

If the time and date that you specify is earlier than the current time and date, the `addNotification` method attempts to update this entry as follows:

- If you provided a value for the `period` parameter, the method increments the `date` value by the `period` value until the date is later than the current date. For example, if you specified `ONE_DAY` for the `period` value, the `addNotification` increments the `date` value one day until it is later than the current date.
- If you provided a value for the `nbOccurrences` parameter, the method updates the notification date as explained above. Each time it increments the `date` value, it decreases the specified number of occurrences by one. If the number of occurrences reaches `0` and the notification date remains earlier than the current date, the method throws `IllegalArgumentException`.
- If you did not provide a value for the `period` parameter, the notification date cannot be updated and the method throws `IllegalArgumentException`.

# Example: Generating a Notification Every Minute

The code in Listing 7-1 is a servlet listener that configures the timer service to emit notifications every minute. It takes the following actions:

1. Extends the `NotificationListener` class so it can listen for notifications from the `Timer` MBean that the class instantiates.

The `handleNotification` method that all listeners must implement is at the end of the class.

2. Instantiates a weblogic.management.timer.Timer MBean.
3. Registers itself with the `Timer` MBean as a notification listener.
4. Invokes the `addNotification` method.

The Date object configures the timer to start emitting this notification 5 seconds after it is added to the `Timer` MBean's notification list. The `PERIOD` value causes the notification to be emitted every minute.

The class attaches itself as the user-defined `userData` object.

Each time the `Timer` MBean emits a notification, it will emit a `TimerNotification` object that contains this object, and whose `Message` attribute contains the string a recurring call, and whose `Type` attribute contains the string `oneMinuteTimer`.

5. Starts the `Timer` MBean instance.

When you redeploy or undeploy the servlet, it invokes it the `Timer.stop` method for the `Timer` MBean instance that is represented by the `timer` variable.

Listing 7-1 Servlet Listener

>     import java.util.Date;

>     import javax.management.Notification;
>     import javax.management.NotificationListener;
>     import javax.management.InstanceNotFoundException;

>     import javax.servlet.ServletContextEvent;
>     import javax.servlet.ServletContextListener;

>     import weblogic.management.timer.Timer;

>     // Implementing NotificationListener
>     public final class LifecycleListener implements ServletContextListener,
>                    NotificationListener {

>         private static final long PERIOD = Timer.ONE_MINUTE;
>         private Timer timer;
>         private Integer notificationId;

>         public void contextInitialized(ServletContextEvent event) {
>             System.out.println(">>> contextInitialized called.");

>             // Instantiating the Timer MBean
>             timer = new Timer();

>             // Registering this class as a listener
>             timer.addNotificationListener(this, null, "some handback object");

>             // Adding the notification to the Timer and assigning the
>             // ID that the Timer returns to a variable
>             Date timerTriggerAt = new Date((new Date()).getTime() + 5000L);
>             notificationId = timer.addNotification("oneMinuteTimer",
>                              "a recurring call", this,
>                              timerTriggerAt, PERIOD);
>             timer.start();
>             System.out.println(">>> timer started.");
>         }

>         public void contextDestroyed(ServletContextEvent event) {
>             System.out.println(">>> contextDestroyed called.");
>             try {
>                 timer.stop();
>                 timer.removeNotification(notificationId);
>                 System.out.println(">>> timer stopped.");
>            } catch (InstanceNotFoundException e) {
>                 e.printStackTrace();
>             }
>         }
>         /* callback method */
>         public void handleNotification(Notification notif, Object handback) {
>                 System.out.println(">>> "+(new Date())+
>                              " timer handleNotification="+notif+
>                              ", handback="+handback);
>         }
>     }

The deployment descriptor for the servlet listener must use the `<listener>` and `<listener-class>` statements to declare the class in the example above. See Listing 7-2.

Listing 7-2 Deployment Descriptor for Servlet Listener

>     <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
>     2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
>     <web-app>
>         <listener>
>             <listener-class>
>                 examples.jmxtimer.LifecycleListener
>             </listener-class>
>         </listener>
>     </web-app>

# Removing Notifications

The `Timer` MBean removes notifications from its list when either of the following occurs:

- A non-repeating notification has been emitted.
- A repeating notification has exhausted its number of occurrences.

The `Timer` MBean also provides the following APIs to remove notifications:

- `removeAllNotifications()`, which remove all notifications that are registered with the `Timer` MBean instance.
- `removeNotification(java.lang.Integer id)`, which removes the notification whose ID matches the ID you specify. The `addNotification` method returns this ID when you invoke it. You can also use `Timer` APIs to retrieve IDs.
- `removeNotifications(java.lang.String type)`, which removes all notifications whose type corresponds to the type that you specify.

To use these remove notification APIs for a given `Timer` MBean instance, add them to the class that you use to instantiate the `Timer` MBean. Wrap each API within a method, similar to the `timer.start()` and `timer.stop()` invocations in Listing 7-1. For example, if you assigned the `Timer` MBean instance to a variable named `timer`, add the following method to your class:

`public void removeMyNotification (java.lang.Integer id) {
timer.removeNotification(id);
}`

For more information, refer to the WebLogic Server Javadoc for `weblogic.management.timer.Timer`.