Accessing MBeans

Once you obtain a home interface, there are several ways to access the underlying MBean Server. The first approach is to use the MBeanHome interface to retrieve an instance of javax.management.MBeanServer, the standard JMX interface for interacting with an MBean Server. It provides a generic way for accessing the attributes and invoking the operations exposed by an MBean. The onus is on you to supply the correct number of parameters, of the correct type, when you use an MBeanServer instance to issue method calls to an MBean.

The second approach is to use a proprietary type-safe interface, which is implemented as a wrapper around the MBeanServer interface. At the cost of portability, you gain very simplified and compact access to MBeans and their attributes and operations. WebLogic's Administration Tool provides another nonprogrammatic approach to accessing MBeans. In addition, the new WLShell tool provides a shell environment for accessing and manipulating MBeans on a particular WebLogic instance.

20.3.1 Naming of MBeans

Before you can use the MBeanServer interface to locate MBeans, you need to understand how WebLogic names its MBeans. Each MBean hosted by an MBean Server is uniquely named, and every MBean name is constructed using an instance of the JMX ObjectName class. WebLogic uses instances of the WebLogicObjectName class, which extends ObjectName to carry additional information. When printed, the name of an MBean follows this format:

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

So, a name contains a domain name, followed by an unordered list of property/value pairs, explained here:

• A domain name identifies the domain to which the MBean belongs. For most MBeans, this is just the name of the WebLogic administration domain. For Security MBeans, the name of the domain must be Security.
• A Name property identifies the name of the resource associated with the MBean. For instance, if you've created a JMS server with the name My JMS server, the name used to locate the associated MBean may use the Name=My JMS Server property. Note that this property does not represent the JNDI name to which the resource is bound.
• A Type property points to the interface implemented by the MBean's class. It also indicates whether the MBean is an Administration, Local Configuration, or Runtime MBean.
• A Location property identifies the name of the server instance on which the MBean is running. You don't need to specify this property when locating Administration MBeans.
• MBeans that are in a parent-child relationship with other MBeans use an additional TypeOfParentMBean=NameOfParentMBean property/value pair to express this relationship.

For example, if you defined a data source in the myClusterDomain domain, the name of the associated Administration MBean is:

 myClusterDomain:Name=My Data Source,Type=JDBCDataSource

To construct a name object representing such an MBean, use the three-argument WebLogicObjectName constructor, which takes the name, the type, and the domain of the object:

WebLogicObjectName oname = new WebLogicObjectName("My Data Source",
 "JDBCDataSource", "myClusterDomain");

20.3.1.1 Determining MBean type

Every MBean within WebLogic is an instance of a class that implements one of the weblogic.management.configuration or weblogic.management.runtime interfaces. When constructing the MBean's name, the value for the Type property that you need to supply is determined by a mangling of the name of the interface implementing either of the aforementioned interfaces.

For WebLogic's Runtime MBeans, the value for the Type property corresponds to the name of the MBean interface, but without the MBean suffix. So, for the ServletRuntimeMBean, the MBean's name must include the name/value pair Type=ServletRuntime. Similarly, for the JDBCDataSourceMBean, you must specify Type=JDBCDataSource.

For WebLogic's Configuration MBeans, the value for the Type property that you supply indicates whether the name refers to an Administration or a Local Configuration MBean. For an Administration MBean, the type corresponds to the name of the MBean's interface but, as before, without the MBean suffix. For a Local Configuration MBean, its type is obtained by appending Config to the type of its Administration MBean counterpart. For example, the MBean name for a ServerMBean on the Administration Server must use the name/value pair Type=Server. If you need to refer to a Local Configuration MBean, you must specify Type=ServerConfig.

Let's assume that our myClusterDomain domain has an Administration Server and two Managed Servers, ServerA and ServerB. If a data source is targeted to both Managed Servers, the names of the Local Configuration MBeans associated with the data source will be:

myClusterDomain:Location=ServerA,Name=My Data Source,Type=JDBCDataSourceConfig
myClusterDomain:Location=ServerB,Name=My Data Source,Type=JDBCDataSourceConfig

To construct a name object representing such an MBean, which has a location, use the four-argument WebLogicObjectName constructor, which takes the object's name, type, domain, and location:

WebLogicObjectName oname = new WebLogicObjectName("My Data Source",
 "JDBCDataSourceConfig", "myClusterDomain", "ServerA");

20.3.1.2 Determining parent-child relationships

Except for the DomainMBean, all MBeans inherit either directly or indirectly from the DomainMBean. Sometimes you need to explicitly state this inheritance when constructing the MBean's name in order to uniquely identify it. For instance, consider the LogMBean, which represents the configuration of a log file. Log configuration can occur at several levels. At the domain level, you could set up the domain log configuration. At a server instance level, you could adjust the server log's configuration. Different instances of the LogMBean represent the configuration at different levels. You can differentiate between these configuration MBeans by indicating the fact that the server log Configuration MBean is a child of the server Configuration MBean running within the domain. The domain log Configuration MBean is an implicit child of DomainMBean and not a child of the server Configuration MBean.

To emphasize this point, let's take a look at an excerpt from the domain's config.xml configuration file:

Here we can clearly see the log configuration for the domain and the two Managed Servers within the domain. The domain LogMBean does not need to express a relationship with the domain. It is unambiguous. The server's LogMBean instance does have to express a parent-child relationship. In this case, the parent is the ServerMBean instance associated with its Managed Server. The relationship between the Log MBeans for the domain and for the Administration Server is expressed in Figure 20-3.

Figure 20-3. Relationships in the MBean hierarchy

There are a two additional points to note from this figure.

• The child MBeans use the same name as the parent MBean, unless there are multiple children of the same type. Thus, the name of the domain's LogMBean is myDomain because the name of the parent MBean also is myDomain.
• The server's LogMBean is in a parent-child relationship, so its name also must include a TypeOfParentMBean=NameOfParentMBean property/value. In this case, we have an additional Server=Admin part to the LogMBean's name so that we can identify the parent MBean.

To construct a name object representing such an MBean, first create one for the parent and then another for the child. As shown in Figure 20-3, the parent MBean is of type ServerMBean. Constructing the name object for the parent uses the constructor that we have seen before:

WebLogicObjectName parent = 
 new WebLogicObjectName("Admin", "Server", "myDomain");

Now, to construct the name of the child, we use the constructor that additionally takes the name of a parent. This time, of course, the type of the MBean is Log:

WebLogicObjectName childlog = 
 new WebLogicObjectName("Admin", "Log", "myDomain", parent);

Though the MBean naming schema may seem tedious, it often makes it a lot easier to find the MBean you want either programmatically or by using the Administration Tool.

20.3.2 Using the Administration Tool

The weblogic.Admin tool can be used to view and manipulate JMX data. You can use this tool for quick, nonprogrammatic access to the MBeans. WebLogic's Administration Tool supports three options pertinent to manipulating MBeans: the GET, SET, and INVOKE options. The GET option can be used to retrieve attribute values of an MBean, the SET to modify attribute values, and the INVOKE to invoke any operation on the MBean. Each command provides two ways in which you can identify the MBean on which to operate. The -mbean argument requires you to specify the name of the MBean, and the -type option requires you to specify the MBean's type.

The following example shows how to use the GET option to retrieve the attribute values of a named DataSource MBean:

java weblogic.Admin -url http://10.0.10.10:7001 -username system -password pssst
 GET -pretty -mbean 
 "myClusterDomain:Location=ServerA,Name=My DataSource,
Type=JDBCDataSourceConfig"

This outputs the full list of attributes and values:

MBeanName: "myClusterDomain:Location=ServerA,Name=My Data Source,
 Type=JDBCDataSourceConfig"
 CachingDisabled: true
 ConnectionWaitPeriod: 1
 DeploymentOrder: 1000
 JNDIName: DS
 Name: MyJDBC Data Source
 Notes:
 ObjectName: MyJDBC Data Source
 PoolName: MyJDBCTool
 Registered: false
 RowPrefetchEnabled: false
 RowPrefetchSize: 48
 StreamChunkSize: 256
 Targets: ServerB,MyCluster
 Type: JDBCDataSourceConfig
 WaitForConnectionEnabled: false

The tool can also help you determine the name of an MBean if you know its type only. The following example prints out the configuration settings encapsulated by the Log MBeans, which we explored in the previous section:

java weblogic.Admin -url http://10.0.10.10:7001 -username system -password pssst
 GET -pretty -type Log

In our example domain, which consists of an Administration Server and two Managed Servers, this command outputs the settings for four Configuration Log MBeans, one for the domain Log MBean and one for each Log MBean associated with the servers.

20.3.3 Using WLShell

BEA's dev2dev web site contains several tools for manipulating and viewing MBean data. The most flexible is WLShell, a powerful shell environment that lets you script actions to create, view, monitor, or modify MBeans. You will need to download and install the tool before you can use it. The latest version, together with many useful scripts, can be obtained from http://www.wlshell.com/.

After starting the tool, you will be presented with a command prompt that allows you to enter commands using the shell's scripting language. WLShell's scripting language uses a filesystem analogy, whereby directories correspond to MBeans. In this analogy, creating a new directory is akin to creating a new MBean. It also provides the familiar get, set, and invoke commands on MBeans, as well as flow control and various other features. The following script illustrates these concepts. It creates a new connection pool, configures the relevant attributes of the pool, and assigns it to a server:

connect 10.0.10.10:7001 system password

targetServer = /Server/MyServer

mkdir /JDBCConnectionPool/MyJDBCTool
cd /JDBCConnectionPool/MyJDBCTool
set DriverName "com.microsoft.jdbcx.sqlserver.SQLServerDataSource"
set InitialCapacity 5
set MaxCapacity 10
set PreparedStatementCacheSize 15
set Properties (Properties) "user=sa;url=jdbc:microsoft:sqlserver://;password=pw;
PortNumber=143;SelectMethod=cur
sor;ServerName=10.0.10.10;dataSourceName=lsiPool;DatabaseName=Galactica"
set SupportsLocalTransaction true
set TestConnectionsOnRelease false
set URL "jdbc:microsoft:sqlserver://"
invoke addTarget $targetServer
cd /

The following script retrieves a few MBean attribute values and then invokes the stop operation on the Server MBean:

get -r ServerRuntime/myserver/State
get JTARuntime/JTARuntime/TransactionCommittedTotalCount
invoke Server/myserver/stop

The tool can also be used with a graphical MBean explorer. To invoke the Explorer, use the explore command in the shell. Figure 20-4 illustrates the Explorer window, showing the MBean structure together with the attributes and values for a selected JMS server.

Figure 20-4. WLShell's Explorer window

A great feature of the tool is its ability to reverse-engineer a domain's config.xml file. This creates a script file that reconstructs the domain's configuration. For any JMX-related work in WebLogic, we recommend that you use this tool because it is far more convenient than the weblogic.Admin tool, and its scripting language lets you create complex scripts for monitoring and configuring WebLogic resources.

20.3.4 Standard MBean Access

A typical JMX client will use the generic methods to interact with an MBean Server and the MBeans it hosts. As we mentioned earlier, an MBeanServer instance is the primary point of contact with an MBean Server. Once you've obtained an Administration or Local home, you can invoke the getMBeanServer( ) method on the MBean home object to retrieve the MBeanServer. Subsequent interaction with the MBeanServer follows the JMX specification.

The following example locates all Log MBean instances and prints out the log filenames:

MBeanServer mbs = adminHome.getMBeanServer( );
Set s = mbs.queryMBeans(new ObjectName("myClusterDomain:*,Type=Log"), null);
for (Iterator i=s.iterator( );i.hasNext( );) {
 Object o = i.next( );
 ObjectInstance m = (ObjectInstance) o;
 System.err.println(mbs.getAttribute(m.getObjectName( ),"FileName"));
}

Here, we've used the queryMBeans( ) method to find all MBeans of interest, in this instance all Log MBeans within myClusterDomain. Once we've acquired the set of desired MBeans, we can iterate over the collection and use the getAttribute( ) method to read the FileName property of each Log MBean. You also can use the setAttribute( ) method to set attributes on the Log MBean, or the invoke( ) method to invoke an operation on the Log MBean.

If your code needs to run on other J2EE platforms, or if it needs to interact with non-WebLogic MBeans, we recommend that you use this approach, which adheres to standard JMX conventions.

20.3.5 WebLogic MBean Access

WebLogic provides a proprietary, type-safe layer over the standard MBeanServer interface. Instead of obtaining a reference to the MBeanServer instance, you can directly use the MBean home to find or retrieve an MBean. If you know the MBean's name, you can use the getMBean( ) method to retrieve the MBean and cast the returned object to the appropriate type, as specified in WebLogic's API documentation. You then can directly use the methods exposed by WebLogic's MBean interface to query or manipulate the MBean. The following code locates the MBean corresponding to a data source deployed to ServerA within myClusterDomain and prints out its JNDI name and the name of its associated connection pool:

WebLogicObjectName name = new WebLogicObjectName(
 "MyJDBC Data Source","JDBCDataSourceConfig",
 "myClusterDomain", "ServerA");
JDBCDataSourceMBean pf = (JDBCDataSourceMBean) localHomeA.getMBean(name);
System.err.println(pf.getJNDIName( ));
System.err.println(pf.getPoolName( ));

Notice how the MBean's name is specified using a WebLogicObjectName instance. The JDBCDataSourceMBean interface (and any WebLogic-specific Configuration or Runtime MBeans) explicitly exposes all the necessary attributes and allowed operations. In general, the MBean's interface will expose getXXX( ) and setXXX( ) methods to read and write each MBean attribute and sensible names for each allowed operation on the target resource or service. Thus, WebLogic-specific MBeans give you a straightforward, type-safe way of exploring MBeans.

If you don't know the MBean's name, you still can query the MBean home for all MBeans using the getAllMBeans( ) method and then operate on the one(s) you want. The following code prints out the JNDI name for all data sources, though it's rather inefficient:

Set s = adminHome.getAllMBeans( );
for (Iterator i=s.iterator( );i.hasNext( );) {
 WebLogicMBean o = (WebLogicMBean) i.next( );
 if (o instanceof JDBCDataSourceMBean) {
 JDBCDataSourceMBean p = (JDBCDataSourceMBean)o;
 System.err.println(p.getJNDIName( ));
 }
}

Alternatively, you can query the home interface for all MBeans of a particular type directly using the getMBeansByType( ) method and instantly filter out unwanted MBeans. The following code sample shows how to query the MBean home for all data source Configuration MBeans and iterate over the result:

Set s = adminHome.getMBeansByType("JDBCDataSourceConfig");
for (Iterator i=s.iterator( );i.hasNext( );) {
 JDBCDataSourceMBean p = (JDBCDataSourceMBean)i.next( );
 System.err.println(p.getJNDIName( ));
}

If your JMX client needs to run on other J2EE platforms or access non-WebLogic MBeans that you have developed and incorporated into WebLogic, you should use the standard MBean access methods and not this WebLogic-specific type-safe approach.