|
|
|
|
|
|
| | | |
Accessing WebLogic Server MBeans
The following sections describe how to access WebLogic Server MBeans from a client application or management framework:
Overview
As described in The WebLogic Server Management System, two primary agent-level interfaces provide client access to MBeans: MBeanServer and MBeanHome.
BEA provides MBeanHome as a simple, strongly-typed interface for accessing MBeans from clients that are either internal or external to the WebLogic Server JVM. If your application requires pure JMX-compliant access to MBeans, you can also obtain the MBeanServer interface via MBeanHome.
This section describes the basic procedure for obtaining an MBeanHome and accessing WebLogic Server MBeans via the MBeanHome interface. See the JMX specification for more information about accessing MBeans via the MBean server interface.
Selecting the Client Interface to WebLogic Server MBeans
Each server in a domain contains an MBeanHome (and a corresponding MBeanServer), which hosts configuration and runtime MBeans on that server. In addition, the administration server has an administration MBeanHome that provides access to all MBeans in the entire domain. The particular interface that you choose to use in your application depends on:
MBeanHome Versus MBeanServer
The MBeanHome interface provides easy access to WebLogic Server MBeans. However, it does not provide access to user-defined MBeans that may be registered in the MBeanServer interface. If your application must access user-defined MBeans, it must do so using the MBeanServer interface.
You may also choose to use the javax.management.MBeanServer interface if your application must fully comply with the JMX specification. Note, however, that the MBeanHome interface provides a strongly-typed interface for accessing WebLogic MBeans, and is generally easier to use than MBeanServer.
Note: All examples in this chapter use MBeanHome as the primary method for accessing MBeans. For information on using MBeanServer, see the JMX specification.
Server MBeanHome Versus Administration MBeanHome
Applications can use individual server MBeanHome interfaces and/or the administration MBeanHome interface, depending which MBean(s) the application accesses.
If your application needs to manage administration MBeans, you must use the domain-wide MBeanHome interface on the administration server, because administration MBeans are not available via the MBeanHome interfaces of managed servers.
If your application will manage multiple WebLogic Server instances in a domain, it may be preferable to use the domain-wide MBeanHome interface. The domain-wide interface allows you to access MBeans from any WebLogic Server in the management domain, by filtering the JMX object names.
If your application manages only a single WebLogic Server instance in a domain, then you may want to obtain the local MBeanHome interface for that server, rather than the domain-wide 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 itself.
Obtaining an MBeanHome Using JNDI
The MBeanHome of any server can be obtained from the relevant server's JNDI tree by using the MbeanHome.LOCAL_JNDI_NAME constant.
The domain-wide administration MBeanHome is published in the administration server's JNDI tree at MBeanHome.ADMIN_JNDI_NAME.
The administration server also publishes an MBeanHome for each server in the domain in its JNDI tree. This MBeanHome is available from the JNDI tree of the administration server, and can be accessed using the MbeanHome.JNDI_NAME+"."+relevantServerName constant.
The javax.management.MBeanServer for an individual server's MBeanHome can be obtained by invoking the getMBeanServer() method on that MBeanHome. Note that the domain-wide MBeanHome does not have a corresponding javax.management.MBeanServer; calling getMBeanServer() on the administration MbeanHome returns the MBeanServer of the admninistration server.
Example: Looking Up MBeanHome from an External Client
The following example shows how an application running in a separate JVM would look up an MBeanHome interface on the administration server.
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 void findExternal(String host,
int port,
String password) {
String url = "t3://" + host +
":" + port;
String username = "system";
try {
Environment env = new Environment();
env.setProviderUrl(url);
env.setSecurityPrincipal(username);
env.setSecurityCredentials(password);
ctx = env.getInitialContext();
home = (MBeanHome)ctx.lookup(MBeanHome.JNDI_NAME + "." +
SERVER_NAME);
System.out.println(SERVER_NAME +
" MBeanHome found externally");
ctx.close();
} catch (AuthenticationException ae) {
System.out.println("Authentication Exception: " + ae);
} catch (CommunicationException ce) {
System.out.println("Communication Exception: " + ce);
} catch (NamingException ne) {
System.out.println("Naming Exception: " + ne);
}
}
Example: Looking Up 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 monitor), the JNDI lookup for the MBeanHome is simpler. The following example shows how an JSP running in the same JVM as the administration server would look up an MBeanHome.
...
public void findInternal() {
Environment env = new Environment();
try {
ctx = env.getInitialContext();
home = (MBeanHome)ctx.lookup(MBeanHome.JNDI_NAME + "." +
SERVER_NAME);
System.out.println(SERVER_NAME +
" MBeanHome found internally");
ctx.close();
} catch (NamingException ne) {
System.out.println("Naming Exception: " + ne);
}
}
Example: Obtaining MBeanServer from MBeanHome
For applications that need to interact directly with the MBeanServer interface, MBeanHome provides a simple method to obtain its associated MBeanServer.
...
home = (MBeanHome)ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
RemoteMBeanServer homeServer = (RemoteMBeanServer)home.getMBeanServer();
...
Using the Helper Class to Obtain MBeanHome Interfaces
WebLogic Server version 6.1 provides the weblogic.management.Helper class to further simplify the process of obtaining MBeanHome interfaces in an internal client. The Helper class provides a methods to obtain the server or administration MBeanHome.
For example, to obtain both the administration server and local server MBeanHome using the Helper class:
public void find(String host,
int port,
String password) {
String url = "t3://" + host +
":" + port;
try {
localHome = (MBeanHome)Helper.getMBeanHome("system",
password,
url,
SERVER_NAME);
adminHome = (MBeanHome)Helper.getAdminMBeanHome("system",
password,
url);
System.out.println("Local and Admin Homes " +
"found using the Helper class");
} catch (IllegalArgumentException iae) {
System.out.println("Illegal Argument Exception: " + iae);
}
}
Accessing MBeans from MBeanHome
After obtaining the MBeanHome, you can look up individual MBeans using the methods described in javax.management.MBeanHome. For example, to look up all MBeans in the administration MBeanHome and print their JMX object names:
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());
}
}
You can access individual MBeans by using the MBeanHome.getMBean() methods. getMBean() has several different method signatures, the simplest of which returns a WebLogicMBean with the given name and type in the default domain.
MBeanHome provides additional getter methods to obtain specific WebLogic Server MBean types. For example, to obtain the Server configuration MBean from the current domain, you can use the getConfigurationMBean() method:
String myBeanType = "ServerConfig";
ConfigurationMBean myServerMBean =
home.getConfigurationMBean(SERVER_NAME, myBeanType);
To obtain a runtime MBean, use the getRuntimeMBean() method. A runtime MBean is a local MBean that gives runtime information about WebLogic Server and application components. Unlike other MBeanHome methods, getRuntimeMBean() returns only runtime MBeans that reside on the current WebLogic Server. If you call MBeanHome.getRuntimeMBean()on the Administration Server, it does not return runtime MBeans from Managed Servers. For example, the following code fragment returns the JDBCConnectionPoolRuntime MBean from the current WebLogic Server:
String poolName = "requestConnectionPool";
JDBCConnectionPoolRuntimeMBean runtimeMBean =
(JDBCConnectionPoolRuntimeMBean)home.getRuntimeMBean(poolName,
"JDBCConnectionPoolRuntime");
See the Javadocs for weblogic.management.MBeanHome for information about each of the getter methods available in MBeanHome.
Registering Custom MBeans with MBeanServer
Because WebLogic Server management services are implemented using JMX, you can also create your own MBeans and register them with an MBean Server in a WebLogic Server installation. This allows you to leverage the WebLogic Server MBean Server implementation to host your own MBeans and make them available to internal and external clients.
Note that all custom MBeans must be registered and accessed using the JMX-compliant MBeanServer interface. You cannot use the MBeanHome interface for custom MBeans, as MBeanHome only makes WebLogic Server MBeans available to clients. Furthermore, you cannot use BEA utilities such as weblogic.Admin to access custom MBeans.
The example that follows shows a very basic MBean implementation and a client application that registers the MBean with the MBean Server on an administration server. Note, however, that this example does not show all of the requirements (for example, MBean exception handling) outlined in the JMX specification. For full details on implementing your own custom MBeans, please refer to the JMX specification.
Example Custom MBean
For the purposes of this example, the custom MBean consists of a skeleton interface requiring only a single method implementation:
public interface MyCustomMBean {
int getMyAttribute();
}
Example Client Application
The client application performs the following actions:
Note that many of the above actions, such as obtaining MBeanHome and MBeanServer, are discussed earlier in this section. Only the registration and attribute calls differ for MBeans, because these calls operate directly against the MBean Server interface (and are full JMX-compliant). Additional information appears within the Java comments.
import weblogic.management.MBeanHome;
import weblogic.management.Helper;
import weblogic.management.RemoteMBeanServer;
import javax.management.*;
import MyCustomMBean;
// The client class implements MyCustomMBean, and the main function obtains
// MBeanHome and MBeanServer; registers the MBean; accesses an attribute value;
// and unregisters itself.
public class MyCustom implements MyCustomMBean, java.io.Serializable {
public static void main(String[] args)
// An actual JMX client would handle appropriate exceptions at different points
// in the application. For clarity, this example client only throws exceptions.
throws Exception {
// The client obtains the MBeanHome of the administration server using the
// Helper class.
MBeanHome mbh = Helper.getMBeanHome("system",
"system_password","t3://localhost:7001","examplesserver");
// The client obtains the MBeanServer interface via MBeanHome.
RemoteMBeanServer mbs = mbh.getMBeanServer();
// To use JMX calls against the MBeanServer interface, the client must use
// ObjectNames.
ObjectName mbo = new ObjectName("user_Domain:Name=x");
// The client attempts to register the custom MBean with the MBeanServer.
try {
mbs.registerMBean((Object)new MyCustom(),mbo);
} catch(InstanceAlreadyExistsException i) {
System.out.println("MBean ("+mbo+") allready exists");
}
// The client obtains and prints the value of MyAttribute.
System.out.println("Value of MyAttribute of ("+mbo+")from MBeanServer = "+
mbs.getAttribute(mbo,"MyAttribute"));
// The custom MBean is unregistered.
mbs.unregisterMBean(mbo);
}
// The example client implements the MyCustomMBean interface's single method
// with prinhted output.
public int getMyAttribute() {
System.out.println("getMyAttribute invoked.");
return 999;
}
}
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|