Developing Custom Management Utilities with JMX
WebLogic Server® provides its own set of MBeans that you can use to configure, monitor, and manage WebLogic Server resources. The following sections describe how WebLogic Server distributes and maintains its MBeans:
WebLogic Server MBean Reference provides a detailed reference for all WebLogic Server MBeans.
A WebLogic Server administration domain is a collection of one or more servers and the applications and resources that are configured to run on the servers. Each domain must include a special server instance that is designated as the Administration Server. The simplest domain contains a single server instance that acts as both Administration Server and host for applications and resources. This domain configuration is commonly used in development environments. Domains for production environments usually contain multiple server instances (Managed Servers) running independently or in groups called clusters. In such environments, the Administration Server does not host production applications. For more information about domains, refer to "Understanding WebLogic Server Domains" in Understanding Domain Configuration.
The life cycle of a runtime MBean follows that of the resource for which it exposes runtime data. For example, when you start a server instance, the server instantiates a
ServerRuntimeMBean and populates it with the current runtime data. Each resource updates the data in its runtime MBean as its state changes. The resource destroys its runtime MBeans when it is stopped.
config.xmlfile and subsidiary files). During a server's startup cycle, it contacts the Administration Server to update its configuration files with any changes that occurred while it was shut down. Then it instantiates configuration MBeans to represent the data in the configuration documents. (See Figure 2-1.)
Note: By default, a Managed Server will start even if it cannot contact the Administration Server to update its configuration files. This default setting creates the possibility that Managed Servers across the domain might run with inconsistent configurations. For information about changing this default, see "Starting a Managed Server When the Administration Server Is Not Accessible" in Managing Server Startup and Shutdown.
The Administration Server maintains a separate, editable copy of the domain's configuration documents in the domain's
config/pending directory. It uses the data in these pending documents to instantiate a set of configuration MBeans that JMX clients can modify. After a JMX client modifies one of these configuration MBeans, the client directs the Administration Server to save the modifications in the pending configuration documents. Then the client starts a transactional process that updates the read-only configuration documents and configuration MBeans for all server instances in the domain.
For more information, see Managing Configuration Changes in Understanding Domain Configuration.
The 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
The XML excerpt in Listing 2-1 illustrates a containment relationship between
To reflect this relationship,
DomainMBean has two attributes,
Clusters. The value of the
Servers attribute is an array of object names
javax.management.ObjectName) for all
ServerMBeans that have been created in the domain. The value of the
Clusters attribute is an array of object names for all
Another aspect of the containment relationship is expressed in a set of MBean operations that follow the design pattern for Java bean factory methods: for each contained (child) MBean, the parent MBean provides a
Child 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,
Note: JMX clients cannot use
register() to create and register instances of WebLogic Server MBeans because WebLogic Server does not make its MBean implementation classes publicly available.
If you create and register custom MBeans (MBeans you have created to manage your applications), you will have access to your own implementation files and you can use the standard
register() methods. Custom MBeans are not part of the WebLogic Server data model and do not participate in its factory method model.
In some cases, an MBean's factory methods are not public because of dependencies within a server instance. In these cases the parent manages the life cycle of its children. For example, each
ServerMBean must have one and only one child
LogMBean to configure the server's local log file. The factory methods for
LogMBean are not public, and
ServerMBean maintains the life cycle of its
With a containment relationship, the parent
MBean also contains a
Child operation. If you know the user-supplied name that was used to create a specific server or resource, you can use the lookup operation in the parent MBean to get the object name. For example,
DomainMBean includes an operation named
), which takes as a parameter the name that was used to create a server instance. If you named a server
MS1, you could pass a
String object that contains
MS1 to the
lookupServers method and the method would return the object name for
The XML excerpt in Listing 2-2 illustrates a reference relationship between
While a server logically belongs to a cluster, the
<cluster> elements in the domain's configuration file are siblings. To reflect this relationship,
ServerMBean has a
Cluster attribute whose value is the object name (
javax.management.ObjectName) of the
ClusterMBean to which the server belongs.
All MBeans must be registered in an MBean server under an object name of type
javax.management.ObjectName. WebLogic Server follows a convention in which object names for child MBeans contain part of its parent MBean object name.
Note: If you learn the WebLogic Server naming conventions, you can understand where an MBean instance resides in the data hierarchy by observing its object name. However, if you use containment attributes or lookup operations to get object names for WebLogic Server MBeans, your JMX applications do not need to construct or parse object names.
com.bea:is the JMX domain name.
]...is a set of JMX key properties.
Table 2-1 describes the key properties that WebLogic Server encodes in its MBean object names.
The string that you provided when you created the resource that the MBean represents. For example, when you create a server, you must provide a name for the server, such as MS1. The
For configuration MBeans and runtime MBeans, the short name of the MBean's type. The short name is the unqualified type name without the
For MBeans that manage services targeted at the system level, the fully qualified name of the MBean's type including any
To create a hierarchical namespace, WebLogic Server MBeans use one or more instances of this attribute in their object names. The levels of the hierarchy are used to indicate scope. For example, a
WebLogic Server child MBeans with implicit creator methods use the same value for the
Some MBeans use multiple instances of this component to provide unique identification. For example, the following is the object name for an
When you access runtime MBeans or configuration MBeans through the Domain Runtime MBean Server, the MBean object names include a
The JVM for an Administration Server maintains three MBean servers provided by BEA and optionally maintains the platform MBean server, which is provided by the JDK itself. The JVM for a Managed Server maintains only one BEA MBean server and the optional platform MBean server.
Table 2-2 describes each MBean server.
If your JMX client accesses WebLogic Server MBeans in this MBean server by constructing object names, the client must add a
MBeans that expose monitoring, runtime control, and the active configuration of a specific WebLogic Server instance. You can also register your own (custom) MBeans in this MBean server (see Use the Runtime MBean Server in Developing Manageable Applications with JMX).
MBeans provided by the JDK that contain monitoring information for the JVM itself. You can register custom MBeans in this MBean server, but BEA recommends that you register them in its Runtime MBean Server.
You can also configure the WebLogic Server Runtime MBean Server to be the platform MBean server, in which case the platform MBean server provides access to JVM MBeans, Runtime MBeans, and active configuration MBeans that are on a single server instance. See Using the JVM Platform MBean Server in Developing Manageable Applications with JMX.
Note: Remote access to the platform MBean server can be secured only by standard JDK 1.5 security features (see http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote). If you have configured the WebLogic Server Runtime MBean Server to be the platform MBean server, enabling remote access to the platform MBean server creates an access path to WebLogic Server MBeans that is not secured through the WebLogic Server security framework.
JMX enables both local and remote access to MBean servers, but JMX clients use different APIs for the two types of access and WebLogic Server MBean servers expose different capabilities to local clients and remote clients.
JMX clients running within a WebLogic Server JVM can access the server's Runtime MBean Server directly through JNDI and must be authenticated to do so. This is the only WebLogic Server MBean server that allows local access. When accessed from a local client, the Runtime MBean Server returns its
javax.management.MBeanServer interface, which enables clients to access WebLogic Server Means and to create, register, and access custom MBeans. See Make Local Connections to the Runtime MBean Server.
JMX clients can also access the local JVM's platform MBean server. The WebLogic Server security framework does not control access to the platform MBean server. Any local client can access the MBeans in this MBean server. See Using the JVM Platform MBean Server in Developing Manageable Applications with JMX.
Remote JMX clients (clients running in a different JVM from the MBean server) can use the
javax.management.remote APIs to access any WebLogic MBean server. Clients must authenticate through the WebLogic Server security framework to do so. When accessed from a remote client, a WebLogic Server MBean server returns its
javax.management.MBeanServerConnection interface, which enables clients only to access MBeans; remote clients cannot create and register custom MBeans. See Make Remote Connections to an MBean Server.
You can enable remote access to the platform MBean server, but such access is not secured by the WebLogic Server security framework; instead, you must use standard JDK 1.5 security features. See http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote. If it is essential that remote JMX clients have access to the JVM MBeans in the platform MBean server, see Using the JVM Platform MBean Server in Developing Manageable Applications with JMX.
Within each MBean server, WebLogic Server registers a service MBean under a simple object name. The attributes and operations in this MBean serve as your entry point into the WebLogic Server MBean hierarchies and enable JMX clients to navigate to all WebLogic Server MBeans in an MBean server after supplying only a single object name. See Table 2-3.
JMX clients that do not use the entry point (service) MBean must correctly construct an MBean's object name to get and set the MBean's attributes or invoke its operations. Because the object names must be unique, they are usually long and difficult to construct from a client.
Provides access to MBeans for domain-wide services such as application deployment, JMS servers, and JDBC data sources. It also is a single point for accessing the hierarchies of all runtime MBeans and all active configuration MBeans for all servers in the domain.