Programming WebLogic Management Services with JMX
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.
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.
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.)
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.
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.
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 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.)
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.
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:
config.xmlfile. (See Figure 1-3.)
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
8000. (See Figure 1-4.)
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.)
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.
config.xml. Changes also are written to
config.xmlwhen the Administration Server shuts down or when MBean attributes are modified by a WebLogic Server utility such as the Administration Console or
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.
The right pane displays the package summary. (See Figure 1-6.)
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.
You can use the Administration Console, the
weblogic.Admin utility, or MBean APIs to view the values. (See Figure 1-8.)
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.
The right pane displays the package summary. (See Figure 1-9.)
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.
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.
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
MBeanServerinterface, you must use standard JMX methods. For example:
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.
weblogic.management.RemoteMBeanServer, which extends the
RemoteMBeanServerinterface 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.
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
MBeanHome interface. (See Figure 1-11.)
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.
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.
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 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.
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.