Developing Manageable Applications with JMX

Introduction and Roadmap

As an application developer, you can greatly reduce the cost of operating and maintaining your applications by building in management facilities. The simplest facility is message logging, which reports events within your applications as they occur and writes messages to a file or other repository. Depending on the criticality of your application, the complexity of the production environment, and the types of monitoring systems your organization uses in its operations center, your needs might be better served by building richer management facilities based on Java Management Extensions (JMX). JMX enables a generic management system to monitor your application, raise notifications when the application needs attention, and change the configuration or runtime state of your application to remedy problems.

This document describes using JMX to make your applications manageable.

The following sections describe the contents and organization of this guide—Developing Manageable Applications with JMX.

Document Scope and Audience

This document is a resource for software developers who develop management services for J2EE applications. 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.

The topics in this document are relevant during the design and development phases of a software project. This document does not address production phase administration, monitoring, or performance tuning topics. For links to WebLogic Server documentation and resources for these topics, see Related Documentation.

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.

Guide to this Document

This chapter, Introduction and Roadmap, introduces the organization of this guide.
Understanding JMX, gives an overview of JMX and describes how J2EE applications can use JMX.
Designing Manageable Applications, recommends design patterns for making J2EE applications manageable through JMX.
Instrumenting and Registering Custom MBeans, describes how to create your own MBeans (custom MBeans), which enable you to promote your application to the status of a managed object within a larger management system.
Using the WebLogic Server JMX Timer Service, describes how to configure your JMX client to carry out a task at a specified time or a regular time interval by using WebLogic Server's implementation of the JMX timer service.
Accessing Custom MBeans, describes options for accessing your MBeans (other than through JMX).

Samples for the JMX Developer

In addition to this document, BEA Systems provides code samples for JMX developers. The examples illustrate management applications in action and provide practical instructions on how to perform key JMX development tasks.

BEA recommends that you run some or all of the JMX examples before developing your own management applications.

Avitek Medical Records Application (MedRec) and Tutorials

MedRec is an end-to-end sample J2EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application provides a framework for patients, doctors, and administrators to manage patient data using a variety of different clients.

MedRec demonstrates WebLogic Server and J2EE features, and highlights BEA-recommended best practices. MedRec is included in the WebLogic Server distribution, and can be accessed from the Start menu on Windows machines. For Linux and other platforms, you can start MedRec from the WL_HOME/samples/domains/medrec directory, where WL_HOME is the top-level installation directory for WebLogic Platform.

MedRec has instrumented one of its session EJBs for management through JMX. The EJB keeps track of how many times it writes to the database, and exposes this counter as an MBean attribute.

New and Changed JMX Features in This Release

Release 9.0 introduces several important changes to the WebLogic Server JMX implementation:

JMX 1.2 and JMX Remote API 1.0 (JSR-160)

In 9.0, WebLogic Server uses the Java Management Extensions (JMX) 1.2 implementation that is included in JDK 1.5. Prior to this release, WebLogic Server used its own JMX implementation based on the JMX 1.0 specification.

Also in 9.0, 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.

Deprecated MBeanHome and Type-Safe Interfaces

Now that the JMX remote APIs (JSR-160) are published, BEA's proprietary API for remote JMX access, weblogic.management.MBeanHome, is no longer needed and is therefore deprecated.

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

As of 9.0, the typed API layer is also deprecated. Instead of using 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 MBeanServerConnection interface.

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.

Changes to the Model for Distributing Configuration Data in a Domain

WebLogic Server 9.0 enables you to collect modifications to a domain's configuration and distribute them as a group throughout the domain. The 9.0 release also contains APIs that you can use to monitor the distribution of changes.

In 9.0, 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 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 without restarting 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.

Changes to the MBean Data Model

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 <server> and <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 <server> and <cluster>.

Prior to 9.0:

There were inconsistencies in the data model across WebLogic Server subsystems.
JMX clients could create and access WebLogic Server MBeans by invoking MBeanServer.createMBean and 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.

As of 9.0:

The data model is consistent across WebLogic Server subsystems.
To enable JMX clients to control MBean life cycles, WebLogic Server MBeans contain operations that follow the design pattern for Java bean factory methods: for each child, a parent MBean contains a createChild and destroyChild operation, where Child is the short name of the MBean's type. (The short name is the MBean's unqualified type name without the MBean suffix. For example, createServer). The parent also contains a lookupChild operation and a Children attribute.

For example, DomainMBean contains the createServer, destroyServer, and lookupServer operations and it contains a Servers attribute.
There is no other option for creating child MBeans.

JMX clients no longer need to construct JMX object names when they want to retrieve a WebLogic Server MBean. Instead, they navigate the MBean hierarchy by successively invoking code similar to the following:

ObjectName on = javax.management.MBeanServerConnection.getAttribute (object-name, attribute);
where:

object-name is the object name of the current node (MBean) in the MBean hierarchy.
attribute is the name of an attribute in the current MBean that refers to another MBean.

The compatibility MBean server (which you must enable if your JMX clients still use the deprecated MBeanHome interface) 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.

New Functionally Aligned MBean Servers

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.

Each Managed Server maintains a Runtime MBean Server, which provides access only to its runtime and read-only configuration MBeans.

JMX clients use the standard javax.remote.access (JSR-160) APIs to access and interact with MBeans registered in the MBean servers.

See MBean Servers in Developing Custom Management Utilities with JMX.

Facilities for Registering Custom MBeans

Prior to 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.

As of 9.0 and JDK 1.5, you can do any of the following from a JMX client that is running in a WebLogic Server JVM:

(Recommended) Access the Runtime MBean Server through JNDI and register custom MBeans in the Runtime MBean Server.
Register custom MBeans in the JVM's platform MBean server.
Create your own MBean server.

See Use the Runtime MBean Server in Developing Manageable Applications with JMX.

New Reference Document for WebLogic Server MBeans

All public WebLogic Server MBeans are described in a new document, WebLogic Server MBean Reference. For each MBean, the document describes:

The MBean's factory methods and other points of access within WebLogic Server MBean trees
The data type, read-write privileges, and other information for each attribute
The parameters, signature, and other information for each operation