This article is the last in a series on BEA WebLogic Server administration and management for developers.

The first installment focused on the WebLogic Server administration concepts and terminology, and the graphical tools for packaging an application and setting up and configuring a WebLogic Server domain. The second article looked at the available application deployment, run time management, and the monitoring facilities that did not require knowledge of JMX. The third article discussed the basic concepts and terminology of JMX and the WebLogic Server 8.1 JMX infrastructure, and showed you how to use JMX-specific tools that come with WebLogic Server 8.1. The fourth article focused on the basics of how to write custom Java applications that use JMX to configure, administer, and manage WebLogic Server 8.1-based applications. Last month, we continued our discussion of JMX programming by showing you how to use the notification facilities to create notification listeners, monitors, and timers (see WLDJ, Vol. 2, issues 10–12; Vol. 3, issues 2 and 4).

This month we'll describe how to expose your own management functionality through JMX and ultimately through the Weblogic Admin Console. We start off by discussing why you might choose to instrument your application with JMX. Then, we discuss the basics of instrumenting your application using standard, dynamic, and model MBeans. Finally, we show you how to expose your MBeans via the WebLogic Console.

Choosing to Instrument with JMX
Why would you want to consider instrumenting your application using JMX? If you read the previous articles in this series, you shouldalready know the answer to this question. If not, the answer is simple: application code that is instrumented using JMX allows the application's configuration and runtime information to be monitored and managed just like any other resource in WebLogic Server.

Last month, we showed you how JMX notification and monitors allow your application to dynamically monitor and track the values of any number of MBeans. Exposing the application information through an MBean makes it easy to correlate your application state with that of other MBeans, such as the WebLogic MBeans that surface statistics about the various servers and application components that make up your production environment.

Finally, instrumenting your code with JMX allows you to expose the monitoring and management functionality of your application through the WebLogic Admin Console.

What sort of functionality might you expose through JMX? The answer is any attribute or functionality of your application that you want to be able to manage. For example, an application might use a logging framework that allows logging levels to be changed dynamically at runtime. By instrumenting the logging framework to expose the logging level through JMX, it is now relatively easy to:

• Change the logging level dynamically through the normal JMX mechanisms.
• Use JMX notification and monitors to change the logging level whenever certain other conditions on other MBeans are observed.
• Expose the logging framework configuration and/or runtime information through the WebLogic Console.

• Standard MBeans
• Dynamic MBeans
• Model MBeans

JMX Instrumentation Using Standard MBeans
Implementing a standard MBean is about as simple as it gets. Before you start, the MBean interface class and MBean implementation class names must follow the specified pattern for all standard MBeans: the MBean interface class name must be the same as the MBean implementation class name with the suffix MBean appended. In our example, the MBean implementation class name is wldj.standard.Logger. Therefore, the MBean interface class name is wldj.standard.LoggerMBean. Now you're ready to create your standard MBean.

First, create an interface class that exposes the JMX attributes and operations through its method definitions. As we discussed in part 3, the attributes are exposed through getter and/or setter methods that conform to the standard JavaBean formats:

public Bar getFoo();
public void setFoo(Bar newValue);

All other methods exposed in the interface that do not follow these conventions are considered JMX operations. Our LoggerMBean interface exposes the following JMX attributes and operations:

Read-Write Attributes:
LoggingLevel

Read-Only Attributes:
DebugLogWrites
InfoLogWrites
WarningLogWrites
ErrorLogWrites
EmergencyLogWrites
TotalLogWrites

Operations:
void resetLogWriteStatistics()

Next, create your MBean implementation class to implement the MBean interface you defined. Remember, your interface only needs to expose the methods that you want JMX applications to be able to manage.

Finally, you need to include initialization code in your application to create and register your MBean with the MBeanServer. In our example, we used a WebLogic Startup class to create and register the MBean with the MBean server, as shown in the code snippet from the LoggerStartup class (see Listing 1).

The primary limitation of this approach is that it does not allow you to expose additional descriptive information about the attributes. JMX 1.2 addresses this limitation by providing a standardMBean base class, which you can extend and use to provide that additional information. You will, however, have to wait until the next release of BEA WebLogic Server to take advantage of this feature.

JMX Instrumentation Using Dynamic MBeans
Implementing a Dynamic MBean is a little more complex but gives you much more flexibility in that you can actually expose JMX attributes and operations that are defined at runtime rather than at compile time. To implement a Dynamic MBean, your MBean implementation class must implement the DynamicMBean interface, which includes:

• Providing an MBeanInfo object that details information about the JMX attributes, operations and notifications that are providde by the MBean
• Implementing the getAttribute() and setAttribute() methods that provide read and write capabilities for the MBean's JMX attributes
• Implementing the invoke() method that interprets the method and attribute types and performs the desired JMX operation
• Implementing the NotificationBroadcaster interface if the MBean emits JMX notifications
• Implementing the MBeanRegistration interface if the MBean needs lifecycle callbacks to create and/or cleanup MBean state.

Dynamic MBeans provide the greatest flexibility and allow the use of the entire JMX functionality. As the example demonstrates, it is also a great deal more effort than implementing a standard MBean. How do you retain the flexibility of dynamic MBeans while reducing the complexity? Model MBeans significantly reduce the level of effort needed to implement dynamic MBeans.

JMX Instrumentation Using Model MBeans
Model MBeans provide similar capabilities to dynamic MBeans but are significantly easier to implement. The majority of the effort in using model MBeans is in constructing the metadata to describe the attributes, constructors, operations, and notifications that the MBean will expose and how those relate to the application class being instrumented. Many of the benefits of model MBeans come from their ability to adapt preexisting implementation code without modification.

We chose to put the logic for creating the ModelMBeanInfo object that contains the metadata inside the Logger class itself. We could have just as easily put this in the LoggerStartup class so that the Logger class would have no JMX code whatsoever. In our example, we used the version of the ModelMBeanAttributeInfo class constructor that assumes the JMX attribute being exposed has the standard getter and setter method names on the instrumented class.

Model MBeans also support changing the names of the attributes and operations by using the Descriptor class to specify different method names on the instrumented class. The descriptor contains a list of name-value pairs. The JMX 1.0 specification defines a set of required and optional descriptor fields. For example, setting the currencyTimeLimit field in the descriptor causes the model MBean implementation class to cache the value of the attribute for the specified period of time. This flexibility is important when acquiring the value involves making a remote invocation or querying a back end system. Since our class was developed from a standard MBean, there was no need to use the descriptor functionality.

Once the ModelMBeanInfo object is populated, we simply need to create an instance of a ModelMBean using the RequiredModelMBean class, configure it to instrument our Logger class, and register it with the MbeanServer (see Listing 2).

While the code for creating and populating the ModelMBeanInfo object is more work than creating a standard MBean, it is equivalent to implementing the DynamicMBean.getMBeanInfo() method. For this effort, you get the flexibility of a dynamic MBean without the need to implement the other dispatch methods in the DymanicMBean interface.

Surfacing the MBean in the WebLogic Admin Console
The WebLogic Admin Console provides an extensibility mechanism that allows you to add pages to the Console to expose your application's MBeans. The basic steps are:

1. Implement a Java class that extends the weblogic.management.console.extensibility.Extension class and implements the weblogic.management.console.extensibility.NavTreeExtension interface.
2. Write a JSP that describes the nodes that you want to add to the Console's navigation tree.
3. Write a set of JSP pages that implement the pages that appear on the right hand side of the console whenever the user selects the nodes from the navigation tree.
4. Create a set of Web application deployment descriptors that tell the server that this web application is a console extension.
5. Package the Web application to the necessary files and deploy the Web application as you would any other Web application.

    public String getNavExtensionFor(Object key) 
    {
        if (key instanceof DomainMBean)
            return "logging_navlink.jsp";
        return null;
    }

To describe the nodes you want to add, you must write the JSP file whose name matches the value returned from the getNavExtensionFor() method. BEA WebLogic Server 8.1 provides a custom JSP tag library, console_extensions_taglib.tld, that contains the JSP custom tag wl:node that you will need to use to define your Console extension nodes. To create a nested set of nodes, you simply nest the wl:node tags in the JSP. The url parameter to the wl:node tags defines which JSPs are called when the user selects one of your custom nodes in the console. For example, selecting the standard MBean Loggers folder in our example causes the standard_summary.jsp to be invoked to fill in the right hand side of the Console window (see Listing 3).

When writing the set of Console pages for your application, use the wl:tag JSP custom tag to create a set of tabs similar to the tabbed pages in the other portions of the WebLogic Console. This tag allows you to create up to two levels of tabs. Look at our example to see how to use this functionality. For more information about the custom JSP tags provided to support extending the WebLogic Console, see the online documentation at http://edocs.bea.com/wls/docs81/console_ext/taglib.html.

Next, you need to write the Web application deployment descriptors. There are three things that you must do in addition to the normal information to describe the web application's contents. First, you need to tell the Console how to find your NavTreeExtension class by defining a context-param in the web.xml deployment descriptor:

    <context-param>
        <param-name>weblogic.console.extension.class</param-name>
        <param-value>wldj.LoggingConsoleExtension</param-value>
    </context-param>

Second, you need to add the taglib definition to the web.xml deployment descriptor:

    <taglib>
        <taglib-uri>console_extension_taglib.jar</taglib-uri> 
        <taglib-location>
            WEB-INF/console_extension_taglib.tld
        </taglib-location>
    </taglib>

Finally, you need to set the CookieName that your Web application uses to be the same as the one used by the WebLogic Admin Console so that your extension will be authenticated when the user logs into the Console. You do this by defining a session-param in the weblogic.xml deployment descriptor (see Listing 4). In the final step, you need to package the Web application and deploy it to your WebLogic Admin server. You will need to copy the console extensions tag library descriptor file $WL_HOME/server/lib/console_extensions_taglib.tld to the WEB-INF directory of your web application.

While the space available here prohibits us from going into more detail about all of the nuances of creating Console extensions, we hope that the downloadable example will provide a realistic enough example to get you started. For more information on creating console extensions, please refer to the BEA WebLogic Server 8.1 documentation at http://edocs.bea.com/wls/docs81/console_ext/.

Summary
We've reached the end of our series on application management with BEA WebLogic Server 8.1. We hope that we were able to show you the power and flexibility of the WebLogic Server 8.1 management tools and services. The JMX infrastructure built into WebLogic Server not only allows you to create custom management applications to manage WebLogic Server, but also allow you to instrument your applications with JMX and expose this instrumentation through extensions to the WebLogic Console.