Accessing WebLogic Server MBeans

All JMX tasks—viewing or changing MBean attributes, using notifications, and monitoring changes—use the same process for accessing MBeans.

This topic contains the following sections:

• Main Steps for Accessing MBeans
• Determining Which Interfaces to Use
• Accessing an MBeanHome Interface
• Using the MBeanServer Interface to Access MBeans
• Using the Type-Safe Interface to Access MBeans
• WebLogicObjectNames for WebLogic Server MBeans

 

---

Main Steps for Accessing MBeans

The main steps for accessing MBeans in WebLogic Server are as follows:

1. Use a weblogic.management.MBeanHome interface to access the MBean Server.

   You can use the local MBeanHome interface from any instance of WebLogic Server to access the MBeans that are registered and active on the current server instance. If you want access to all MBeans in the domain, you can use the Administration MBeanHome interface on the Administration Server instead of the local MBeanHome interface.

2. Use one of the following interfaces to retrieve, look up, and invoke operations on MBeans:
   • The standard JMX javax.management.MBeanServer interface, which can retrieve and invoke operations on WebLogic Server MBeans or on MBeans that you create.
   • A type-safe interface that WebLogic Server provides. This interface, which is a WebLogic Server extension to JMX, can retrieve and invoke operations only on the MBeans that WebLogic Server provides.

   In most cases, you use these interfaces to retrieve a list of MBeans and then filter the list to retrieve and invoke operations on a specific MBean. However, if you know the WebLogicObjectName of an MBean, you can retrieve an MBean directly by name.

 

---

Determining Which Interfaces to Use

When accessing MBeans, you must make two choices about which interfaces you use:

1. Whether to use the MBeanHome interface on a local server instance or the Administration MBeanHome to access the MBean Server. The MBeanHome interface that you choose determines the set of MBeans you can access.

   The following table lists typical considerations for determining whether to use the local MBeanHome interface or the Administration MBeanHome interface.

   If your application manages...	Retrieve this MBeanHome interface...
   Administration MBeans	Administration MBeanHome
   Multiple WebLogic Server instances in a domain	Administration MBeanHome
   A single WebLogic Server instance in a domain	Local MBeanHome Using the local interface saves you the trouble of filtering MBeans to find those that apply to the single server. Using the local interface also uses fewer network hops to access MBeans, because you are connecting directly to the Managed Server.

   
    

2. Whether to use the standard JMX MBeanServer interface or the WebLogic Server type-safe interface to access and invoke operations on MBeans.

   The following table lists typical considerations for determining whether to use the MBeanServer interface or the type-safe interface.

   If your application...	Use this interface...
   Interacts only with WebLogic Server MBeans.	The WebLogic Server type-safe interface
   Might need to run on J2EE platforms other than WebLogic Server	MBeanServer
   Interacts with non-WebLogic Server MBeans	MBeanServer

   
    

   
    

 

---

Accessing an MBeanHome Interface

The simplest process for retrieving a local MBeanHome interface or an Administration MBeanHome interface is to use the WebLogic Server Helper class. If you are more comfortable with a standard J2EE approach, you can use the Java Naming and Directory Interface (JNDI) to retrieve MBeanHome.

This section contains the following subsections:

• Using the Helper APIs to Retrieve an MBeanHome Interface
• Using JNDI to Retrieve an MBeanHome Interface

Using the Helper APIs to Retrieve an MBeanHome Interface

WebLogic Server provides the weblogic.management.Helper APIs to simplify the process of retrieving MBeanHome interfaces.

To use the Helper APIs, collect the following information:

• The username and password of a user who has permission to invoke MBean operations.
• If you are accessing a local MBeanHome interface, the name of the target server (as defined in the domain configuration) and the URL of the target server.
• If you are accessing the Administration MBeanHome, the URL of the Administration Server.

After you collect the information, use one of the following APIs:

• To retrieve a local MBeanHome:
  Helper.getMBeanHome(java.lang.String user, java.lang.String password, java.lang.String serverURL, java.lang.String serverName)
• To retrieve the Administration MBeanHome: Helper.getAdminMBeanHome(java.lang.String user, java.lang.String password, java.lang.String adminServerURL)

For more information about the APIs, refer to the Helper Javadoc.

Example: Retrieving a Local MBeanHome Interface

The following example (Listing 2-1) is a class that uses the Helper API to obtain the local MBeanHome interface for a server named peach.

Listing 2-1 Retrieving a Local MBeanHome Interface

public void find(String host,
                     int port,
                   String username 
                     String password){

        String url = "t3://" + host +
                     ":" + port;

        try {
            localHome = (MBeanHome)Helper.getMBeanHome(username,
                                                       password,
                                                       url,
                                                       "peach");
            System.out.println("Local MBeanHome " +
                               "found using the Helper class");
        } catch (IllegalArgumentException iae) {
            System.out.println("Illegal Argument Exception: " + iae);
        } 
    }

Using JNDI to Retrieve an MBeanHome Interface

While the Helper APIs provide a simple way to obtain an MBeanHome interface, you might be more familiar with the standard approach of using JNDI to retrieve the MBeanHome. From the JNDI tree of a Managed Server, you can access the server's local MBeanHome interface. From the JNDI tree of the Administration Server, you can access the Administration MBeanHome as well as the local MBeanHome interface for any server instance in the domain.

To use JNDI to retrieve an MBeanHome interface, do the following:

1. Use weblogic.jndi.Environment methods to set an initial context.

   If your application and the MBeanHome that you want to retrieve are running in the same JVM, the following API is sufficient for setting an initial context:
   Environment.getInitialContext()

   If your application and the MBeanHome are in different JVMs, you must use Environment methods to set the initial context with the following properties:

   • The URL of the WebLogic Server instance that hosts the MBeanHome you want to retrieve.
   • The username and password of a user who has permission to access the MBean.

   For example, the following lines of code set the initial context to a host named peach:

   Environment env = new Environment();
   env.setProviderUrl("t3://peach:7001");
   env.setSecurityPrincipal("weblogic");
   env.setSecurityCredentials("weblogic");
   Context ctx = env.getInitialContext();

   For more information about weblogic.jndi.Environment, refer to the WebLogic Server Javadoc.

2. Use javax.naming.Context.lookup(String name) to retrieve the MBeanHome interface.

   Supply one of the following values for the name argument depending on which MBeanHome interface you are retrieving:

   • To retrieve the local MBeanHome for the current context, use the following value:
     MBeanHome.LOCAL_JNDI_NAME
   • If the current context is an Administration Server, you can supply the following value to retrieve the local MBeanHome of any server instance in the domain:
     weblogic.management.home.relevantServerName

   where relevantServerName is the name of a server as defined in the domain configuration.

   • If the current context is an Administration Server, you can supply the following value to retrieve the Administration MBeanHome:
     MBeanHome.ADMIN_JNDI_NAME

   The Administration MBeanHome interface provides access to all Local Configuration, Administration, and Runtime MBeans in the domain.

   For more information about javax.naming.Context.lookup(String name), refer to the JNDI Javadoc.

The following sections provide examples for retrieving MBeanHome interfaces:

• Example: Retrieving the Administration MBeanHome from an External Client
• Example: Retrieving a Local MBeanHome from an Internal Client

Example: Retrieving the Administration MBeanHome from an External Client

The following example (Listing 2-2) shows how an application running in a separate JVM would look up the Administration MBeanHome interface. In the example, weblogic is a user who has permission to view and modify MBean attributes. For information about permissions to view and modify MBeans, refer to "Protecting System Administration Operations" in the WebLogic Server Administration Guide.

Listing 2-2 Retrieving the Administration MBeanHome from an External Client

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.AuthenticationException;
import javax.naming.CommunicationException;
import javax.naming.NamingException;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;

...

  public static void main(String[] args) {
    
   MBeanHome home = null;

   //domain variables
   String url = "t3://localhost:7001";

   String username = "weblogic";
   String password = "weblogic";

   //Setting an initial context.
   try {
    Environment env = new Environment();
    env.setProviderUrl(url);
    env.setSecurityPrincipal(username);
    env.setSecurityCredentials(password);
    Context ctx = env.getInitialContext();

    //Retrieving the Administration MBeanHome interface
    home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
    System.out.println("Got the Admin MBeanHome: " + home + " from the Admin server");

    } catch (Exception e) {
      System.out.println("Exception caught: " + e);
     }

Example: Retrieving a Local MBeanHome from an Internal Client

If your client application resides in the same JVM as the Administration Server (or the WebLogic Server instance you want to manage), the JNDI lookup for the MBeanHome is simpler. Listing 2-3 shows how a servlet running in the same JVM as the Administration Server would look up the local MBeanHome for a server instance named melon.

Listing 2-3 Retrieving a Local MBeanHome from an Internal Client

import java.io.PrintWriter;
import java.io.IOException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.ServletException;
import weblogic.logging.NonCatalogLogger;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import javax.naming.Context;

public class MyServlet extends HttpServlet {

public void findInternal() {
      Environment env = new Environment();

      try {

         //Setting the initial context
         ctx = env.getInitialContext();

         //Retrieving the server-specific MBeanHome interface
         home = (MBeanHome)ctx.lookup(weblogic.management.home.melon);
         System.out.println("Got the Server-specific MBeanHome: " + home);

     } catch (Exception e) {
      System.out.println("Exception caught: " + e);
     }

}

 

---

Using the MBeanServer Interface to Access MBeans

A standard JMX approach for interacting with MBeans is to use the javax.management.MBeanServer interface to look up MBeans that are within the scope of the MBeanHome interface. Then you use the MBeanServer interface to get or set MBean attributes or to invoke MBean operations.

The example class in Listing 2-4 uses JNDI to retrieve the Administration MBeanHome interface. Then it retrieves the MBeanServer interface and uses a query to look up all instances of JDBCConnectionPoolMBean in the domain.

For the complete list of MBeanServer methods, refer to 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.

Listing 2-4 Using the MBeanServer Interface

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.AuthenticationException;
import javax.naming.CommunicationException;
import javax.naming.NamingException;
import javax.management.MBeanServer;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.RemoteMBeanServer;

...

  public static void main(String[] args) {
    
   MBeanHome home = null;
   RemoteMBeanServer homeServer = null;

   //domain variables
   String url = "t3://localhost:7001";

   String username = "weblogic";
   String password = "weblogic";

   //Setting an initial context.
   try {
    Environment env = new Environment();
    env.setProviderUrl(url);
    env.setSecurityPrincipal(username);
    env.setSecurityCredentials(password);
    Context ctx = env.getInitialContext();

    //Retrieving the Administration MBeanHome interface
    home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
    System.out.println("Got the Admin MBeanHome: " + home + " from the Admin server");

    } catch (Exception e) {
      System.out.println("Exception caught: " + e);

    //Retrieving the MBeanServer interface
    homeServer = home.getMBeanServer();

    //Retrieving a list of MBeans with object names that include 
    //"JDBCConnectionPool"
   java.util.Set JDBCMBeans = homeServer.queryNames(new 
                    ObjectName("mydomain:Type=JDBCConnectionPool,*"), query);
   //where "query" could be any object that implements the JMX 
   //javax.managementQueryExp

   for (Iterator itr = JDBCMBeans.iterator(); itr.hasNext(); ) {
            WebLogicMBean mbean = (WebLogicMBean)itr.next();
             System.out.println("Matches to the MBean query:" + mbean);
    }
}

 

---

Using the Type-Safe Interface to Access MBeans

A simpler approach for accessing MBeans is to use methods of the MBeanHome interface. These methods look up WebLogic Server MBeans and return a type-safe interface that you can use to get and set attributes and invoke MBean operations.

This section contains the following subsections:

• Retrieving a List of All MBeans
• Retrieving MBeans By Type and Selecting From the List

Retrieving a List of All MBeans

You can use the MBeanHome.getAllMBeans method to look up the object names of MBeans that are within the scope of the MBeanHome interface that you retrieve. For example, if you retrieve the Administrative MBeanHome, using getAllMBeans() returns a list of all MBeans in the domain.

The example code in Listing 2-5 retrieves all MBeans in the domain. It then uses weblogic.management.WebLogicMBean.getName() to retrieve the Name value of the WebLogicObjectName.

Listing 2-5 Retrieving All MBeans in a Domain

public void displayMBeans() {

        Set allMBeans = home.getAllMBeans();
        System.out.println("Size: " + allMBeans.size());
        for (Iterator itr = allMBeans.iterator(); itr.hasNext(); ) {
            WebLogicMBean mbean = (WebLogicMBean)itr.next();
            WebLogicObjectName objectName = mbean.getObjectName();
            System.out.println(objectName.getName() +
                               " is a(n) " +
                               mbean.getType());
        } 
    } 

For more information about the MBeanHome.getAllMBeans method, refer to WebLogic Server Javadoc.

Retrieving MBeans By Type and Selecting From the List

Instead of retrieving a list of all MBeans in the scope of MBeanHome, you can retrieve only the list of MBeans that match a specific type. Type indicates the type of resource that the MBean manages and whether the MBean is an Administration, Local Configuration, or Runtime MBean. For more information about types of MBeans, refer to the next section, WebLogicObjectNames for WebLogic Server MBeans.

The example class in Listing 2-6 retrieves a list of all ServerRuntime MBeans in a domain, and then iterates through the list to select the ServerRuntime for a server named Server1.

Listing 2-6 Selecting from a List of MBeans

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.*;
import weblogic.jndi.Environment;

import weblogic.management.MBeanHome;
import javax.management.ObjectName;
import weblogic.management.WebLogicMBean;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.runtime.ServerRuntimeMBean;
import weblogic.management.WebLogicObjectName;

public class serverRuntimeInfo3 {

  public static void main(String[] args) {

       MBeanHome home = null;

//domain variables
   String url = "t3://localhost:7001";
   String serverName = "Server1"; 
   String username = "weblogic";
   String password = "weblogic";

   ServerRuntimeMBean serverRuntime = null;
   Set mbeanSet = null;
   Iterator mbeanIterator = null;

//Setting the initial context
   try {
    Environment env = new Environment();
    env.setProviderUrl(url);
    env.setSecurityPrincipal(username);
    env.setSecurityCredentials(password);
    Context ctx = env.getInitialContext();

// Getting the Administration MBeanHome.
    home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
    System.out.println("Got the Admin MBeanHome: " + home );
   } catch (Exception e) {
      System.out.println("Exception caught: " + e);
     }   

    /* Here we use the getMBeansByType method to get the set of ServerRuntime mbeans
     * Then we iterate through the set. We retrieve the ServerRuntimeMbean we are
     * interested in by comparing the name to the name of the server.
     */

  try { 
     mbeanSet = home.getMBeansByType("ServerRuntime"); 
     mbeanIterator = mbeanSet.iterator();
     while(mbeanIterator.hasNext()) {
	    serverRuntime = (ServerRuntimeMBean)mbeanIterator.next();
	    if(serverRuntime.getName().equals(serverName)) {
	     System.out.println("we have got the serverRuntimembean: " + serverRuntime +
      " for: " + serverName);
   }
}

For more information about the MBeanHome.getMBeansByType method, refer to WebLogic Server Javadoc.

 

---

WebLogicObjectNames for WebLogic Server MBeans

Each WebLogic Server MBean is registered in the MBean Server under a name that conforms to the weblogic.management.WebLogicObjectName conventions. If you know the WebLogicObjectName of an MBean, after you retrieve an MBeanHome interface, you can retrieve an MBean directly by name.

The MBean's WebLogicObjectName uses the following conventions to provide a unique identification for a given MBean across all domains:

domain:Name=name,Type=type[,attr=value]... 

The following table describes each name component.

This Component	Specifies
domain	The name of the WebLogic Server administration domain.
Name=name	The string that you provided when you created the associated resource. For example, when you create a JDBC connection pool, you must provide a name for that pool, such as MyPool1. The JDBCConnectionPoolMBean that represents MyPool1 uses Name=MyPool1 in its JMX object name. The WebLogicObjectName.getName method returns this value for any given MBean.
Type=type	Refers to the interface class of which the MBean is an instance. All WebLogic Server MBeans are an instance of one of the interface classes defined in the weblogic.management.configuration or weblogic.management.runtime packages. For Configuration MBeans, type also refers to whether an instance is an Administration MBean or a Local Configuration MBean. For a complete list of all WebLogic Server MBean interface classes, refer to the WebLogic Server Javadoc for the weblogic.management.configuration or weblogic.management.runtime packages. To determine the value that you provide for the Type component, do the following: 1. Find the MBean's interface class and remove the MBean suffix from the class name. For example, for an MBean that is an instance of the weblogic.management.runtime.JDBCConnectionPoolRuntimeMBean, use JDBCConnectionPoolRuntime. 2. For a Local Configuration MBean, append Config to the name. For example, for a Local Configuration MBean that is an instance of the weblogic.management.configuration.JDBCConnectionPoolMBean interface class, use JDBCConnectionPoolConfig. For the corresponding Administration MBean instance, use JDBCConnectionPool.
Location=servername	All Runtime and Local Configuration MBeans include a Location component that specifies the name of the server on which that MBean is located. Administration MBeans do not include this component. For example, for the ServletRuntime MBean that runs on a server named myserver, the WebLogicObjectName includes the following components: mydomain:Name=myServlet,Type=ServletRuntime,Location=myserver The WebLogicObjectName.getLocation method returns this value for any given MBean.
TypeOfParentMBean= NameOfParentMBean	Runtime, Local Configuration, or Administration MBeans that have a child relationship with a parent MBean use this extra attribute in their object names to identify the relationship. Note: With the exception of DomainMBean, all MBeans are direct or indirect children of the domain's DomainMBean. Because this parent-child relationship applies to all MBeans, it is not expressed in WebLogicObjectName. For example, an instance of LogMBean is used by a domain to configure the domain-wide log file. Each WebLogic Server instance also maintains its own instance of LogMBean to configure its server-specific log file. The LogMBean that a domain uses does not express a child relationship, while the LogMBean that a server instance uses expresses its child relationship with the server's ServerMBean. (See Figure 2-1.) To express the name of the Administration LogMBean that examplesServer uses to maintain its log file, use the following name: examples:Name=examplesServer,Server=examplesServer,Type=Log To express the name of the Local Configuration LogMBean that examplesServer uses to maintain its log file, use the following name: examples:Location=examplesServer,Name=examplesServer,ServerConfig=examplesServer,Type=LogConfig By convention, WebLogic Server child MBeans use the same value for the Name component as the parent MBean. For example, the LogMBean that is a child of the examplesServer Server MBean uses Name=examplesServer in its WebLogicObjectName. WebLogic Server cannot follow this convention when a parent MBean has multiple children of the same type. To determine whether the WebLogicObjectName of an MBean expresses a parent-child relations, use the WebLogicObjectName.getParent method or the weblogic.Admin GET command.

 

Figure 2-1 Parent-Child Relation of LogMBean Instances

 

Using weblogic.Admin to Find the WebLogicObjectName

If you are unsure which values to supply for an MBean's WebLogicObjectName, you can use the weblogic.Admin utility to find the WebLogicObjectName. The utility can return information only for WebLogic Server MBeans that are on an active server instance.

For example, to find the WebLogicObjectName for the Administration instance of the LogMBean in the examples domain, enter the following command on the examplesServer Administration Server, where the Administration Server is listening on port 8001 and weblogic is the name and password of a user who has permission to view MBean attributes:

java weblogic.Admin -url http://localhost:8001 -username weblogic -password weblogic GET -pretty -type Log

The command returns the output in Listing 2-7. Notice that the command returns two MBeans of type Log on the Administration Server. The first MBean, examples:Name=examplesServer,Server=examplesServer,Type=Log, has a child relationship with the ServerMBean of examplesServer; this relationship indicates that the MBean is the LogMBean that configures the server-specific log file. The second MBean, examples:Name=examples,Type=Log, has no child relationship, which indicates that it configures the domain-wide log file.

Listing 2-7 Output from weblogic.Admin

---------------------------
MBeanName: "examples:Name=examplesServer,Server=examplesServer,Type=Log"
        CachingDisabled: true
        FileCount: 7
        FileMinSize: 500
        FileName: examplesServer\examplesServer.log
        FileTimeSpan: 24
        Name: examplesServer
        Notes:
        NumberOfFilesLimited: false
        ObjectName: examplesServer
        Registered: false
        RotationTime: 00:00
        RotationType: none
        Type: Log

---------------------------
MBeanName: "examples:Name=examples,Type=Log"
        CachingDisabled: true
        FileCount: 7
        FileMinSize: 500
        FileName: ./logs/wl-domain.log
        FileTimeSpan: 24
        Name: examples
        Notes:
        NumberOfFilesLimited: false
        ObjectName: examples
        Registered: false
        RotationTime: 00:00
        RotationType: none
        Type: Log

To view the Local Configuration MBean instances of LogMBean, append Config to the value of the type argument:

java weblogic.Admin -url http://localhost:8001 -username weblogic -password weblogic GET -pretty -type LogConfig

The command returns output in Listing 2-8. Notice that the WebLogicObjectName of the Local Configuration MBeans includes a Location component.

Listing 2-8 Local Configuration MBeans

---------------------------
MBeanName: "examples:Location=examplesServer,Name=examplesServer,ServerConfig=examplesServer,Type=LogConfig"
        CachingDisabled: true
        FileCount: 7
        FileMinSize: 500
        FileName: examplesServer\examplesServer.log
        FileTimeSpan: 24
        Name: examplesServer
        Notes:
        NumberOfFilesLimited: false
        ObjectName: examplesServer
        Registered: false
        RotationTime: 00:00
        RotationType: none
        Type: LogConfig

---------------------------
MBeanName: "examples:Location=examplesServer,Name=examples,Type=LogConfig"
        CachingDisabled: true
        FileCount: 7
        FileMinSize: 500
        FileName: ./logs/wl-domain.log
        FileTimeSpan: 24
        Name: examples
        Notes:
        NumberOfFilesLimited: false
        ObjectName: examples
        Registered: false
        RotationTime: 00:00
        RotationType: none
        Type: LogConfig