An MBean is a managed Java object, similar to a JavaBeanTM, that follows the design patterns set forth in the instrumentation level of the JavaTM Management Extensions (JMXTM) 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 GlassFish Enterprise 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 19, Configuring Management Rules, in Sun GlassFish Enterprise Server v2.1.1 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/javase/6/docs/technotes/guides/jmx/overview/JMXoverviewTOC.html.
For a tutorial of JMX technology, see http://java.sun.com/javase/6/docs/technotes/guides/jmx/tutorial/tutorialTOC.html.
This chapter includes the following topics:
The MBean life cycle proceeds as follows:
The MBean's class files are installed in the Enterprise 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 Enterprise Server automatically appends server=target to the ObjectName when the MBean is registered, where the target is the name of the server instance or cluster to which the MBean is deployed.
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 Enterprise Server configuration. Changes to attributes after registration through a JMX connector such as JConsole do not affect the Enterprise Server configuration. To change an attribute value in the Enterprise 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 Enterprise Server runtime. See The MBeanServer in the Enterprise 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.
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 Enterprise Server. The classes are available to all other MBeans, applications, and modules deployed on servers that share the same configuration.
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 deployed on servers that share the same configuration, but not to 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 Enterprise Server class loaders, see Chapter 2, Class Loaders.
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.
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 Enterprise Server runtime environment. For more information about the MBeanServer, see The MBeanServer in the Enterprise Server.
Here is a simple example of an asadmin create-mbean command in which TextPatterns is the implementation class. The --attributes and --target options are not required.
asadmin create-mbean --user adminuser --target server1 --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 GlassFish Enterprise Server v2.1.1 Reference Manual.
For more information about MBean attributes, see Handling MBean Attributes.
To redeploy an MBean, simply install its new classes into the Enterprise Server as described in MBean Class Loading. Then either restart the server or use asadmin delete-mbean followed by asadmin create-mbean.
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. The --target option is not required.
asadmin delete-mbean --user adminuser --target server1 TextPatterns |
For full details on the asadmin delete-mbean command, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.
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. The --target option is not required.
asadmin list-mbeans --user adminuser --target server1 |
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 GlassFish Enterprise Server v2.1.1 Reference Manual.
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 Enterprise 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/javase/6/docs/technotes/guides/jmx/tutorial/tutorialTOC.html, and Using JConsole in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.
The connection to this MBeanServer is non-SSL by default for the developer profile and SSL by default for the cluster profile.
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 server1.admin-service.jmx-connector.system.port=8687 |
For details, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.
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 server1.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 GlassFish Enterprise Server v2.1.1 Reference Manual.
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 Enterprise 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 Enterprise Server configuration
In the Enterprise Server configuration, MBean attributes are stored as properties. Therefore, using the asadmin set command means editing properties. For example:
asadmin set --user adminuser server1.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.
For full details on the asadmin set command, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.