Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Programming WebLogic Management Services with JMX > Accessing WebLogic Server MBeans

Programming WebLogic Management Services with JMX

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Accessing WebLogic Server MBeans

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

The following sections describe how to access WebLogic Server MBeans:

 

Accessing MBeans: Main Steps

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

  1. Use a weblogic.management.MBeanHome interface to access the MBean Server. See Accessing an MBeanHome Interface.
  2. Use one of the following interfaces to retrieve, look up, and invoke operations on MBeans:

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

 

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.

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:

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

For more information about the Helper APIs, refer to the WebLogic Server 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 MS1.

Listing 2-1 Retrieving a Local MBeanHome Interface

import weblogic.management.Helper;
import weblogic.management.MBeanHome;
public class UseHelper {
    public static void main(String[] args) {
        String url = "t3://localhost:7001";
        String username = "weblogic";
        String password = "weblogic";
        String msName = "MS1";
        MBeanHome localHome = null;
        try {
            localHome = (MBeanHome)Helper.getMBeanHome(username, password, url,
                       msName);
            System.out.println("Local MBeanHome for" + localHome +
                       " 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:

  1. Construct a weblogic.jndi.Environment object and use Environment methods to configure the object:
    1. Use the setSecurityPrincipal and setSecurityCredentials methods to specify user credentials.

      2. WebLogic Server verifies that the user credentials you supply have been granted permission to carry out requests through the MBeanHome interface. For more information, refer to "Security Roles" in the Securing WebLogic Resources guide.

    2. If your application and the MBeanHome interface are in different JVMs, use the Environment.setProviderUrl method to specify the server instance that hosts the MBeanHome interface. The URL must specify the listen address of the server and the port on which the server listens for administrative requests.

      3. If you want to retrieve the Administration MBeanHome, setProviderUrl must specify the Administration Server.

    3. Use the getInitialContext method to initialize a javax.naming.Context object.

    For example, the following lines of code set the initial context to a server instance that runs on a host computer named WLServerHost and uses the default domain-wide administration port to receive administrative requests:

    Environment env = new Environment();
    env.setProviderUrl("t3://WLServerHost:9002");
    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 methods to look up and retrieve the MBeanHome interface for the current context.

    3. Use one of the following APIs, depending on whether you are retrieving a local MBeanHome interface or the Administration MBeanHome:

The following sections are examples of retrieving MBeanHome interfaces:

Example: Retrieving the Administration MBeanHome from an External Client

The following example (Listing 2-2) shows how an application running in a separate JVM looks 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 "Security Roles" in the Securing WebLogic Resources 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 class RetrieveMBeanHome{
    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 myserver.

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.jndi.Environment;
import weblogic.management.MBeanHome;
import javax.naming.Context;
public class MyServlet extends HttpServlet {
    public void doGet(HttpServletRequest req, HttpServletResponse res) 
    throws ServletException{
        doPost(req,res);
    }
    public void doPost(HttpServletRequest req,HttpServletResponse res)
    throws ServletException{
        try {
            Environment env = new Environment();
            env.setProviderUrl("t3://localhost:7001");
        env.setSecurityPrincipal("weblogic");
            env.setSecurityCredentials("weblogic");
            //Setting the initial context
            Context ctx = env.getInitialContext();
             //Retrieving the server-specific MBeanHome interface
            MBeanHome home = (MBeanHome)ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
            System.out.println("Got the Server-specific MBeanHome: " + home);
        } catch (Exception e) {
            System.out.println("Exception caught: " + e);
        }
    }
}

 

Using the Type-Safe Interface to Access MBeans

After you retrieve the MBeanHome interface, the easiest approach for accessing MBeans is to use methods in the MBeanHome interface that retrieve a type-safe interface for MBeans.

You can use this type-safe interface only with the MBeans that WebLogic Server provides. You cannot use this type-safe interface for MBeans that are based on MBean types that you create.

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 Administration MBeanHome, using getAllMBeans() returns a list of all MBeans in the domain. If you retrieve a Local MBeanHome interface, using getAllMBeans() returns a list of the Runtime MBeans for the current server only and of all Local Configuration MBeans in the domain.

The example class in Listing 2-4:

  1. Uses JNDI APIs to retrieve the Administration MBeanHome interface.
  2. Uses the MBeanHome.getAllMBeans method to retrieve all MBeans in a domain.
  3. Assigns the list of MBeans to a Set object and uses methods of the Set and Iterator interfaces to iterate through the list.
  4. Uses the WebLogicMBean.getObjectName method to retrieve the WebLogicObjectName of each MBean.
  5. Uses the WebLogicObjectName.getName and getType methods to retrieve the Name and Type values of the WebLogicObjectName

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 "Security Roles" in the Securing WebLogic Resources guide.

Listing 2-4 Retrieving All MBeans in a Domain

import javax.naming.Context;
import java.util.Set;
import java.util.Iterator;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.WebLogicObjectName;
public class ListAllMBeans{
    public static void main(String args[]) {
        String url = "t3://localhost:7001";
        String username = "weblogic";
        String password = "weblogic";
        try {
            //Obtaining an MBeanHome Using JNDI
            Environment env = new Environment();
            env.setProviderUrl(url);
            env.setSecurityPrincipal(username);
            env.setSecurityCredentials(password);
            Context ctx = env.getInitialContext();
            MBeanHome home = (MBeanHome)ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
            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());
            }
        }catch(Exception e){
            System.out.println(e);
        }
    }
}

For more information about the MBeanHome.getAllMBeans method, refer to the 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 a 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, WebLogic Server Management Namespace.

The example class in Listing 2-5:

  1. Uses JNDI to retrieve the Administration MBeanHome interface.
  2. Uses the MBeanHome.getMBeansByType method to retrieve a list of all ServerRuntime MBeans in a domain.
  3. Assigns the list of MBeans to a Set object and uses methods of the Set and Iterator interfaces to iterate through the list.
  4. Uses the ServerRuntime.getName method to retrieve the name of each ServerRuntime MBean. The name of a ServerRuntime MBean corresponds to the name of a server instance.
  5. When it finds the ServerRuntime MBean for a server named Server1, it prints a message to standard out.

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 "Security Roles" in the Securing WebLogic Resources guide.

Listing 2-5 Selecting by Type from a List of MBeans

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.Context;
import javax.management.ObjectName;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.WebLogicObjectName;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.runtime.ServerRuntimeMBean;
import weblogic.jndi.Environment;
public class serverRuntimeInfo {
    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;
        //Using JNDI to retrieve the Administration MBeanHome
        //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);
        }   
        //Using the getMBeansByType method to get all ServerRuntime MBeans
        //in the domain.
        try { 
            mbeanSet = home.getMBeansByType("ServerRuntime"); 
            //Iterating through the results and comparing the server names
            //find the one we want.
            mbeanIterator = mbeanSet.iterator();
            while(mbeanIterator.hasNext()) {
                serverRuntime = (ServerRuntimeMBean)mbeanIterator.next();
                //Using serverRuntime.getName to find the ServerRuntime
                //MBean for Server1.
                if(serverRuntime.getName().equals(serverName)) {
                    System.out.println("Got the serverRuntimembean: " + 
                    serverRuntime + " for: " + serverName);
                 }
            }
         } catch (Exception e) {
               System.out.println("Exception caught: " + e);
         } 
    }
}

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

Walking the Hierarchy of Local Configuration and Runtime MBeans

WebLogic Server MBeans exist within a hierarchy that reflects the resources with which they are associated. For example, each server instance can contain multiple execute queues, and WebLogic Server represents this relationship by making each ExecuteQueueMBean a child of a ServerMBean.

Walking the hierarchy of MBeans is the easiest way to retrieve Local Configuration and Runtime MBeans. If you want to retrieve Administration MBeans, or if you want to use the Administration MBeanHome to retrieve MBeans, BEA recommends that you retrieve MBeans by type and then filter the list. See Retrieving MBeans By Type and Selecting From the List.

The root of the configuration MBean hierarchy is DomainMBean. Below this root are MBeans such as:

The root of the runtime hierarchy is ServerRuntimeMBean. Just below this root are MBeans such as:

Parent MBeans usually provide methods for retrieving their children. For example, ServerMBean.getExecuteQueues returns all ExecuteQueueMBeans that have been configured for the server.

For more information about the hierarchy, see WebLogic Server Management Namespace.

To walk the hierarchy of Local Configuration MBeans or Runtime MBeans:

  1. From your JMX application, retrieve the local MBeanHome interface.
  2. From the local MBeanHome interface, retrieve one of the top-level MBeans by invoking one of the following methods:

    3. Use these methods to retrieve only MBeans that are immediately below DomainMBean or ServerRuntimeMBean. These methods do not return MBeans that are below the first level of the MBean hierarchy.

  3. From the MBean that you retrieved, invoke methods to retrieve the MBean's children.

    4. If a parent MBean does not provide methods to retrieve child MBeans, use getMBeanByType() and iterate over the results to find the MBean that matches your criteria. If you want to retrieve Local Configuration MBeans, be sure to append Config to the MBean type value. See Retrieving MBeans By Type and Selecting From the List.

Note: BEA recommends that you retrieve Local Configuration MBeans only to read values; 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.

Listing 2-6 is an example of retrieving all Local Configuration ExecuteQueueMBeans on a server instance named MedRecServer.

Listing 2-6 Retrieving Local Configuration ExecuteQueueMBeans

import javax.naming.Context;
import javax.management.ObjectName;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.WebLogicObjectName;
import weblogic.management.configuration.ConfigurationMBean;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.configuration.ExecuteQueueMBean;
import weblogic.jndi.Environment;
public class serverConfigInfo {
    public static void main(String[] args) {
        MBeanHome home = null;
        ServerMBean servercfg = null;
        ExecuteQueueMBean[] xqueues = null;
        ExecuteQueueMBean xqueue = null;
        //domain variables
        String url = "t3://localhost:7001";
        String serverName = "MedRecServer"; 
        String username = "weblogic";
        String password = "weblogic";
        try {
            Environment env = new Environment();
            env.setProviderUrl(url);
            env.setSecurityPrincipal(username);
            env.setSecurityCredentials(password);
            //Setting the initial context
            Context ctx = env.getInitialContext();
            //Retrieving the server-specific MBeanHome interface
            home = (MBeanHome)ctx.lookup(MBeanHome.LOCAL_JNDI_NAME);
            System.out.println("Got the Server-specific MBeanHome: " + home);
           //Retrieving the Local Configuration ServerMBean
            servercfg = (ServerMBean)home.getConfigurationMBean(serverName,
                                                       "ServerConfig");
           System.out.println("Got the Server Config MBean: " + servercfg);
           //Retrieving all ExecuteQueue MBeans that have been
           //configured for the server instance
           xqueues = servercfg.getExecuteQueues();
           //Iterating through the results 
           for (int i=0; i < xqueues.length; i++){
                xqueue = xqueues[i];
                System.out.println("Execute queue name: " + 
                    xqueue.DEFAULT_QUEUE_NAME);
              System.out.println("Thread count:" + xqueue.getThreadCount());
             }
       } catch (Exception e) {
            System.out.println("Exception caught: " + e);
        }
    }
}

If you want to create generic JMX code that you can run on any server instance to retrieve its Server Configuration MBean:

  1. From the local MBeanHome interface, use the getMBeansByType method to retrieve the server's ServerRuntimeMBean:
    serverRuntime = MBeanHome.getMBeansByType(ServerRuntime)

    2. The local MBeanHome interface can access only the runtime MBeans that are specific to the current server instance, so getMBeansByType(ServerRuntime) returns only the ServerRuntimeMBean for the current server.

  2. Use ServerRuntimeMBean's getName method to retrieve the name of the server:
    serverName = serverRuntime.getName()
  3. Use the server name when invoking MBeanHome.getConfigurationMBean:
    MBeanHome.getConfigurationMBean(serverName,"ServerConfig")

For more information, see Example: Determining the Active Domain and Servers.

 

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 the MBeans that are registered in the MBean Server. Then you use the MBeanServer interface to get or set MBean attributes or to invoke MBean operations. 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.

You can use the following techniques to retrieve the MBeanServer interface:

The example code in Listing 2-7 looks up the MBeanServer interface from a server's JNDI tree. To establish an initial context in a WebLogic Server JNDI tree, a client must specify the server's connection information, the name of the WebLogic Server context factory, and the WebLogic Server login credentials. See the Javadoc for javax.naming.Context.

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 "Security Roles" in the Securing WebLogic Resources guide.

Listing 2-7 Retrieving MBeanServer Through JNDI

String url = "t3://localhost:7001"; //URL of the server instance
String username = "weblogic";
String password = "weblogic";
MBeanServer rmbs = null;
Hashtable props = new Hashtable();
props.put(Context.PROVIDER_URL, url);
props.put(Context.INITIAL_CONTEXT_FACTORY,
   "weblogic.jndi.WLInitialContextFactory");
   props.put(Context.SECURITY_PRINCIPAL, username);
   props.put(Context.SECURITY_CREDENTIALS, password);
InitialContext ctx = new InitialContext(props);
rmbs = (MBeanServer) ctx.lookup("weblogic.management.server");

 

Skip navigation bar  Back to Top Previous Next