Sun Java System Application Server Platform Edition 9 Developer's Guide

Chapter 14 Developing Custom MBeans

An MBean is a managed Java object, similar to a JavaBean^TM, that follows the design patterns set forth in the instrumentation level of the Java^TM Management Extensions (JMX^TM) specification. An MBean can represent a device, an application, or any resource that needs to be managed. MBeans expose a management interface: a set of readable and/or writable attributes and a set of invokable operations, along with a self-description. The actual runtime interface of an MBean depends on the type of that MBean. MBeans can also emit notifications when certain defined events occur. Unlike other components, MBeans have no annotations or deployment descriptors.

The Sun Java System Application Server supports the development of custom MBeans as part of the self-management infrastructure or as separate applications. All types of MBeans (standard, dynamic, open, and model) are supported. For more about self-management, see Chapter 20, Using the Application Server Management Extensions and Chapter 17, Configuring Management Rules, in Sun Java System Application Server Platform Edition 9 Administration Guide.

For general information about JMX technology, including how to download the JMX specification, see http://java.sun.com/products/JavaManagement/index.jsp.

For a useful overview of JMX technology, see http://java.sun.com/j2se/1.5.0/docs/guide/jmx/overview/JMXoverviewTOC.html.

For a tutorial of JMX technology, see http://java.sun.com/j2se/1.5.0/docs/guide/jmx/tutorial/tutorialTOC.html.

This chapter includes the following topics:

The MBean Life Cycle

The MBean life cycle proceeds as follows:

The MBean's class files are installed in the Application Server. See MBean Class Loading.
The MBean is deployed using the asadmin create-mbean command or the Admin Console. See Creating, Deleting, and Listing MBeans.
The MBean class is loaded. This also results in loading of other classes. The delegation model is used. See the class loader diagram in The Class Loader Hierarchy.
The MBean is instantiated. Its default constructor is invoked reflectively. This is why the MBean class must have a default constructor.
The MBean's ObjectName is determined according to the following algorithm.
- If you specify the ObjectName, it is used as is. The domain must be user:. The property name server is reserved and cannot be used.
  
  The Application Server automatically appends server=server to the ObjectName when the MBean is registered.
- If the MBean implements the MBeanRegistration interface, it must provide an ObjectName in its preregister() method that follows the same rules.
- If the ObjectName is not specified directly or through the MBeanRegistration interface, the default is user:type=impl-class-name.
All attributes are set using setAttribute calls in the order in which the attributes are specified. Attempting to specify a read-only attribute results in an error.

If attribute values are set during MBean deployment, these values are passed in as String objects. Therefore, attribute types must be Java classes having constructors that accept String objects. If you specify an attribute that does not have such a constructor, an error is reported.

Attribute values specified during MBean deployment are persisted to the Application Server configuration. Changes to attributes after registration through a JMX connector such as JConsole do not affect the Application Server configuration. To change an attribute value in the Application Server configuration, use the asadmin set command. See Handling MBean Attributes.
If the MBean is enabled, the MBeanServer.registerMBean(Object, ObjectName) method is used to register the MBean in the MBeanServer. This is the only method called by the Application Server runtime. See The MBeanServer in the Application Server.

MBeans are enabled by default. Disabling an MBean deregisters it. See Enabling and Disabling MBeans.
The MBean is automatically loaded, instantiated, and registered upon each server restart.
When the MBean is deleted using the asadmin delete-mbean command or the Admin Console, the MBean is first deregistered if it is enabled, then the MBean definition is deleted from the configuration. The class files are not deleted, however.

MBean Class Loading

After you develop a custom MBean, copy its class files (or JAR file) into the MBean class loader directory, domain-dir/applications/mbeans. You have two choices of where to place any dependent classes:

Common class loader – Copy the classes as JAR files into the domain-dir/lib directory, or copy the classes as .class files into the domain-dir/lib/classes directory. The classes are loaded when you restart the Application Server. The classes are available to all other MBeans and all deployed applications and modules.
MBean class loader – Copy the classes into the domain-dir/applications/mbeans directory. No restart is required. The classes are available to all other MBeans, but not to all deployed applications and modules.

After copying the classes, register the MBean using the asadmin create-mbean command. See The asadmin create-mbean Command.

For general information about Application Server class loaders, see Chapter 2, Class Loaders.

Creating, Deleting, and Listing MBeans

This section describes the following commands:

Use the asadmin create-mbean command to deploy, or register, an MBean.
Use the asadmin delete-mbean command to undeploy an MBean.
Use the asadmin list-mbeans command to list deployed MBeans.

To perform these tasks using the Admin Console, open the Custom MBeans component. For details, click the Help button in the Admin Console.

The `asadmin create-mbean` Command

After installing the MBean classes as explained in MBean Class Loading, use the asadmin create-mbean command to deploy the MBean. This registers the MBean in the MBeanServer that is part of the Application Server runtime environment. For more information about the MBeanServer, see The MBeanServer in the Application Server.

Here is a simple example of an asadmin create-mbean command in which TextPatterns is the implementation class. The --attributes option is not required.

asadmin create-mbean --user adminuser --attributes color=red:font=Times TextPatterns

Other options not included in the example are as follows:

--name defaults to the implementation class name
--objectname is explained in The MBean Life Cycle
--enabled defaults to true and is explained in Enabling and Disabling MBeans

All options must precede the implementation class.

For full details on the asadmin create-mbean command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

For more information about MBean attributes, see Handling MBean Attributes.

Note –

To redeploy an MBean, simply install its new classes into the Application Server as described in MBean Class Loading. Then either restart the server or use asadmin delete-mbean followed by asadmin create-mbean.

The `asadmin delete-mbean` Command

To undeploy an MBean, use the asadmin delete-mbean command. This removes its registration from the MBeanServer, but does not delete its code. Here is an example asadmin delete-mbean command in which TextPatterns is the implementation class.

asadmin delete-mbean --user adminuser  TextPatterns

For full details on the asadmin delete-mbean command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

The `asadmin list-mbeans` Command

To list MBeans that have been deployed, use the asadmin list-mbeans command. Note that this command only lists the MBean definitions and not the MBeans registered in the MBeanServer. Here is an example asadmin list-mbeans command.

asadmin list-mbeans --user adminuser

The output of the asadmin list-mbeans command lists the following information:

Implementation class – The name of the implementation class without the extension.
Name – The name of the registered MBean, which defaults to but may be different from the implementation class name.
Object name – The ObjectName of the MBean, which is explained in The MBean Life Cycle.
Object type – For custom MBeans, the object type is always user. System MBeans have other object types.
Enabled – Whether the MBean is enabled. MBeans are enabled by default. See Enabling and Disabling MBeans.

For full details on the asadmin list-mbeans command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

The `MBeanServer` in the Application Server

Custom MBeans are registered in the PlatformMBeanServer returned by the java.lang.management.ManagementFactory.getPlatformMBeanServer() method. This MBeanServer is associated with a standard JMX connector server.

You can use any JMX connector to look up MBeans in this MBeanServer just as you would any other MBeanServer. If your JMX connector is remote, you can connect to this MBeanServer using the following information:

Host name of the Application Server machine
MBeanServer port, which is 8686 by default
Administrator username
Administrator password

For example, if you use JConsole, you can enter this information under the Remote tab. JConsole is a generic JMX connector you can use to look up and manage MBeans. For more information about JConsole, see http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html, the JMX tutorial at http://java.sun.com/j2se/1.5.0/docs/guide/jmx/tutorial/tutorialTOC.html, and Using JConsole in Sun Java System Application Server Platform Edition 9 Administration Guide.

The connection to this MBeanServer is non-SSL by default.

If SSL is enabled, you must provide the location of the truststore that contains the server certificate that the JMX connector should trust. For example, if you are using JConsole, you supply this location at the command line as follows:

jconsole -J-Djavax.net.ssl.trustStore=home-directory/.asadmintruststore

Look up the MBean by its name. By default, the name is the same as the implementation class.

You can reconfigure the JMX connector server's naming service port in one of the following ways:

In the Admin Console, open the Admin Service component under the relevant configuration, select the system subcomponent, edit the Port field, and select Save. For details, click the Help button in the Admin Console.
Use the asadmin set command as in the following example:
asadmin set --user adminuser server.admin-service.jmx-connector.system.port=8687
For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Enabling and Disabling MBeans

A custom MBean is enabled by default. You can disable an MBean during deployment by using the asadmin create-mbean command's optional --enabled=false option. See The asadmin create-mbean Command.

After deployment, you can disable an MBean using the asadmin set command. For example:

asadmin set --user adminuser server.applications.mbean.TextPatterns.enabled=false

If the MBean name is different from the implementation class, you must use the name in the asadmin set command. In this example, the name is TextPatterns.

For full details on the asadmin set command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Handling MBean Attributes

You can set MBean attribute values that are not read-only in the following ways:

In the MBean code itself, which does not affect the Application Server configuration
During deployment using the asadmin create-mbean command
During deployment using the Custom MBeans component in the Admin Console
Using the asadmin set command
Using a JMX connector such as JConsole, which does not affect the Application Server configuration

In the Application Server configuration, MBean attributes are stored as properties. Therefore, using the asadmin set command means editing properties. For example:

asadmin set --user adminuser server.applications.mbean.TextPatterns.property.color=blue

If the MBean name is different from the implementation class, you must use the MBean name in the asadmin set command. In this example, the name is TextPatterns.