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

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:

Constructs an instance of the weblogic.management.timer.Timer MBean.

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.

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.

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.Datemidnight = 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:

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.

Instantiates a weblogic.management.timer.Timer MBean.

Registers itself with the Timer MBean as a notification listener.

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.

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.