2 Understanding WebLogic Server MBeans

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:

• Basic Organization of a WebLogic Server Domain

• Separate MBean Types for Monitoring and Configuring

• The Life Cycle of WebLogic Server MBeans

• WebLogic Server MBean Data Model

• MBean Servers

• Security for WebLogic Server MBeans

The Oracle WebLogic Server MBean Reference provides a detailed reference for all WebLogic Server MBeans.

Basic Organization of a WebLogic Server Domain

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 Oracle WebLogic Server Domains" in Understanding Domain Configuration for Oracle WebLogic Server.

Separate MBean Types for Monitoring and Configuring

All WebLogic Server MBeans can be organized into one of the following general types based on whether the MBean monitors or configures servers and resources:

• Runtime MBeans contain information about the run-time state of a server and its resources. They generally contain only data about the current state of a server or resource, and they do not persist this data. When you shut down a server instance, all run-time statistics and metrics from the run-time MBeans are destroyed.

• Configuration MBeans contain information about the configuration of servers and resources. They represent the information that is stored in the domain's XML configuration documents.

• Configuration MBeans for system modules contain information about the configuration of services such as JDBC data sources and JMS topics that have been targeted at the system level. Instead of targeting these services at the system level, you can include services as modules within an application. These application-level resources share the life cycle and scope of the parent application. However, WebLogic Server does not provide MBeans for application modules. See "Supported Deployment Units" in Deploying Applications to Oracle WebLogic Server.

The Life Cycle of WebLogic Server MBeans

The life cycle of a run-time MBean follows that of the resource for which it exposes run-time data. For example, when you start a server instance, the server instantiates a ServerRuntimeMBean and populates it with the current run-time data. Each resource updates the data in its run-time MBean as its state changes. The resource destroys its run-time MBeans when it is stopped.

For a configuration MBean, the life cycle is as follows:

1. Each server in the domain has its own copy of the domain's configuration documents (which consist of a config.xml file 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 for Oracle WebLogic Server.

   Figure 2-1 Initializing Configuration MBeans on Administration Server

   
   Description of "Figure 2-1 Initializing Configuration MBeans on Administration Server"
   
   

   The configuration MBeans enable each server instance in the domain to have an identical in-memory representation of the domain's configuration.

2. To control changes to the domain's configuration, JMX clients have read-only access to these configuration MBeans.

   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 for Oracle WebLogic Server.

3. Configuration MBeans are destroyed when you shut down the server instance that hosts them.

WebLogic Server MBean Data Model

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

The following sections describe the patterns that WebLogic Server MBeans use to model the underlying XML configuration:

• Containment and Reference Relationships

• WebLogic Server MBean Object Names

Containment and Reference Relationships

MBean attributes that provide access to other MBeans represent one of following types of relationships:

• Containment, which reflects a parent-child relationship between the corresponding XML elements in the domain's configuration document.

• Reference, which reflects a sibling or other non-ancestor, non-descendant relationship.

Containment Relationship

The XML excerpt in Example 2-1 illustrates a containment relationship between <domain> and <server> and <domain> and <cluster>.

Example 2-1 Containment Relationship in XML

<domain>
   <server>
      <name>MyServer</name>
   </server>
   <cluster>
      <name>MyCluster</name>
   </cluster>
</domain>

To reflect this relationship, DomainMBean has two attributes, Servers and 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 ClusterMBeans.

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

Note:

JMX clients cannot use javax.management.MBeanServer.create() or 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 MBeanServer.create() or 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 LogMBean.

With a containment relationship, the parent MBean also contains a lookupChild 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 lookupServers(String name), 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 MS1.

Reference Relationship

The XML excerpt in Example 2-2 illustrates a reference relationship between <server> and <cluster>.

Example 2-2 Reference Relationship in XML

<domain>
   <server>
      <name>MyServer</name>
      <cluster>MyCluster</cluster>
   </server>
   <cluster>
      <name>MyCluster</name>
   </cluster>
</domain>

While a server logically belongs to a cluster, the <server> and <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.

MBeans in a reference relationship do not provide factory methods.

WebLogic Server MBean Object Names

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.

WebLogic Sever naming conventions encode its MBean object names as follows:

com.bea:Name=name,Type=type[,TypeOfParentMBean=NameOfParentMBean]
[,TypeOfParentMBean1=NameOfParentMBean1]... 

where:

• com.bea: is the JMX domain name.

  For WebLogic Server MBeans, the JMX domain is always com.bea. If you create custom MBeans for your applications, name them with your own JMX domain.

• Name=name,Type=type[,TypeOfParentMBean=NameOfParentMBean] [,TypeOfParentMBean1=NameOfParentMBean1]... is a set of JMX key properties.

The order of the key properties is not significant, but the name must begin with com.bea:.

Table 2-1 describes the key properties that WebLogic Server encodes in its MBean object names.

Table 2-1 WebLogic Server MBean Object Name Key Properties

This Key Property	Specifies
Name=name	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 ServerMBean that represents MS1 uses Name=MS1 in its JMX object name. If you create an MBean, you must specify a value for this Name component that is unique amongst all other MBeans in a domain.
Type=type	For configuration MBeans and run-time MBeans, the short name of the MBean's type. The short name is the unqualified type name without the MBean suffix. For example, for an MBean that is an instance of the ServerRuntimeMBean, use ServerRuntime. For MBeans that manage services targeted at the system level, the fully qualified name of the MBean's type including any Bean or MBean suffix. For example, for an MBean that manages a system-level JDBC data source, use weblogic.j2ee.descriptor.wl.JDBCDataSourceBean.
TypeOfParentMBean= NameOfParentMBean	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 LogMBean at the domain level of the hierarchy manages the domain-wide message log, while a LogMBean at a server level manages a server-specific message log. WebLogic Server child MBeans with implicit creator methods use the same value for the Name property as the parent MBean. For example, the LogMBean that is a child of the MedRecServer Server MBean uses Name=MedRecServer in its object name: medrec:Name=MedRecServer,Type=Log,Server=MedRecServer WebLogic Server cannot follow this convention when a parent MBean has multiple children of the same type. Some MBeans use multiple instances of this component to provide unique identification. For example, the following is the object name for an EJBComponentRuntime MBean for in the MedRec sample application: medrec:ApplicationRuntime=MedRecServer_MedRecEAR, Name=MedRecServer_MedRecEAR_Session EJB,ServerRuntime=MedRecServer,Type=EJBComponentRuntime The ApplicationRuntime=MedRecServer_MedRecEAR key property indicates that the EJB instance is a module within the MedRec enterprise application and a child of the MedRecServer_MedRecEAR ApplicationRuntimeMBean. The ServerRuntime=MedRecServer key property indicates that the EJB instance is currently deployed on a server named MedRecServer and a child of the MedRecServer ServerRuntimeMBean.
Location=servername	When you access run-time MBeans or configuration MBeans through the Domain Runtime MBean Server, the MBean object names include a Location=servername key property which specifies the name of the server instance on which that MBean is located. See MBean Servers. Singleton MBeans, such as DomainRuntimeMBean and ServerLifeCycleRuntimeMBean exist only on the Administration Server and do not need to include this key property.

MBeanServerInvocationHandler

If you use the MBeanServerInvocationHandler to create a proxy for the MBean, as shown here:

Intf proxy = (Intf)
     MBeanServerInvocationHandler.newProxyInstance(mbs,
                                                   name,
                                                   Intf.class,
                                                   false);

you should include the WLS extension MBeanServerInvocationHandler instead of javax.management.MBeanServerInvocationHandler, as shown here:

import weblogic.management.jmx.MBeanServerInvocationHandler;

This ensures that return exceptions are handled correctly.

MBean Servers

At the core of any JMX agent is the MBean server, which acts as a container for MBeans.

The JVM for an Administration Server maintains three MBean servers provided by Oracle and optionally maintains the platform MBean server, which is provided by the JDK itself. The JVM for a Managed Server maintains only one Oracle MBean server and the optional platform MBean server.

Table 2-2 describes each MBean server.

Table 2-2 MBean Servers in a WebLogic Server Domain

This MBean server	Creates, registers, and provides access to...
Domain Runtime MBean Server	MBeans for domain-wide services. This MBean server also acts as a single point of access for MBeans that reside on Managed Servers. You can register your own (custom) MBeans in this MBean server (see "Registering Custom MBeans in the Domain Runtime MBean Server" in Developing Manageable Applications With JMX for Oracle WebLogic Server). If your JMX client accesses WebLogic Server MBeans in this MBean server by constructing object names, the client must add a Location=servername key property to the MBean object name. See WebLogic Server MBean Object Names. Only the Administration Server hosts an instance of this MBean server.
Runtime MBean Server	MBeans that expose monitoring, run-time control, and the active configuration of a specific WebLogic Server instance. You can also register your own (custom) MBeans in this MBean server (see "Registering Custom MBeans in the Domain Runtime MBean Server" in Developing Manageable Applications With JMX for Oracle WebLogic Server). In this release, the WebLogic Server Runtime MBean Server is configured by default to be the platform MBean server. However, you can configure WebLogic Server to create a separate MBean Server and use it instead of the platform MBean Server. See Using the Platform MBean Server. Each server in the domain hosts an instance of this MBean server.
Edit MBean Server	Pending configuration MBeans and operations that control the configuration of a WebLogic Server domain. It exposes a ConfigurationManagerMBean for locking, saving, and activating changes. Only the Administration Server hosts an instance of this MBean server.
The JVM's platform MBean server	MBeans provided by the JDK that contain monitoring information for the JVM itself. You can register custom MBeans in this MBean server. In this release, WebLogic Server uses the JVM's platform MBean server to contain the WebLogic run-time MBeans by default. As such, the platform MBean server provides access to platform MXBeans, WebLogic run-time MBeans, and WebLogic configuration MBeans that are on a single server instance. See Using the Platform MBean Server, and "Registering MBeans in the JVM Platform MBean Server" in Developing Manageable Applications With JMX for Oracle WebLogic Server.

Connecting to MBean Servers

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.

Local Connections to MBean Servers

JMX clients running within a WebLogic Server JVM can access the server's Runtime MBean Server or Domain Runtime MBean Server directly through JNDI and must be authenticated to do so. These are the only WebLogic Server MBean servers that allow local access. When accessed from a local client, the Runtime MBean Server or Domain Runtime MBean Server returns its javax.management.MBeanServer interface, which enables clients to access WebLogic Server MBeans and to create, register, and access custom MBeans. See Make Local Connections to the Runtime MBean Server, and Make Local Connections to the Domain Runtime MBean Server.

JMX clients can also access the local JVM's platform MBean server. Any local client can access the MBeans in this MBean server. See "Registering MBeans in the JVM Platform MBean Server" in Developing Manageable Applications With JMX for Oracle WebLogic Server.

Remote Connections to MBean Servers

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 (see Security for WebLogic Server MBeans). When accessed from a remote client, a WebLogic Server MBean server returns its javax.management.MBeanServerConnection interface, which enables clients to only 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. See "Registering MBeans in the JVM Platform MBean Server" in Developing Manageable Applications With JMX for Oracle WebLogic Server.

Using the Platform MBean Server

In this release of WebLogic Server, the WebLogic Server Runtime MBean Server is configured by default to contain the platform MXBeans for the corresponding server. The Domain Runtime MBean Server contains the platform MXBeans for all of the servers in the domain. The MBean object names for the platform MXBeans will be the same as those provided by the JVM except they will have the additional Location=servername key property.

The WLST script in Example 2-3 illustrates using platform MXBeans to monitor the resources of a running domain.

Example 2-3 Using Platform MXBeans

"""
 This WLST script demonstrates how to use the Platform MXBeans to monitor
 the resources of a running WLS domain. It uses the domainCustom command
 to retrieve the memory usage for 2 servers in the domain. For information
 on the available platform MXBeans, refer to the following link:
 http://download.oracle.com/javase/6/docs/api/java/lang/management/package-summary.html
"""

connect()
domainCustom()
cd ("java.lang")
# monitor heap and thread usage once a minute for 5 minutes 
x = 0
while x < 5:
    # Admin Server
    cd ("java.lang:Location=AdminServer,type=Memory")
    huAdmin = get("HeapMemoryUsage")
    cd ("..")
    cd ("java.lang:Location=AdminServer,type=Threading")
    numThreadsAdmin = get("ThreadCount")
    print "Admin server memory usage = ", huAdmin.get("max"), " number threads: ", numThreadsAdmin
    cd ("..")
    # m1 server
    cd ("java.lang:Location=m1,type=Memory")
    huM1 = get("HeapMemoryUsage")
    cd ("..")
    cd ("java.lang:Location=m1,type=Threading")
    numThreadM1 = get("ThreadCount")
    cd ("..")
    print "M1 server memory usage = ", huM1.get("max"), " number threads: ", numThreadM1
    Thread.sleep(60000)
    x = x + 1

Using the platform MBean server for the Runtime MBean Server is controlled by the PlatformMBeanServerUsed attribute in the JMX MBean. In previous releases, the default value for the PlatformMBeanServerUsed attribute was false so the platform MBean server was not used unless explicitly enabled. In this release of WebLogic Server, the default value for the PlatformMBeanServerUsed attribute is true for domains that are at version 10.3.3.0 or higher. For more information, see the PlatformMBeanServerEnabled attribute.

If desired, you can configure WebLogic Server to create a separate MBean Server and use it instead of the platform MBean server by setting the PlatformMBeanServerEnabled attribute value to false with either the WebLogic Server Administration Console or WLST. Using the Console, navigate to the Domain > Configuration > General page > Advanced options and deselect the Platform MBean Server Used check box. In WLST, start an edit session, navigate to the JMX directory for the domain, use cmo.setPlatformMBeanServerUsed(false) to change the value, and then activate the changes.

For more information on the Platform MBean Server and Platform MXBean, see the following JAVA SDK documentation:

• http://download.oracle.com/javase/6/docs/technotes/guides/management/mxbeans.html

• http://download.oracle.com/javase/6/docs/api/java/lang/management/package-summary.html

Service MBeans

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.

Table 2-3 Service MBeans

MBean Server	Service MBean	JMX object name:
The Domain Runtime MBean Server	DomainRuntimeServiceMBean 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 run-time MBeans and all active configuration MBeans for all servers in the domain. See "DomainRuntimeServiceMBean" in Oracle WebLogic Server MBean Reference.	com.bea:Name=DomainRuntimeService,Type=weblogic. management.mbeanservers. domainruntime.DomainRuntimeServiceMBean
Runtime MBean Servers	RuntimeServiceMBean Provides access to run-time MBeans and active configuration MBeans for the current server. See "RuntimeServiceMBean" in Oracle WebLogic Server MBean Reference.	com.bea:Name=RuntimeService, Type=weblogic.management. mbeanservers.runtime. RuntimeServiceMBean
The Edit MBean Server	EditServiceMBean Provides the entry point for managing the configuration of the current WebLogic Server domain. See "EditServiceMBean" in Oracle WebLogic Server MBean Reference.	com.bea:Name=EditService, Type=weblogic.management. mbeanservers.edit. EditServiceMBean

Security for WebLogic Server MBeans

To connect to a WebLogic Server MBean server, a JMX client must supply credentials for a user who has been defined in the WebLogic Server domain's security realm.

To further secure the MBeans that have been registered in an MBean server, WebLogic Server uses security roles and policies. A security role, like a security group, grants an identity to a user. Unlike a group, however, membership in a role can be based on a set of conditions that are evaluated at run time. A security policy is another set of run-time conditions that specify which users, groups, or roles can access a resource. Oracle provides a default set of roles and policies for WebLogic Server MBeans. (See "Default Security Policies for MBeans" in the Oracle WebLogic Server MBean Reference.)

During the startup cycle for a WebLogic Server instance, the server creates a collection of weblogic.security.service.JMXResource objects, which are the in-memory representations of the MBean security policies. When a JMX client attempts to get or set an MBean attribute or invoke an operation, the MBean server asks the security realm if the user has sufficient permission. The security realm first determines which role the user is in. (Role assignments are determined at run time.) Then it uses the default policies and any other policies that you have created to determine if the role is allowed access.

You can use the WebLogic Server Administration Console to change the default access permissions. For example, you can create roles for specific applications and allow only specific roles to access the MBean instances that are associated with specific applications. See "Configure JMX Policies" in the Oracle WebLogic Server Administration Console Help.

Additional Security Resources for Some Attributes and Operations

For MBean attributes and operations that represent particularly sensitive data or actions, WebLogic Server provides additional security resource objects to limit which users can access the data or action. For example, the ServerLifeCycleRuntimeMBean's shutdown() operation is protected by a JMXResource object and a weblogic.security.service.ServerResource object. For a complete list of attributes and operations that are protected by multiple resources, see "Administrative Resources" and "Server Resources" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

The default configuration of roles and security policies for these attributes and operations work together to create a consistent security scheme. You can, however, make modifications that limit access in ways that you do not intend. See "Maintaininig a Consistent Security Scheme" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.