Developing Manageable Applications with JMX

Instrumenting and Registering Custom MBeans

This section describes BEA's recommendation for instrumenting and registering standard MBeans for application modules. Figure 4-1 illustrates the process. The steps in the process, and the results of each are described in Table 4-1. Subsequent sections detail each step in the process.

Figure 4-1 Standard MBean Development Overview

 

Table 4-1 Model MBean Development Tasks and Results

Step	Description	Result
1. Create and Implement a Management Interface on page 4-3	Create a standard Java interface that describes the properties (management attributes) and operations you want to expose to JMX clients. Create a Java class that implements the interface. Because management logic should be separate from business logic, the implementation should not be in the same class that contains your business methods.	Source files that describe and implement your management interface.
2. Modify Business Methods to Push Data on page 4-6	If your management attributes contain data about the number of times a business method has been invoked, or if you want management attributes to contain the same value as a business property, modify your business methods to push (update) data into the management implementation class. For example, if you want to keep track of how frequently your business class writes to the database, modify the business method that is responsible for writing to the database to also increment a counter property in your management implementation class. This design pattern enables you to insert a minimal amount of management code in your business code.	A clean separation between business logic and management logic.
3.Register the MBean on page 4-7	If you want to instantiate your MBeans as part of application deployment, create a WebLogic Server ApplicationLifecycleListener class to register your MBean.	A Java class and added entries in weblogic-application.xml.
4. Package Application and MBean Classes on page 4-9	Package your compiled classes into a single archive.	A JAR, WAR, EAR file or other deployable archive file.

 

---

Create and Implement a Management Interface

One of the main advantages to the standard MBeans design pattern is that you define and implement management properties (attributes) as you would any Java property (using getter/is and setter methods); similarly, you define and implement management methods (operations) as you would any Java method.

When you register the MBean, the MBean server examines the MBean interface and determines how to represent the data to JMX clients. Then, JMX clients use the MBeanServerConnection.getAttribute() and setAttribute() methods to get and set the values of attributes in your MBean and they use MBeanServerConnection.invoke() to invoke its operations. See MBeanServerConnection in the J2SE 5.0 API Specification.

To create an interface for your standard MBean:

Declare the interface as public.
BEA recommends that you name the interface as follows:
Business-objectMBean.java

where Business-object is the object that is being managed.

BEA's recommended design pattern for standard MBeans enables you to follow whatever naming convention you prefer. In other standard MBean design patterns (patterns in which the MBean's implementation file does not extend javax.management.StandardMBean), the file name must follow this pattern: Impl-fileMBean.java where Impl-file is the name of the MBean's implementation file.

For each read-write attribute that you want to make available in your MBean, define a getter and setter method that follows this naming pattern:

getAttribute-name
setAttribute-name

where Attribute-name is a case-sensitive name that you want to expose to JMX clients.

If your coding conventions prefer that you use an isAttribute-name as the getter method for attributes of type Boolean, you may do so. However, JMX clients use the MBeanServerConnection.getAttribute() method to retrieve an attribute's value regardless of the attribute's data type; there is no MBeanServerConnection.isAttribute() method.

For each read-only attribute that you want to make available, define only an is or a getter method.

For each write-only attribute, define only a setter method.

Define each management operation that you want to expose to JMX clients.

Listing 4-1 is an MBean interface that defines a read-only attribute of type int and an operation that JMX clients can use to set the value of the attribute to 0.

Listing 4-1 Management Interface

package com.bea.medrec.controller;

public interface RecordSessionEJBMBean {
   public int getTotalRx(); 
   public void resetTotalRx(); 
}

To implement the interface:

Create a public class.

BEA recommends the following pattern as a naming convention for implementation files: MBean-InterfaceImpl.java.

Extend javax.management.StandardMBean to enable this flexibility in the naming requirements.

See StandardMBean in the J2SE 5.0 API Specification.

Implement the StandardMBean(Object implementation, Class mbeanInterface) constructor.

With BEA's recommended design pattern in which you separate the management logic into a delegate class, you must provide a public constructor that implements the StandardMBean(Object implementation, Class mbeanInterface) constructor.

Implement the methods that you defined in the management interface.

Note the following guidelines:

• If you are using BEA's recommend design pattern in which business objects push management data into the management object, provide a method in this implementation class that the business methods use to set the value of the management attribute. In Listing 4-2, the incrementTotalRx() method is available to business methods but it is not part of the management interface.
• If multiple instances of an EJB, servlet, or other class can set the value of a management attribute, make sure to increment the property atomically and do not make its getter and setter (or increment method) synchronized. While synchronizing guarantees the accuracy of management data, it blocks business threads until the management operation has completed.

Listing 4-2 MBean Implementation

package com.bea.medrec.controller;

import javax.management.StandardMBean;
import com.bea.medrec.controller.RecordSessionEJBMBean;

public class RecordSessionEJBMBeanImpl extends StandardMBean 
   implements RecordSessionEJBMBean {

   public RecordSessionEJBMBeanImpl() throws
      javax.management.NotCompliantMBeanException {
         super(RecordSessionEJBMBean.class);
   }

   public int TotalRx = 0;
   public int getTotalRx() {
        return TotalRx;
   }
   public void incrementTotalRx() {
      TotalRx++;
   }
   public void resetTotalRx() {
       TotalRx = 0;
   }
}

 

---

Modify Business Methods to Push Data

If your management attributes contain data about the number of times a business method has been invoked, or if you want management attributes to contain the same value as a business property, modify your business methods to push (update) data into the management implementation class.

Listing 4-3 shows a method in an EJB that increments the integer in the TotalRx property each time the method is invoked.

Listing 4-3 EJB Method That Increments the Management Attribute

private Collection addRxs(Collection rXs, RecordLocal recordLocal)
   throws CreateException, Exception {
   ...
   com.bea.medrec.controller.RecordSessionEJBMBeanImpl.incrementTotalRx();
   ...
}

 

---

Register the MBean

If you want to instantiate your MBeans as part of application deployment, create an ApplicationLifecycleListener that registers your MBean when the application deploys (see Use ApplicationLifecycleListener to Register Application MBeans):

Create a class that extends weblogic.application.ApplicationLifecycleListener.
In this ApplicationLifecycleListener class, implement the ApplicationLifecycleListener.postStart(ApplicationLifecycleEvent evt) method.

In your implementation of this method:

Construct an object name for your MBean.

BEA recommends this naming convention:
your.company:Name=Parent-module,Type=MBean-interface-classname

To get the name of the parent module, use ApplicationLifecycleEvent to get an ApplicationContext object. Then use ApplicationContext to get the module's identification.

Access the WebLogic Server Runtime MBean Server through JNDI.

If the classes for the JMX client are part of a J2EE module, such as an EJB or Web application, then the JNDI name for the Runtime MBeanServer is:
java:comp/env/jmx/runtime

If the classes for the JMX client are not part of a J2EE module, then the JNDI name for the Runtime MBean Server is:
java:comp/jmx/runtime

For example:

InitialContext ctx = new InitialContext();
MBeanServer server = (MBeanServer)
     ctx.lookup("java:comp/env/jmx/runtime");

See Make Local Connections to the Runtime MBean Server in Developing Custom Management Utilities with JMX.

Register your MBean using MBeanServer.registerMBean(Object object, ObjectName name) where:

object is an instance of your MBean implementation class.

name is the JMX object name for your MBean.

When your application deploys, the WebLogic deployment service emits ApplicationLifecycleEvent notifications to all of its registered listeners. When the listener receives a postStart notification, it invokes its postStart method. See Programming Application Lifecycle Events in Developing Applications with WebLogic Server.

In the same class, implement the ApplicationLifecycleListener.preStop(ApplicationLifecycleEvent evt) method.

In your implementation of this method, invoke the
javax.management.MBeanServer.unregister(ObjectName MBean-name) method to unregister your MBean.

Register your class as an ApplicationLifecycleListener by adding the following element to your application's weblogic-application.xml file:

<listener>
   <listener-class>
      fully-qualified-class-name
   </listener-class>
</listener>

For an example of this technique, see the Medrec example server.

 

---

Package Application and MBean Classes

Package your MBean classes in the application's APP-INF directory or in a module's JAR, WAR or other type of archive file depending on the access that you want to enable for the MBean. See Additional Design Considerations.