How WebLogic Uses JMX

Every subsystem and component that comprises WebLogic Server is a resource and, as such, can be managed. Whether it's a mail session, a JMS server, or a connection pool, WebLogic Server uses a JMX object to manage it. Take a look in the Administration Console and click behind one of the question mark icons that appear next to every field and component. A pop-up box is displayed that shows not only what the item is, but also its associated MBean. Similarly, the weblogic.Admin utility also calls upon MBeans to manage resources.

WebLogic Server MBeans

To manage and monitor its resources, WebLogic Server defines and utilizes numerous types of MBeans:

• Configuration MBeans— These are simply MBeans used for managing resources. Attributes are exposed through getter (read) and setter (write) methods. In addition, operations may be called by exposing the appropriate methods.

• Runtime MBeans— These are MBeans that return real-time data about the resources being managed in a running domain. They are typically read-only.

Configuration MBeans

Configuration MBeans are used to manage resources in a domain. WebLogic Server employs two different kinds of configuration MBeans to enhance performance as well as manage changes between an administrative and managed server.

In a typical scenario of one administration server with one or more managed servers, the administration server employs its own configuration MBeans, or Administrative MBeans, to manage its resources. These MBeans are then replicated to each managed server in the domain. The MBean replicas hosted on the managed servers are Local Configuration MBeans.

It's important to distinguish between the two beans. Changes to the Administration MBean properties are domainwide and persisted in the config.xml file. Changes made to Local Configuration MBeans are temporary, and apply only to the current session. Both Administrative and Local Configuration MBeans may be viewed or modified via the weblogic.Admin utility, or by calling the MBean's getter or setter methods; however, only Administrative MBeans may be viewed or changed with the Administration Console. To change a Local Configuration MBean value, you can use the weblogic.Server options in the managed server's startup script.

Runtime MBeans

Runtime MBeans are used to return the performance data of resources in a running domain. Runtime MBeans on the administration server are not replicated to other domain members, and each server in the domain has its own set of Runtime MBeans. It's also important to note that Runtime MBeans pertain only to the current state, and therefore are not persisted. Runtime MBeans may be viewed or changed in the weblogic.Admin utility, the Administration Console, or programmatically via the JMX API.

The WebLogic JMX Extensions

WebLogic provides hundreds of MBeans that manage all of its resources, and these MBeans all extend WebLogic's own set of JMX extensions. These MBeans map roughly to the objects available in the WLS console. The WebLogic Server set of management extensions, weblogic.management, extends the javax.management API. When used to manage resources in WebLogic, they add a great deal of functionality to the Sun API; however, because WebLogic's management extensions are hidden, you cannot use them in your own custom MBeans. The WebLogic extensions enable you to persist changes to the config.xml file, or to receive remote MBean notification events on an application running in a different JVM than the WebLogic Server JVM.

Accessing WebLogic Server MBeans

Now that we've seen some of the different kinds of MBeans defined in WebLogic Server, let's look at how we can access and manage resources with those MBeans. To get an idea of the many different WebLogic MBeans available to you, refer to the weblogic.management.WebLogicMBean interface in the WebLogic Server API. Its subinterfaces are MBeans that contain the many resources you can manage.

For our example, we'll do something simple, such as retrieve the administration server's state and the host and port it's listening on. To do so, we make use of the weblogic.management.runtime.ServerRuntimeMBean. The ServerRuntimeMBean's getState() method returns a String value for the state of the server. Its getAdminServerHost() method returns a String value for the name of the host it's listening on, and its getAdminServerListenPort() returns an int value for the listening port.

In a text editor, create and save a file WLSMBeanClient.java.

First, import the necessary file packages:

import weblogic.management.MBeanHome;
import weblogic.management.Helper;
import weblogic.management.runtime.ServerRuntimeMBean;
import javax.management.*;

We then need to determine which interface is best to access our MBean. If your application is accessing only WebLogic Server MBeans, you have the choice to use the WebLogic MBeanHome interface or the standard JMX compliant MBeanServer interface. An application that manages any custom MBeans, or may be used in a container other than WebLogic Server, needs to use the javax.management.MBeanServer interface. Because our application is accessing only a WebLogic Server MBean, we'll use the more convenient weblogic.management.MBeanHome class.

Each server in a WebLogic Server domain contains its own instance of MBeanHome. The MBeanHome on an administration server, however, has access to all the MBeans on all server instances in the domain. If we need to access an Administration MBean or MBeans distributed on more than one WebLogic Server instance, we would use the Administration MBeanHome. If your MBean manages a resource on only one managed server instance, you have the choice to use the local server MBeanHome. The local MBeanHome connects you directly to the MBean on the managed server instance, and thus is a little more efficient than routing through the administration server.

In our example, we're accessing an MBean running on the administration server, so we'll use the Administration MBeanHome interface. There are two ways in which we can retrieve the MBeanHome interface. We can either use the standard JNDI lookup or a utility class provided by WebLogic, the weblogic.management.Helper class. We'll take the easy approach and use the Helper class. The Helper class defines two methods: getAdminMBeanHome() to get an administration MBeanHome instance and getMBeanHome() to get a local MBeanHome instance.

For our example, we'll define a main method and create an instance of our Administration MBean home where weblogic is the admin username, weblogic is the password, and t3://localhost:7001 is the URL:

[View full width]
public static void main(String[] args) {
  try {

    MBeanHome mbh = Helper.getAdminMBeanHome("weblogic", "weblogic", "t3://localhost
:7001");

Now that we have an instance of our MBeanHome, we can create an instance of the ServerRuntimeMBean MBean from it. The getRuntimeMBean() method takes two String parameters: The first is the name of the server instance the MBean is resident on and the second is the WebLogic MBean's type.

A quick note on MBean types: Knowing and declaring the type are essential to creating instances of WebLogic Server MBeans. However, it isn't always clear what type the MBean you want actually is. The MBean type is normally derived from the MBean class, less the MBean suffix. Thus, type ServerRuntime is derived from the class name ServerRuntimeMBean. Had we been looking to access a ServletRuntimeMBean, its type would be ServletRuntime, and so forth. This is not, however, a hard-and-fast rule. Configuration MBeans, for instance, often add a -Config suffix to the MBean root name. So, the type of ServerMBean (a configuration MBean) would be ServerConfig.

For our client example, we'll pass in to the getRuntimeMBean() method the default name myserver for the domain's administration server. The second parameter to pass is the type of MBean it's creating, which in our example will be the ServerRuntime type:

[View full width]
ServerRuntimeMBean wlmb = (ServerRuntimeMBean)mbh.getRuntimeMBean ("myserver",
 "ServerRuntime");

Now we can call methods on the ServerRuntimeMBean MBean, such as getState(), getAdminServerHost(), and getAdminServerListenPort():

[View full width]
System.out.println("The admin server's current state is " + wlmb.getState() + ".");
System.out.println("The admin server is listening for connections on " + wlmb
.getAdminServerHost() + ":" + wlmb.getAdminServerListenPort() + ".");

You can then end the try/catch block and the main method. The complete WLSMBeanClient.java class is given in Listing 37.5.

Listing 37.5 WLSMBeanClient.java

import weblogic.management.MBeanHome;
import weblogic.management.Helper;
import weblogic.management.runtime.ServerRuntimeMBean;
import javax.management.*;

public class WLSMBeanClient.java {

  public static void main(String[] args) {
    try {
      MBeanHome mbh = Helper.getAdminMBeanHome("weblogic", "weblogic", "t3://localhost:7001");
      ServerRuntimeMBean wlmb = (ServerRuntimeMBean)mbh.getRuntimeMBean ("myserver",
 "ServerRuntime");
      System.out.println("The admin server's current state is " + wlmb.getState() + ".");
      System.out.println("The admin server is listening for connections on " +wlmb
.getAdminServerHost() + ":" + wlmb.getAdminServerListenPort() + ".");
    }    catch(Exception e)
    {
      e.printStackTrace();
    }
  }
}

Now let's test the client application in a running instance of WebLogic Server. Start your WebLogic Server. Then open a new command window, and run the WLSMBeanClient application:

C:\dev\src\jmx>java WLSMBeanClient

The application will create an instance of the administration server's MBeanHome and an instance of its ServerRuntimeMBean from which you can manage its resources. In Figure 37.12, we see the output of our client application, showing the state of the administration server and the address and port it's listening on.