> Developing Manageable Applications with JMX > Instrumenting and Registering Custom MBeans

Developing Manageable Applications with JMX

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Instrumenting and Registering Custom MBeans

The following sections describe how to instrument and register standard MBeans for application modules:

 

Overview of the MBean Development Process

Figure 4-1 illustrates the MBean development 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

Standard MBean Development Overview

Table 4-1 Model MBean Development Tasks and Results
Step
Description
Result
1. Create and Implement a Management Interface
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
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
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
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 getxxx, setxxx, and isxxx 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:

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

    3. 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.

  3. 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:

    4. 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.

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

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

  5. 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:

  1. Create a public class.

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

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

    3. See StandardMBean in the J2SE 5.0 API Specification.

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

    4. 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.

  4. Implement the methods that you defined in the management interface.

    5. Follow these guidelines:

    • If you are using BEA's recommended 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):

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

    3. In your implementation of this method:

    1. Construct an object name for your MBean.

      2. 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.

    2. Access the WebLogic Server Runtime MBean Server through JNDI.

      3. 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.

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

      4. 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.

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

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

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

    5. <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.


  Back to Top       Previous  Next