Using MBean Notifications

 

The following sections provide an overview of how to use the various notifications that can be broadcast from WebLogic Server MBeans:

• Overview

• MBean Notification Summary

• Using Basic JMX Notifications

• Working with WebLogic Server Log Notifications

 

---

Overview

All WebLogic Server MBeans implement the javax.management.NotificationBroadcaster interfaces, which means they can emit standard JMX notification types.

To observe MBean notifications, you simply implement the NotificationListener interface in your client application, and register the listener class with the MBeans whose notifications you want to receive. The figure below shows a basic system to monitor notifications using a JSP or Servlet.

A listener class can optionally register a NotificationFilter class, which provides additional control over which notifications the listener receives.

Note: For an complete explanation of JMX notifications and how they work, see the Sun Microsystems J2EE JMX specification.

Making Notifications Available to Outside Clients

The JMX version 1.0 specification does not describe how to make notifications available to clients outside the broadcasting MBean's JVM. WebLogic Server version 6.1 makes notifications available externally via the weblogic.management.RemoteNotificationListener interface.

RemoteNotificationListener extends javax.management.NotificationListener and java.rmi.Remote, making MBean notifications available to external clients via RMI. Remote Java clients simply implement RemoteNotificationListener, rather than NotificationListener, to accept WebLogic MBean notifications, as shown below.

Registration of the remote Java client listener is accomplished through the standard JMX addNotificationListener() method.

 

---

MBean Notification Summary

WebLogic Server notifications use the standard notification classes identified in the JMX 1.0 specification. In addition, WebLogic Server provides additional notification classes and notification helper classes for working with WebLogic Server MBean log notifications. The following sections summarize the notification types and classes that JMX applications can use in WebLogic Server.

Basic JMX Notifications

All WebLogic Server MBeans implement the NotificationBroadcaster interface, and can generate the notification types described in the JMX 1.0 specification. These notification types include:

• javax.management.AttributeChangeNotification, for notifying when an MBean attribute value has been changed, and

• javax.management.MbeanServerNotification, for notifications delegated to the MBean server.

In addition, certain WebLogic Server MBeans support two additional notification types for attributes that have "add" and "remove" methods:

• weblogic.management.AttributeAddNotification is broadcast when an attribute's addAttributeName method is called.

• weblogic.management.AttributeRemoveNotification is broadcast when an attribute's removeAttributeName method is called.

WebLogic Server Log Notifications

WebLogic Server provides the LogBroadcasterRuntime MBean, whose sole responsibility is to broadcast log messages. Client applications that need to listen for log notifications can simply register with the LogBroadcasterRuntime MBean.

A notification that represents a WebLogic Server log message contains many additional pieces of information, such as:

• The name of the machine that issued the log message

• The name of the WebLogic Server that issued the log message

• The log message ID number

To help JMX applications extract and use this WebLogic Server log information, BEA provides the WebLogicLogNotification wrapper class. WebLogicLogNotification provides simple getter methods to extract parts of the log message, as well as methods to obtain the transaction ID, user ID, and version number associated with the message.

Working with WebLogic Server Log Notifications provides details on using the log notification supporting classes and interfaces.

 

---

Using Basic JMX Notifications

To receive WebLogic MBean notifications, an external client application must:

1. Implement the RemoteNotificationListener interface.

2. Register the listener class implementation with the MBean(s) whose notifications you want to receive.

The following sections describe these basic steps.

Creating a Notification Listener

The notification listener class is responsible for handling the JMX notifications broadcast by one or more MBeans. If your JMX application resides outside of the broadcasting MBean's JVM, the listener class should implement weblogic.management.RemoteNotificationListener, supplying a handleNotification() class to perform actions when notifications are received. An example implementation follows:

import javax.management.Notification;

import javax.management.NotificationFilter;

import javax.management.NotificationListener;

import javax.management.Notification.*;

...

public class WebLogicLogNotificationListener implements

                RemoteNotificationListener {

...

public void handleNotification(Notification notification, Object obj) {

        WebLogicLogNotification wln = (WebLogicLogNotification)notification;

        System.out.println("WebLogicLogNotification");

        System.out.println("         type = " +

                           wln.getType());

        System.out.println("   message id = " +

                           wln.getMessageId());

        System.out.println("  server name = " +

                           wln.getServername());

        System.out.println("    timestamp = " +

                           wln.getTimeStamp());

        System.out.println("      message = " +

                           wln.getMessage() + "\n");

    }

Registering Notification Listeners with MBeans

Because all WebLogic Server MBeans are notification broadcasters, it is possible to register a NotificationListener with any available MBean. Registering a NotificationListener can be accomplished by calling the MBean's addNotificationListener() method.

However, in most cases it is preferable to register a listener using the MBean server's addNotificationListener() method. Using the javax.management.MBeanServer interface saves the trouble of looking up a particular MBean simply for registration purposes. For example, to listener defined in Creating a Notification Listener registers itself using:

rmbs = home.getMBeanServer();

oname = new WebLogicObjectName("TheLogBroadcaster",

                "LogBroadcasterRuntime",

                DOMAIN_NAME,

                SERVER_NAME);

rmbs.addNotificationListener(oname,

                listener,

                null,

                null);

 

---

Working with WebLogic Server Log Notifications

To receive log messages, client applications can use the standard JMX API to register a notification listener with the WebLogic Server LogBroadcasterRuntimeMBean, as shown in the previous examples. LogBroadcasterRuntimeMBean is responsible for generating notifications for log messages generated by a server.

All notifications broadcast by LogBroadcasterRuntimeMBean are of the type WebLogicLogNotification. There is only one LogBroadcasterRuntimeMBean per server, named TheLogBroadcaster.

The LogBroadcasterRuntimeMBean can be accessed using the mechanisms described in Accessing MBeans from MBeanHome.

Contents of a WebLogicLogNotification

All JMX notifications for a WebLogic Server log message contain the following fields:

• Type—the type field to which the log notification is mapped. This field has the format:

  weblogic.logMessage.subSystem.messageID

  where subSystem indicates the WebLogic Server subsystem that issued the log message, and messageID indicates the internal WebLogic Server message ID.

• Time stamp—the time at which the log message causing this notification was generated by the server.

• Sequence number.

• Message—contains the actual message body of the log message.

• User data—the user data field is not currently used.

All log notifications are of the type WebLogicLogNotification. This helper class provides getter methods for all individual fields of a log message. Using the WebLogicLogNotification class, a client application can easily filter log notifications based on their severity, user ID, subsystem, and other fields.

The following NotificationFilter example uses the WebLogicLogNotification class to select only messages of a specific message ID (111000) to be sent as notifications.

import javax.management.Notification;

import javax.management.NotificationFilter;

import javax.management.Notification.*;

....

public class WebLogicLogNotificationFilter implements NotificationFilter,

                                              java.io.Serializable {

public WebLogicLogNotificationFilter() {

        subsystem = "";

    } 

public boolean isNotificationEnabled(Notification notification) {

                if (!(notification instanceof WebLogicLogNotification)) {

            return false;

        }

        WebLogicLogNotification wln = (WebLogicLogNotification)notification;

        if (subsystem == null ||

            subsystem.equals("")) {

            return true;

        }

                StringTokenizer tokens = new StringTokenizer(wln.getType(), ".");

        tokens.nextToken();

        tokens.nextToken();

        return (tokens.nextToken().equals(subsystem));

    }

    public void setSubsystemFilter(String newSubsystem) {

        subsystem = newSubsystem;

    }

}

Example Notification Listeners for WebLogic Server Error Messages

Client applications can create various custom NotificationListeners that receive log messages as notifications and perform actions such as:

• E-mailing the WebLogic administrator with critical log messages

• Adding log messages to a datastore

The basic form of the notification listener differs little from the example shown in Creating a Notification Listener. Simply replace the printed messages in that example with the necessary JDBC calls or paging operations to perform in response to the notification.