Skip navigation.
Downloads | Product Documentation | Support

Developing Manageable Applications with JMX

# 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
- Create and Implement a Management Interface
- Modify Business Methods to Push Data
- Register the MBean
- Package Application and MBean Classes

# 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

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 `get` `xxx`, `set` `xxx`, and `is` `xxx` 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-object` `MBean.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-file` `MBean.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:

`get` `Attribute-name`
`set` `Attribute-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 `is` `Attribute-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.

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.

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

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

See `StandardMBean` in the J2SE 5.0 API Specification.

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

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

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.

In your implementation of this method:

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

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

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

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

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