Programming WebLogic Management Services with JMX

Overview of WebLogic JMX Services

WebLogic Server implements the Sun Microsystems, Inc. Java Management Extensions (JMX) 1.0 specification to provide open and extensible management services. WebLogic Server adds its own set of convenience methods and other extensions to facilitate working in the WebLogic Server distributed environment.

All WebLogic Server resources are managed through these JMX-based services, and third-party services and applications that run within WebLogic Server can be managed through them as well. You can build your own management utilities that use these JMX services to manage WebLogic Server resources and applications.

The following sections provide an overview of the WebLogic Server JMX services:

To view the JMX 1.0 specification, download it from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The API documentation is included in the archive that you download.

WebLogic Server Managed Resources and MBeans

Subsystems within WebLogic Server (such as JMS Provider and JDBC Container) and the items that they control (such as JMS servers and JDBC connection pools) are called WebLogic Server managed resources. Each managed resource includes a set of attributes that can be configured and monitored for management purposes. For example, each JDBC connection pool includes attributes that define its name, the name of its driver, its initial capacity, and its cache size. Some managed resources provide additional methods (operations) that can be used for management purposes. The WebLogic JMX services expose these management attributes and operations through one or more managed beans (MBeans). An MBean is a concrete Java class that is developed per JMX specifications. It can provide getter and setter operations for each management attribute within a managed resource along with additional management operations that the resource makes available. (See Figure 1-1.)

Figure 1-1 Managed Resources and Managed Beans

Managed Resources and Managed Beans

WebLogic Server MBeans that expose attributes and operations for configuring a managed resource are called Configuration MBeans while MBeans that provide information about the runtime state of a managed resource are called Runtime MBeans. The functions of configuring resources and viewing data about the runtime state of resources in a WebLogic Server domain are different enough that Configuration MBeans and Runtime MBeans are distributed and maintained differently.

The following sections describe how WebLogic Server distributes and maintains MBeans:

Basic Organization of a WebLogic Server Domain

A WebLogic Server administration domain is a logically related group of WebLogic Server resources. Domains include a special WebLogic Server instance called the Administration Server, which is the central point from which you configure and manage all resources in the domain. Usually, you configure a domain to include additional WebLogic Server instances called Managed Servers. You deploy applications, EJBs, and other resources developed onto the Managed Servers and use the Administration Server for configuration and management purposes only.

Note: WebLogic Server does not support multi-domain interaction using either the Administration Console, the weblogic.Admin utility, or WebLogic Ant tasks. This restriction does not, however, explicitly preclude a user written Java application from accessing multiple domains simultaneously.

Using multiple Managed Servers enables you to balance loads and provide failover protection for critical applications, while using single Administration Server simplifies the management of the Managed Server instances. For more information about domains, refer to "Overview of WebLogic Server Domains" in Configuring and Managing WebLogic Server.

MBeans for Configuring Managed Resources

To support the WebLogic Server model of centralizing management responsibilities on the Administration Server, the Administration Server hosts Configuration MBeans for all managed resources on all server instances in the domain. In addition, the Administration Server saves changes to configuration data so that it is available when you shut down and restart a server instance.

To change the configuration of a WebLogic Server resource, you modify the values in the Configuration MBeans on the Administration Server.

Local Replicas of Configuration MBeans

To enhance performance, each Managed Server creates local replicas of all Configuration MBeans in a domain. WebLogic Server subsystems and applications that interact with MBeans use the replicas on the local server instead of initiating remote calls to the Administration Server. (See Figure 1-2.)

Figure 1-2 MBean Replication

MBean Replication

The Configuration MBeans on the Administration Server are called Administration MBeans, and the replicas on the Managed Servers are called Local Configuration MBeans.

Note: In addition to hosting Administration MBeans, the Administration Server hosts the Local Configuration MBeans that are used by its own subsystems and by any applications that are deployed on the Administration Server.

The Life Cycle of Configuration MBeans

This section describes how Administration MBeans and Local Configuration MBeans are initialized, how changes to configuration data are propagated throughout the WebLogic Server system, and how attribute values can be changed so that they are available when you restart server instances:

The life cycle of a Configuration MBean begins when you start the Administration Server. During its startup cycle, the Administration Server initializes all the Administration MBeans for the domain with data from the domain's config.xml file. (See Figure 1-3.)

Figure 1-3 Initializing Configuration MBeans

Initializing Configuration MBeans

The Administration Server reads data from the config.xml file only during its startup cycle.

When a Managed Server starts, it contacts the Administration Server for its configuration data. By default, it creates replicas of the Administration MBeans that configure resources in the domain. However, you can use arguments in the server's startup command to override values of the Administration MBeans.

For example, for Managed Server A, the config.xml file states that its listen port is 8000. When you use the weblogic.Server command to start Managed Server A, you include the -Dweblogic.ListenPort=7501 startup option to change the listen port for the current server session. The Managed Server creates a replica of the Administration MBeans, but substitutes 7501 as the value of its listen port. When you restart Managed Server A, it will revert to using the value from the config.xml file, 8000. (See Figure 1-4.) Figure 1-4 Overriding Administration MBean Values
When you start an Administration Server, any startup command arguments that you use to override the values in config.xml affect only the values of the Local Configuration MBeans on the Administration Server. The command arguments do not affect the values of the Administration MBeans and therefore do not affect subsequent server sessions. (See Figure 1-5.) Figure 1-5 Overriding Values on the Administration Server

If you change a value in an Administration MBean, and if the corresponding Managed Server is running, the Administration Server propagates the change to the Local Configuration MBean. Depending on the attribute, the underlying resource might not be able to accept the new value until it restarts. The WebLogic Server Javadoc indicates whether a managed resource can accept new values for an attribute during the current session. Even if a managed resource can accept new values, depending on the frequency with which the resource checks for configuration changes, the resource might not use the updated value immediately.

Note: BEA recommends that you change only the values of Administration MBean attributes. Do not change attribute values in Local Configuration MBeans. When the Managed Server replicates the data of other Managed Servers, it uses the values that are stored in Administration MBeans. Communication problems can occur if the values in Administration MBeans and Local Configuration MBeans differ.

Periodically, the Administration Server determines whether Administration MBeans have been changed and writes any changes back to config.xml. Changes also are written to config.xml when the Administration Server shuts down or when MBean attributes are modified by a WebLogic Server utility such as the Administration Console or weblogic.Admin.

Local Configuration MBeans are destroyed when you shut down Managed Servers. Administration MBeans are destroyed when you shut down the Administration Server.

Replication of MBeans for Managed Server Independence

Managed Server Independence (MSI) is a feature that enables a Managed Server to start if the Administration Server is unavailable. If a Managed Server is configured for MSI, in addition to its Local Configuration MBeans, it also contains a copy of all Administration MBeans for the domain.

Do not interact with these Administration MBeans on a Managed Server. They reflect the last known configuration for the domain and are used only for starting the Managed Server in MSI mode. Modifying an Administration MBean on a Managed Server can cause the Managed Server's configuration to be inconsistent with the Administration Server, which will lead to unpredictable results. In addition, Managed Servers are not aware of the Administration MBeans on other Managed Servers.

For more information on MSI, refer to "Starting a Managed Server When the Administration Server Is Not Accessible" in Configuring and Managing WebLogic Server.

Documentation for Configuration MBean APIs

To view the documentation for Configuration MBeans:

Open the WebLogic Server Javadoc.

In the top left pane of the Web browser, click weblogic.management.configuration.

The lower left pane displays links for the package.

In the lower left pane, click weblogic.management.configuration again.

The right pane displays the package summary. (See Figure 1-6.) Figure 1-6 Javadoc for the configuration Package

Click on an interface name to view its API documentation.

MBeans for Viewing the Runtime State of Managed Resources

WebLogic Server managed resources provide performance metrics and other information about their runtime state through one or more Runtime MBeans. Runtime MBeans are not replicated like Configuration MBeans, and they exist only on the same server instance as their underlying managed resources.

Because Runtime MBeans contain only transient data, they do not save their data in the config.xml file. When you shut down a server instance, all runtime statistics and metrics from the Runtime MBeans are destroyed.

The following figure (Figure 1-7) illustrates how Runtime MBeans, Administration MBeans, and Local Configuration MBeans are distributed throughout a domain.

Figure 1-7 Distribution of MBeans

Distribution of MBeans

You can use the Administration Console, the weblogic.Admin utility, or MBean APIs to view the values. (See Figure 1-8.)

Figure 1-8 Viewing Runtime Metrics from the Administration Console

Viewing Runtime Metrics from the Administration Console

You can also use these interfaces to change some runtime values. For example, the weblogic.management.runtime.DeployerRuntimeMBean activates and deactivates a deployed module by changing its runtime state.

Documentation for Runtime MBean APIs

To view the documentation for Runtime MBeans:

Open the WebLogic Server Javadoc.

In the top left pane of the Web browser, click weblogic.management.runtime.

The lower left pane displays links for the package.

In the lower left pane, click weblogic.management.runtime again.

The right pane displays the package summary. (See Figure 1-9.) Figure 1-9 Javadoc for the runtime Package

Click on an interface name to view its API documentation.

Security MBeans

The WebLogic Security Service provides MBeans and tools for generating additional MBeans that manage security on a WebLogic Server. These MBeans are called Security MBeans and their usage model is different from the one described in this document. For information on Security MBeans, refer to Developing Security Providers for WebLogic Server.

Non-WebLogic Server MBeans

WebLogic Server provides hundreds of MBeans, many of which are used to configure and monitor EJBs, Web applications, and other deployable J2EE modules. If you want to use additional MBeans to configure your applications or services, you can create your own MBeans.

Any MBeans that you create can take advantage of the full set of JMX 1.0 features, as defined by the JMX specification (which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html).

However, only MBeans that are provided by WebLogic Server can use the WebLogic Server extensions to JMX. For example, any MBeans that you create for your applications cannot save data in the config.xml file and they cannot use the type-safe interface as described in the next section, MBean Servers and the MBeanHome Interface.

MBean Servers and the MBeanHome Interface

Within a WebLogic Server instance, the actual work of registering and providing access to MBeans is delegated to an MBean Server subsystem. The MBean Server on a Managed Server registers and provides access only to the Local Configuration MBeans and Runtime MBeans on the current Managed Server. The MBean Server on an Administration Server registers and provides access to the domain's Administration MBeans as well as the Local Configuration MBeans and Runtime MBeans on the Administration Server.

Note: On a Managed Server that is configured for Managed Server Independence (MSI), the MBean Server also registers the Administration MBean replicas that the server uses to start if the Administration Server is not available. Do not interact with these Administration MBean replicas. For more information, refer to Replication of MBeans for Managed Server Independence.

To access the MBean Server subsystem, you use the weblogic.management.MBeanHome interface. From MBeanHome, you can use any of the following interfaces to interact with the MBean Server and its MBeans (see Figure 1-10):

javax.management.MBeanServer, which is the standard JMX interface for interacting with MBeans. You can use this interface to look up MBeans that are registered in an MBean Server, determine the set of operations available for an MBean, and determine the type of data that each operation returns. If you invoke MBean operations through the MBeanServer interface, you must use standard JMX methods. For example:

MBeanHome.getMBeanServer().getAttribute(MBeanObjectName, attributeName)
MBeanHome.getMBeanServer().setAttribute(MBeanObjectName, attributeName)
MBeanHome.getMBeanServer().invoke(MBeanObjectName, operationName, params, signature)

For a complete list of MBeanServer APIs, refer to view the JMX 1.0 API documentation, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The archive that you download includes the API documentation.
The MBeanServer interface is your only option for interacting with MBeans that you have created and registered (non-WebLogic MBeans).

weblogic.management.RemoteMBeanServer, which extends the javax.management.MBeanServer and java.rmi.Remote interfaces.Use the RemoteMBeanServer interface if you want to use standard JMX techniques to access WebLogic Server MBeans from remote JVMs or if you want to interact with non-WebLogic MBeans from a remote JVM.
A WebLogic Server type-safe interface that makes it appear as though you can invoke an MBean's methods directly. You can use this interface to look up MBeans that are registered in an MBean Server and invoke get, set, and other operations on the MBean. For example:

wlMBean = MBeanHome.getMBean(WebLogicObjectName) wlMBean.getAttributewlMBean.setAttributewlMBean.operationName
The type-safe interface extends the java.rmi.Remote interface, so you can use it to access WebLogic Server MBeans from remote JVMs. Figure 1-10 MBeans Servers and Their Interfaces

Local MBeanHome and the Administration MBeanHome

All instances of WebLogic Server provide a local MBeanHome interface through which you can access the MBeans that are hosted in the server instance's MBean Server.

For Managed Servers and Administration Servers, the local MBeanHome interface provides access to the Runtime MBeans for the current server only and to all Local Configuration MBeans in the domain.

The Administration Server provides an additional instance of the MBeanHome interface. This Administration MBeanHome provides access to Administration MBeans along with all other MBeans on all server instances in the domain. The Administration MBeanHome uses RMI to contact MBeans on Managed Servers, which uses more network resources and might take longer than using a local MBeanServer or MBeanHome interface. (See Figure 1-11.)

Figure 1-11 Local and Administration MBeanHome Interfaces

Local and Administration MBeanHome Interfaces

The local MBeanHome and the Administration MBeanHome are two instances of the same interface class, so the APIs for the two types of MBeanHome differ only in the name of the MBeanHome instance and in the set of MBeans that you can access.

Notifications and Monitoring

Depending on your management needs, you can use MBean APIs to view MBean attributes only upon request, or you can use the WebLogic Server notification and monitoring facilities, which automatically broadcast reports (JMX notifications) when MBean attributes change.

To use these facilities:

Create a JMX listener, which listens for and reports all attribute changes within an MBean that you specify. For example, you could use a listener with some additional logic to send an email to a System Administrator any time a user changes the configuration of a deployed component. For information about using listeners, refer to Using WebLogic Server MBean Notifications and Monitors.
Create a JMX monitor, which listens for and reports only the changes to specific MBean attributes that fall outside a set of parameters that you set. For example, you could use a monitor with some additional logic to send an email to a System Administrator when the number of open thread pools exceeds a specified limit. For more information, refer to Using WebLogic Server MBean Notifications and Monitors.

The Administration Console and the weblogic.Admin Utility

The WebLogic Server Administration Console and the weblogic.Admin utility are examples of management utilities that use the WebLogic Server JMX services. You can use these interfaces to familiarize yourself with WebLogic Server management services before developing your JMX applications.

The Administration Console

The Administration Console is a Web application with servlets that invoke the WebLogic Server JMX APIs. Almost all of the values that the Administration Console presents are attributes of Administration MBeans and Runtime MBeans. Because the Administration Console does not read or write Local Configuration MBeans, it is possible that it reports a value that a server instance is not currently using. For example, if you use a weblogic.Server startup option to override the configured listen port, the Administration Console reports the value that is in the config.xml file, not the overriding value.

To determine which MBean attribute the Administration Console is presenting, click the question mark icon in the top banner. In the help window, click the Attributes link to see the MBean class and attribute that is associated with field on the Administration Console.

The caution icon (yellow triangle with an exclamation point) next to a field in the Administration Console indicates that an attribute is not dynamic. If you modify such an attribute, the underlying managed resource cannot use the new value until you restart the server.

If you modify a dynamic value from the Administration Console, the console updates the corresponding Administration MBean. For information on how this change is propagated to the Local Configuration MBean, refer to The Life Cycle of Configuration MBeans.

The weblogic.Admin Utility

The weblogic.Admin utility provides several commands that create, get and set values for, invoke operations on, and delete instances of Administration and Configuration MBeans. It also provides commands to get values and invoke operations on Runtime MBeans. You could create shell scripts that use this utility instead of creating JMX applications to programmatically interact with the WebLogic Server management services, however, the performance of a JMX application is superior to a shell script that invokes command-line utilities.

You can also use the weblogic.Admin utility to verify object names of MBeans and to get and set attributes from a command line before committing to writing JMX code. Subsequent sections in this document provide examples of using the weblogic.Admin utility as part of your JMX development.

For more information, refer to "Commands for Managing WebLogic Server MBeans" in the WebLogic Server Command Line Reference.