bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Programming WebLogic Management Services with JMX > Accessing WebLogic Server MBeans |
Programming WebLogic Management Services with JMX |
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
The main steps for accessing MBeans in WebLogic Server are as follows:
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.
Determining Which Interfaces to Use
When accessing MBeans, you must make two choices about which interfaces you use:
The following table lists typical considerations for determining whether to use the local MBeanHome interface or the Administration MBeanHome 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.
This section contains the following subsections:
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 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:
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:
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.
Supply one of the following values for the name argument depending on which MBeanHome interface you are retrieving:
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
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
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.
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. |
|
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. |
|
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. |
|
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