Listening for Messages from the WebLogic Server Log

Each WebLogic Server instance broadcasts its log messages in the form of JMX notifications. The broadcast includes all messages (except those of the DEBUG severity level) that the WebLogic Server instance, its subsystems, and any applications write to the WebLogic Server log. An Administration Server listens for these notifications and places a subset of them in the domain-wide message log. (See Figure 1-1, "WebLogic Server Logging Services," on page 1-6.)

Your application also can listen for log messages that are broadcast from a WebLogic Server instance. For example, your application can listen for a log message that signals the failure of a specific subsystem. Then your application can perform actions such as:

• E-mail the log message to the WebLogic Server administrator.
• Shut down or restart itself or its subcomponents.

To listen for these notifications, you create a notification listener and register it with the WebLogic Server broadcast MBean, LogBroadcasterRuntimeMBean. A notification listener is an implementation of the JMX NotificationListener interface. When LogBroadcasterRuntimeMBean emits a notification, it uses the registered listener's handleNotification method to pass a WebLogicLogNotification object. (See Figure 4-1.)

Figure 4-1 WebLogic Broadcaster and Your Listener

A subsequent subsection, WebLogicLogNotification Objects, provides more information about WebLogicLogNotification objects

To enable your application to listen for notifications from a WebLogic Server log, complete the following tasks:

• Step 1: Create a Notification Listener
• Step 2: Register the Notification Listener
• Step 3: Create and Register a Notification Filter

Note: If your application runs outside a WebLogic Server JVM, it can listen for WebLogic Server log notifications, but it cannot use WebLogic logging services to broadcast messages.

 

---

Step 1: Create a Notification Listener

The steps that you follow to create a notification listener differ depending on whether your application runs within a WebLogic Server JVM.

This section contains the following subsections:

• Creating a Notification Listener for an Application that Runs Within a WebLogic Server JVM
• Creating a Notification Listener for a Remote Application

Creating a Notification Listener for an Application that Runs Within a WebLogic Server JVM

If your application runs within a WebLogic Server JVM, do the following:

1. Import the javax.management.Notification.* interfaces. Because WebLogic Server already includes these interfaces and requires them to be on the classpath, you need only to include an import statement in your class.
2. Create a class that implements NotificationListener. Your implementation must include the NotificationListener.handleNotification() method.

   For more information on NotificationListener, refer to the javax.management.Notification Javadoc, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html.

Figure 4-2 shows a system in which a JSP is running within a WebLogic Server JVM. The JSP listens for notifications from LogBroadcasterRuntimeMBean.

Figure 4-2 Listener for a Local JSP

Listing 4-1 provides an example notification listener for a local client. The listener uses WebLogicLogNotification getter methods to print all messages that it receives. For more information, refer to WebLogicLogNotification Objects.

Listing 4-1 Example Notification Listener for a Local Client

import javax.management.Notification;
import javax.management.NotificationListener;

...

public class MyNotificationListener implements
    NotificationListener {

...

public void handleNotification(Notification notification, Object handback) {
    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");
}

Creating a Notification Listener for a Remote Application

If your application resides outside of the WebLogic Server JVM, do the following:

1. Make sure that WL_HOME/server/lib/weblogic_sp.jar and WL_HOME/server/lib/weblogic.jar are in the application's classpath.
2. Import the javax.management.Notification.* interfaces.
3. Create a class that implements weblogic.management.RemoteNotificationListener. RemoteNotificationListener MBean makes notifications available to remote applications via RMI by extending javax.management.NotificationListener and java.rmi.

   Your implementation must include the RemoteNotificationListener.handleNotification() method. For more information, refer to the weblogic.management.RemoteNotificationListener Javadoc.

Figure 4-3 shows a system in which a JSP runs in the WebLogic Server JVM and an application runs in a remote JVM. To listen for notifications, the JSP implements NotificationListener and the remote application implements RemoteNotificationListener.

Figure 4-3 Local JSP and Remote Application

Listing 4-2 provides an example notification listener for a remote client.

Listing 4-2 Example Notification Listener for a Remote Client

import javax.management.Notification;
import javax.management.NotificationListener;

import weblogic.management.RemoteNotificationListener;
import weblogic.management.logging.WebLogicLogNotification;

...

public class MyRemoteNotificationListener implements
    RemoteNotificationListener {

...

public void handleNotification(Notification notification, Object handback) {
    WebLogicLogNotification wln = (WebLogicLogNotification)notification;
}

 

---

Step 2: Register the Notification Listener

After you implement your notification listener, you must register it with LogBroadcasterRuntimeMBean on a WebLogic Server instance. Because each instance broadcasts its own notifications, you must register your notification listener on each WebLogic Server instance from which you want to receive notifications.

This section describes the code fragment that you use to register a listener. You can add this fragment to a class that runs when your client application starts, when a WebLogic Server instance starts, or whenever you want your application to receive notifications.

To register with the LogBroadcasterRuntimeMBean on a WebLogic Server instance, the code must do the following:

1. Import the following interfaces:

   javax.naming.Context
   javax.naming.InitialContext
   javax.naming.AuthenticationException
   javax.naming.CommunicationException
   javax.naming.NamingException
   weblogic.jndi.Environment
   weblogic.management.MBeanHome

2. Obtain the MBeanServer from MBeanHome. For more information, refer to Accessing WebLogic Server MBeans in the Using WebLogic JMX Services Guide.
3. Use the addNotificationListener() method of the MBeanServer to register your notification listener with LogBroadcasterRuntimeMBean.

Using the addNotificationListener API

The syntax for the addNotificationListener API is as follows:

MBeanServer.addNotificationListener(ObjectName name,
     NotificationListener listener,
     NotificationFilter filter,
     java.lang.Object handback)

Provide the following values:

• name is the object name of the WebLogic Server instance's LogBroadcasterRuntimeMBean. You can obtain the object name by doing one of the following:
• Creating an instance weblogic.management.WebLogicObjectName. For more information, refer to the WebLogicObjectName Javadoc.
• Looking up the weblogic.management.runtime.LogBroadcasterRuntimeMBean at runtime and calling .getObjectName(). For more information, refer to the LogBroadcasterRuntimeMBean Javadoc.
• Using the weblogic.Admin GET command. For more information, refer to the GET command in the WebLogic Server Command Line Reference.
• listener is the instance of the Notification listener you created in Step 1: Create a Notification Listener.
• filter is a filter object. If filter is null, no filtering will be performed before handling notifications. The next section, Step 3: Create and Register a Notification Filter, describes creating and registering a filter object.
• handback is the context to be sent to the listener when a notification is broadcast.

Complete documentation for the addNotificationListener API is available in the Javadoc for javax.management.MBeanServer, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html.

Examples for Registering a Notification Listener

The following examples register the listener defined in Step 1: Create a Notification Listener. The examples in Listing 4-3 and Listing 4-4 do the following:

1. Use the weblogic.management.Helper API to obtain the server-specific MBeanHome interface for a server named peach. For more information about obtaining the MBeanHome interface, refer to Accessing WebLogic Server MBeans in the Programming WebLogic Management Services with JMX guide.
2. Use the MBeanHome interface to retrieve the corresponding MBeanServer interface.
3. Use a different method for retrieving the LogBroadcasterRuntimeMBean object name.
4. Instantiate the listener object defined in Step 1: Create a Notification Listener.
5. Use the addNotificationListener method of the ServerMBean interface to register the listener object with the LogBroadcasterRuntimeMBean.

Listing 4-3 uses WebLogicObjectName to construct the LogBroadcasterRuntimeMBean object name.

Listing 4-3 Using WebLogicObjectName

public void find(String host, int port, String username, String password,
                 String hostname, String myDomain, String myServer)
{
    String url = "t3://" + host + ":" + port;

    //Get the server's MBeanHome interface.
     try {
          serverSpecificHome = (MBeanHome)Helper.getMBeanHome(                                 username, password, url, hostname);
     } catch (IllegalArgumentException iae) {
           System.out.println("Illegal Argument Exception: " + iae);
     } 

    //Use MBeanHome to get the server's MBeanServer interface.
    MBeanServer mServer = serverSpecificHome.getMBeanServer();

   //Construct the WebLogicObjectName of the server's LogBroadcasterRuntimeMBean.
    WebLogicObjectName logBCOname = new WebLogicObjectName(
         "WebLogicLogBroadcaster","LogBroadcasterRuntime",myDomain,myServer);

    //Instantiate a listener object.
   MyRemoteNotificationListener myListener = new MyRemoteNotificationListener();

    //Register the listener.
    mServer.addNotificationListener( logBCOname,myListener,null,null );
}

Listing 4-4 uses MBeanHome.getMBeanByClass to retrieve the LogBroadcasterRuntimeMBean object name.

Listing 4-4 Using getObjectName()

public void find(String host, int port, String username, String password,
                 String hostname, String myDomain, String myServer)
{
    String url = "t3://" + host + ":" + port;

    //Get the server's MBeanHome interface.
     try {
          serverSpecificHome = (MBeanHome)Helper.getMBeanHome(                                 username, password, url, hostname);
     } catch (IllegalArgumentException iae) {
           System.out.println("Illegal Argument Exception: " + iae);
     } 

    //Use MBeanHome to get the server's MBeanServer interface.
    MBeanServer mServer = serverSpecificHome.getMBeanServer();

    //Use getMBeanByClass to retrieve the object name.
    LogBroadcasterRuntimeMBean logBCOname = (LogBroadcasterRuntimeMBean)
       home.getMBeanByClass(
       Class.forName ("weblogic.management.runtime.LogBroadcasterRuntimeMBean")
       );

    //Instantiate a listener object.
   MyRemoteNotificationListener myListener = new MyRemoteNotificationListener();

    //Register the listener.
    mServer.addNotificationListener( logBCOname,myListener,null,null );
}

Listing 4-5 assumes that you used weblogic.Admin GET to retrieve the LogBroadcasterRuntimeMBean object name. It also illustrates the format of object names that weblogic.Admin GET returns.

Listing 4-5 Using weblogic.Admin GET

MyRemoteNotificationListener myListener = new MyRemoteNotificationListener();
MBeanServer mServer = home.getMBeanServer();

ObjectName logBCOname = new ObjectName("mydomain:Location=myserver,Name=TheLogBroadcaster,Type=LogBroadcast
erRuntime");

mServer.addNotificationListener( logBCOname,myListener,null,null);

 

---

Step 3: Create and Register a Notification Filter

By default, the notification listener that you registered in the previous section listens for all notifications from LogBroadcasterRuntimeMBean and sends them to your application. You can configure the LogBroadcasterRuntimeMBean to send only the notifications that are pertinent to your application by creating and registering a filter. The filter determines whether a notification matches a set of criteria that you create, and the LogBroadcasterRuntimeMBean sends the notification only if the filter evaluates as true.

This section contains the following subsections:

• Creating and Registering a Filter
• WebLogicLogNotification Objects
• Example Notification Filter

Creating and Registering a Filter

To create and register a filter, do the following:

1. Import the following interfaces:

   import javax.management.Notification
   import javax.management.NotificationFilter

   Optionally import the following interface:
   import weblogic.management.logging.WebLogicLogNotification

   WebLogicLogNotification provides methods that you can use to get attributes of WebLogic log messages.

2. Create a serializable object that does the following:
   1. Implements javax.management.NotificationFilter.
   2. Searches a notification for a string.

   To search a notification that has been cast as a WebLogicLogNotification object, you can use WebLogicLogNotification getter methods. For example, you can use the getter methods to get the message timestamp, severity, user ID, the name of the subsystem that generated the message, the message text, and other data. For more information, refer to WebLogicLogNotification Objects.

   3. Uses a boolean to indicate whether the serializable object returns a true value.
   4. (Optional) Includes code that carries out an action depending on the value of the boolean. For example, your filter can use the JavaMail API to send e-mail to an administrator if a message is of severity WARNING or higher.
3. Use the addNotificationListener API to register the filter. For more information, refer to Using the addNotificationListener API.

Adding Filter Classes to the Server Classpath

If you create a filter for a listener that runs in a remote JVM, you must add the filter's classes to the classpath of the server instance from which you are listening for notifications. Although the listener runs in the remote JVM, to minimize the transportation of serialized data between the filter and the listener, the filter runs in the JVM of the server instance. (See Figure 4-4.)

Figure 4-4 Filters Run on WebLogic Server

WebLogicLogNotification Objects

All messages that a WebLogic Server generates are cast as weblogic.management.logging.WebLogicLogNotification objects. WebLogicLogNotification objects contain the following fields:

• Type—identifies the notification as required by the JMX specification. This field has the format:

weblogic.log.subSystem.messageID

where subSystem indicates the subsystem or application that issued the log message this notification contains, and messageID indicates the internal WebLogic Server message ID.

Note: For NonCatalogLogger messages, the message ID is always 000000. All log messages that WebLogic Server subsystems generate have a message ID that begins with the string BEA-.

• Time stamp—indicates the time at which the log message causing this notification was generated by the server.
• Sequence number.
• Message—contains the log message.
• User data—the user data field is not currently used.

A WebLogicLogNotification inherits getter methods from javax.management.Notification and it provides one getter method for each field within the log message. (See Figure 4-5.)

You can use these getter methods to search or print the information within the WebLogicLogNotification. For more information, refer to the weblogic.management.logging.WebLogicLogNotification Javadoc.

Figure 4-5 WebLogicLogNotification Getter Methods

Example Notification Filter

Listing 4-6 provides an example NotificationFilter that uses the WebLogicLogNotification.getType method.

Listing 4-6 Example Notification Filter

import javax.management.Notification;
import javax.management.NotificationFilter;
import weblogic.management.logging.WebLogicLogNotification;

....

public class MyLogNotificationFilter implements NotificationFilter,
    java.io.Serializable {

    public MyLogNotificationFilter() {
        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;
    }

}