Developing Custom Management Utilities with JMX
To integrate third-party management systems with the WebLogic Server management system, WebLogic Server provides standards-based interfaces that are fully compliant with the Java Management Extensions (JMX) specification. Software vendors can use these interfaces to monitor WebLogic Server MBeans, to change the configuration of a WebLogic Server domain, and to and monitor the distribution (activation) of those changes to all server instances in the domain. While JMX clients can perform all WebLogic Server management functions without using BEA's proprietary classes, BEA recommends that remote JMX clients use WebLogic Server protocols (such as T3) to connect to WebLogic Server instances.
This document is a resource for software vendors who develop JMX-compatible management systems. It also contains information that is useful for business analysts and system architects who are evaluating WebLogic Server® or considering the use of JMX for a particular application.
It is assumed that the reader is familiar with J2EE and general application management concepts. This document emphasizes a hands-on approach to developing a limited but useful set of JMX management services. For information on applying JMX to a broader set of management problems, refer to the JMX specification or other documents listed in Related Documentation.
The Sun Developer Network includes a Web site that provides links to books, white papers, and additional information on JMX: http://java.sun.com/products/JavaManagement/.
To view the JMX 1.2 specification, download it from http://jcp.org/aboutJava/communityprocess/final/jsr003/index3.html.
To view the JMX Remote API 1.0 specification, download it from http://jcp.org/aboutJava/communityprocess/final/jsr160/index.html.
You can view the API reference for the
javax.management* packages from: http://java.sun.com/j2se/1.5.0/docs/api/overview-summary.html.
WebLogic Server uses the Java Management Extensions (JMX) 1.2 implementation that is included in JDK 1.5. Prior to WebLogic Server 9.0, WebLogic Server used its own JMX implementation based on the JMX 1.0 specification.
Remote JMX clients can use the standard JMX remote API 1.0 (JSR-160) to connect to the JMX agents in WebLogic Server. (See http://jcp.org/en/jsr/detail?id=160.) Prior to 9.0, the JMX remote API had not been published and remote JMX clients had to use BEA's proprietary APIs to connect to WebLogic Server.
MBeanHome API also made it possible for BEA to provide a typed API layer over its JMX layer that you could use to interact with WebLogic Server MBeans. Your JMX application classes could import type-safe interfaces for WebLogic Server MBeans; retrieve a reference to the MBeans through the
weblogic.management.MBeanHome interface; and invoke the MBean methods directly.
The typed API layer is also deprecated. Instead of this API-like programming model, all JMX applications should use the standard JMX programming model, in which clients use the
javax.management.MBeanServerConnection interface to discover MBeans, attributes, and attribute types at runtime. In this JMX model, clients interact indirectly with MBeans through the
If any of your classes import the type-safe interfaces (which are under
weblogic.management), BEA recommends that you update to using the standard JMX programming model. See Accessing WebLogic Server MBeans with JMX in Developing Custom Management Utilities with JMX. If you do not update your JMX clients, they will use the domain's compatibility MBean server, which is enabled by default.
If you were using the
MBeanHome API to automate common configuration tasks, consider using the new WebLogic Scripting Tool (WLST) instead of JMX. WLST is a command-line scripting interface that manages and monitors active or inactive WebLogic Server domains. The WLST scripting environment is based on the Java scripting interpreter Jython. In addition to WebLogic scripting functions, you can use common features of interpreted languages, including local variables, conditional variables, and flow control statements. You can extend the WebLogic scripting language by following the Jython language syntax. See http://www.jython.org. For more information on WLST, see WebLogic Scripting Tool.
You can now collect modifications to a domain configuration and distribute them as a group throughout the domain. This release also contains APIs that you can use to monitor the distribution of changes.
The Administration Server hosts a set of pending MBeans, which are the in-memory representation of all pending changes to a domain's configuration (pending MBean data is backed up in a pending
config.xml file). Changes in pending MBeans do not take effect immediately. You must explicitly distribute them in a process that resembles a transaction. If any Managed Server is unable to consume a change, the entire set of changes in a distribution process is rolled back. This transactional process is the only way to change a domain's configuration through JMX. See Managing a Domain's Configuration with JMX in Developing Custom Management Utilities with JMX.
Prior to WebLogic Server 9.0, the Administration Server hosted a set of MBeans (administration MBeans) that represented the persisted configuration for all servers and server resources in a domain. To enhance performance, each server instance replicated these MBeans locally and used the replicas, called local configuration MBeans. When a JMX client changed an administration MBean, the Administration Server immediately updated the local configuration MBeans on all server instances in the domain even if the server itself could not integrate the change. In some cases, a local configuration MBean could not be updated unless you restarted a server instance, and the replica and its master administration MBean would contain different values. In addition, JMX clients could directly access local configuration MBeans and change their values, which also resulted in an inconsistent state between replica and master MBean.
TThe JMX specification does not impose a model for organizing MBeans. However, because the configuration of a WebLogic Server domain is specified in an XML document, WebLogic Server organizes its MBeans into a hierarchical model that reflects the XML document structure.
For example, the root of a domain's configuration document is
<domain> and below the root are child elements such as
<cluster>. Each domain maintains a single MBean of type
DomainMBean to represent the
<domain> root element. Within
DomainMBean, JMX attributes provide access to the MBeans that represent child elements such as
MBeanServer.createMBeanand passing a correctly constructed, hierarchical object name. However, if a JMX client incorrectly constructed the object name, the MBean would be created and registered but not recognized within the WebLogic Server data model.
Childis the short name of the MBean's type. (The short name is the MBean's unqualified type name without the
MBeansuffix. For example,
createServer). The parent also contains a
Childoperation and a
object-nameis the object name of the current node (MBean) in the MBean hierarchy.
attributeis the name of an attribute in the current MBean that refers to another MBean.
MBeanHomeinterface) will register new instances of WebLogic Server MBeans only if the JMX client has specified a correctly constructed, hierarchical object name for the instance.
To access the hierarchy, clients can use a set of new service MBeans which are registered in an MBean server under object names that are immutable and well defined. A JMX client supplies this object name to retrieve the service MBean. Then it uses the service MBean's attributes and operations to retrieve the root of a WebLogic Server MBean hierarchy.
An Administration Server maintains three MBean servers, each of which provides access to different MBean hierarchies. The Edit MBean Server provides access to the domain's editable configuration MBeans; the Domain Runtime MBean Server provides federated access to all runtime MBeans and read-only configuration MBeans in the domain; and the Runtime MBean Server provides access only to the runtime and read-only configuration MBeans on the Administration Server.
See MBean Servers in Developing Custom Management Utilities with JMX.
WebLogic Server now enables application developers to create and package descriptors for the application's services (such as JMS and JDBC services) in the application EAR file. When you deploy the application, WebLogic Server creates an instance of the service and configures it as defined in the descriptor. To support these application-scoped services, many subsystems have deprecated all or part of their old JMX interfaces and replaced them with new or updated MBeans.
See WebLogic Server MBean Reference, which lists all deprecated and new MBeans for WebLogic Server 9.0.
Prior to WebLogic Server 9.0, if you wanted to register custom MBeans in an MBean server on a WebLogic Server instance, you could either create your own MBean server or use
weblogic.management.RemoteMBeanServer to register in WebLogic Server's MBean server.
See Use the Runtime MBean Server in Developing Manageable Applications with JMX.
All public WebLogic Server MBeans are described in a new document, WebLogic Server MBean Reference. For each MBean, the document describes: