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
- Determining Which Interfaces to Use
- Accessing an MBeanHome Interface
- Using the Type-Safe Interface to Access MBeans
- Using the MBeanServer Interface to Access MBeans
Accessing MBeans: Main Steps
The main steps for accessing MBeans in WebLogic Server are as follows:
- Use a weblogic.management.MBeanHome interface to access the MBean Server. See Accessing an MBeanHome Interface.
- Use one of the following interfaces to retrieve, look up, and invoke operations on MBeans:
- 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. See Using the Type-Safe Interface to Access MBeans.
- The standard JMX javax.management.MBeanServer interface, which can retrieve and invoke operations on WebLogic Server MBeans or on MBeans that you create. See Using the MBeanServer Interface to Access MBeans.
- The weblogic.management.RemoteMBeanServer interface, which extends the javax.management.MBeanServer and java.rmi.Remote interfaces.
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, make two choices about which interfaces you use:
- Whether to use the MBeanHome interface on a local server instance or the Administration MBeanHome interface 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... Local Configuration MBeans or Runtime MBeans Administration MBeanHome or local MBeanHome The Administration MBeanHome provides a single, convenient interface from which to access all MBeans on all server instances in a domain. When you use this interface, you typically retrieve MBeans from multiple server instances and then iterate through the list to find an MBean for a specific server instance.A local MBeanHome provides access only to the Local Configuration MBeans and Runtime MBeans on a specific server instance. It saves you the trouble of iterating through lists of MBeans. It also uses fewer network hops to access MBeans because it requires your client to establish a direct connection to the server instance. Administration MBeans Administration MBeanHome
- Whether to use the WebLogic Server type-safe interface, the standard JMX MBeanServer interface, or the WebLogic RemoteMBeanServer interface to access and invoke operations on MBeans.
The following table lists typical considerations for determining whether to use the type-safe interface or the MBeanServer interface.
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:
- The username and password of a WebLogic Server user who has permission to invoke MBean operations. For more information, refer to "Security Roles in the Securing WebLogic Resources guide.
- 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 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:
- Construct a weblogic.jndi.Environment object and use Environment methods to configure the object:
- Use the setSecurityPrincipal and setSecurityCredentials methods to specify user credentials.
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.
- 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.
If you want to retrieve the Administration MBeanHome, setProviderUrl must specify the Administration Server.
- 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.
- Use javax.naming.Context methods to look up and retrieve the MBeanHome interface for the current context.
Use one of the following APIs, depending on whether you are retrieving a local MBeanHome interface or the Administration MBeanHome:
- To retrieve the local MBeanHome for the current context, use the following API:
javax.naming.Context.lookup(MBeanHome.LOCAL_JNDI_NAME)- If the current context is an Administration Server, use the following API to retrieve the local MBeanHome of any server instance in the domain:
javax.naming.Context.lookup("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, use the following API to retrieve the Administration MBeanHome:
javax.naming.Context.lookup(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 Sun Javadoc.
The following sections are examples of 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 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 Local Configuration and Runtime MBeans on the current server instance.
The example class in Listing 2-4:
- Uses JNDI APIs to retrieve the Administration MBeanHome interface.
- Uses the MBeanHome.getAllMBeans method to retrieve all MBeans in a domain.
- Assigns the list of MBeans to a Set object and uses methods of the Set and Iterator interfaces to iterate through the list.
- Uses the WebLogicMBean.getObjectName method to retrieve the WebLogicObjectName of each MBean.
- 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:
- Uses JNDI to retrieve the Administration MBeanHome interface.
- Uses the MBeanHome.getMBeansByType method to retrieve a list of all ServerRuntime MBeans in a domain.
- Assigns the list of MBeans to a Set object and uses methods of the Set and Iterator interfaces to iterate through the list.
- 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.
- 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.
The root of the configuration MBean hierarchy is DomainMBean. Below this root are MBeans such as:
- ClusterMBean
- ServerMBean
- ApplicationMBean
- RealmMBean
- JDBC and JMS configuration MBeans
The root of the runtime hierarchy is ServerRuntimeMBean. Just below this root are MBeans such as:
- ClusterRuntimeMBean
- ApplicationRuntimeMBean
- JDBC and JMS runtime MBeans
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:
- From your JMX application, retrieve the local MBeanHome interface.
- From the local MBeanHome interface, retrieve one of the top-level MBeans by invoking one of the following methods:
- getConfigurationMBean (java.lang.String name, java.lang.String type)
See the Javadoc for MBeanHome.getConfigurationMBean.
- getRuntimeMBean (java.lang.String name, java.lang.String type)
See the Javadoc for MBeanHome.getRuntimeMBean.
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.
- From the MBean that you retrieved, invoke methods to retrieve the MBean's children.
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. With some WebLogic Server facilities, such as clustering, a Managed Server replicates a subset of other Managed Server's configuration data. 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); } }
}
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.
In the WebLogic Server implementation of JMX, you use the MBeanHome interface to look up the MBeanServer interface.
The example class in Listing 2-7:
- Uses JNDI to retrieve the Administration MBeanHome interface. Because this example retrieves Administration MBeans, it must use the Administration MBeanHome interface.
- Uses the Administration MBeanHome interface to retrieve the MBeanServer interface.
- Uses the MBeanServer.queryNames method to look up all instances of JDBCConnectionPoolMBean in the domain. Note that the queryNames method signature requires the example to cast the string "medrec:Type=JDBCConnectionPool,*" as an Object.
- Assigns the list of MBeans to a Set object and uses methods of the Set and Iterator interfaces to iterate through the list.
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 Using the MBeanServer Interface
import java.util.Iterator;
import java.util.Set;
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 javax.management.ObjectName;
import javax.management.QueryExp;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.RemoteMBeanServer;public class ListJDBCInfo {public static void main(String[] args) {
QueryExp query = null;
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");//Retrieving the MBeanServer interface
homeServer = home.getMBeanServer();//Retrieving a list of MBeans with object names that include
//"JDBCConnectionPool"
Set JDBCMBeans = homeServer.queryNames(new
ObjectName("mydomain:Type=JDBCConnectionPool,*"), query);
//where "query" could be any object that implements the JMX
//javax.managementQueryExpfor (Iterator itr = JDBCMBeans.iterator(); itr.hasNext(); ) {
ObjectName mbean = (ObjectName)itr.next();
System.out.println("Matches to the MBean query:" + mbean);
}
}catch(Exception e){
System.out.println(e);
}
}
}