Overview of WebLogic JMX Services

To provide open and extensible management services, WebLogic Server implements the Sun Microsystems, Inc. Java Management Extensions (JMX) 1.0 specification. 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.

The WebLogic Server Administration Console and the weblogic.Admin utility use WebLogic JMX APIs to implement their management services. You can also use these APIs to build your own, specialized management utilities. For example, you can build a management utility that uses JMX APIs to monitor your application's use of JDBC connection pools. If usage falls outside a set of allowable parameters, your utility can use the APIs to adjust the size or configuration of the connection pools. Your utility could also include code that sends an email to alert a system administrator of the configuration change.

WebLogic Server implements the JMX 1.0 specification and adds its own set of convenience methods and other extensions to take advantage of the WebLogic Server distributed environment. This topic provides an overview of the WebLogic Server JMX services:

• WebLogic Server Managed Resources and MBeans
• MBean Servers and the MBeanHome Interface
• Notifications and Monitoring
• The Administration Console and the weblogic.Admin Utility

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

 

WebLogic Server MBeans that expose attributes and operations for configuration 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 are sufficiently different in a WebLogic Server domain that Configuration MBeans and Runtime MBeans are distributed and maintained differently.

This section contains the following subsections:

• Basic Organization of a WebLogic Server Domain
• MBeans for Configuring Managed Resources" on page 4
• MBeans for Viewing the Runtime State of Managed Resources
• Security MBeans
• Non-WebLogic Server 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 that you develop onto the Managed Servers and use the Administration Server for configuration and management purposes only.

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 System Administration" in the WebLogic Server Administration Guide.

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 shutdown and restart a server instance.

This section contains the following subsections:

• Replicating Configuration MBeans
• The Lifecycle of Configuration MBeans
• Replication of MBeans for Managed Server Independence
• Documentation for Configuration MBean APIs


 

Replicating Configuration MBeans

To enhance performance and enable flexibility when configuring distributed resources, each Managed Server creates local replicas of the Configuration MBeans for its own managed resources. Objects that interact with MBeans (MBean clients) 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

 

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

In addition to enhancing performance, this distribution of MBeans enables you to choose between making permanent or temporary changes to a server's configuration:

• Changes that you make to an Administration MBean are saved in a configuration file called config.xml and are available across server sessions. You can change an Administration MBean through the Administration Console, the weblogic.Admin command utility, or by using one of the MBean's setter methods.
• Changes that you make to a Local Configuration MBean are not saved to config.xml and apply only to the current server session. You can change a Local Configuration MBean through the weblogic.Admin command utility, by using one of the MBean's setter methods, or by using options of the weblogic.Server startup command. The weblogic.Server options modify the values in the Local Configuration MBean, overriding the values from the Administration MBean. You cannot use the Administration Console to view or modify Local Configuration MBeans.

While the Administration Server always hosts Administration MBeans, it can potentially host Local Configuration MBeans as well. For example, if you set up managed resources on the Administration Server, it must host both the Administration MBeans for all server instances in the domain along with the Local Configuration MBeans associated with the resource. MBean clients on the Administration Server use the Local Configuration MBean. (See Figure 1-3.)

Figure 1-3 Local Configuration MBean on Administration Server

 

The Lifecycle of Configuration MBeans

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

1. The lifecycle 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-4.)

   Figure 1-4 Initializing Configuration MBeans

   
    

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

2. 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 its local resources. 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-5.)

   Figure 1-5 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-6.)

   Figure 1-6 Overriding Values on the Administration Server

   
    

3. 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.
4. 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.
5. 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 the Configuring and Managing WebLogic Server guide.

Documentation for Configuration MBean APIs

To view the documentation for Configuration MBeans, do the following:

1. Open the WebLogic Server Javadoc.
2. In the top left pane of the Web browser, click weblogic.management.configuration.

   The lower left pane displays links for the package.

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

   The right pane displays the package summary. (See Figure 1-7.)

   Figure 1-7 Javadoc for the configuration Package

   
    

4. 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-8) illustrates how Runtime MBeans, Administration MBeans, and Local Configuration MBeans are distributed throughout a domain.

Figure 1-8 Distribution of MBeans

 

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

Figure 1-9 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, do the following:

1. Open the WebLogic Server Javadoc.
2. In the top left pane of the Web browser, click weblogic.management.runtime.

   The lower left pane displays links for the package.

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

   The right pane displays the package summary. (See Figure 1-10.)

   Figure 1-10 Javadoc for the runtime Package

   
    

4. 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 the Developing Security Services for WebLogic Server guide.

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 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-11):

• 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).

• 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.getAttribute
wlMBean.setAttribute
wlMBean.operationName

Figure 1-11 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 Local Configuration MBeans and Runtime MBeans for the current server only.

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. While the Administration MBeanHome provides a single access point for all MBeans in the domain, you must sort through the lookup results to find an MBean for a specific WebLogic Server instance. In addition, it 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-12.)

Figure 1-12 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, you can do the following:

• 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.
• 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 Monitoring WebLogic Server MBeans.

 

---

The Administration Console and the weblogic.Admin Utility

Even if you are developing applications to use the WebLogic Server JMX implementation, you will probably use the WebLogic Server Administration Console and the weblogic.Admin utility for some management tasks. In some cases, you might use these interfaces to familiarize yourself with some area of WebLogic Server management services before developing your JMX applications.

This section contains the following subsections:

• The Administration Console
• The weblogic.Admin Utility

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 next to a field. A help window displays the associated MBean class, attribute, and Javadoc description. (See Figure 1-13.)

Figure 1-13 Viewing MBean Associations from the Administration Console

 

The caution icon (yellow triangle with an exclamation point) 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 (such as Startup Mode in Figure 1-13), the console updates the corresponding Administration MBean For information on how this change is propagated to the Local Configuration MBean, refer to The Lifecycle 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 invoke 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 "MBean Management Command Reference" in the WebLogic Server Command Line Reference.