© Copyright International Business Machines Corporation 2003. All rights reserved.

Introduction

IBM ® WebSphere® Application Server (hereafter called Application Server) Version 5.0 provides enhancements to scalability, reliability, Web services, J2EE 1.3 certification, and many other areas. Version 5.0 also provides a completely rewritten infrastructure for you to manage and administer your servers and applications. An open standards-based management framework, Java^TM Management Extensions (JMX) is at the core of the Version 5.0 management capabilities. New administration tool sets built for Version 5.0 take advantage of this framework. Also, you can use the Version 5.0 administration tool capabilities for your own custom administration programs.

This system administration series will discuss a variety of ways to use the Application Server 5.0 management features. Part 1 introduced the basic system administration concepts needed to understand 5.0 features. This included a discussion of the new JMX-based administrative architecture for Application Server 5.0 and the various tools available for administering an Application Server system. Part 2 explores the administrative client API, and discusses how to use it to develop your own custom administrative client program.

Back to top

Overview of JMX

Before you start to develop the sample administration client program, it is important that you familiarize yourself with JMX.

JMX is the Java standard for managing an application's resources. The management architecture defined by JMX is divided into three levels:

• The bottom level is management instrumentation. Each manageable resource is described by an interface that specifies the attributes it has, the operations it supports, and the notifications it sends. This resource is a managed bean (MBean).
• The middle level is the management agent. Each managed process contains a JMX agent that includes an MBean server, which provides a registry and access point for MBeans. Management clients must use the MBean server to access the registered MBeans.
• The top level of the architecture is identified, but undefined in the current level of the JMX specification. It is the distributed services level, and its role is to facilitate remote access to JMX agents. This task is accomplished through connectors, which provide a protocol-independent, location-transparent, client-side interface to the MBean server (for example, an RMI connector), or protocol adapters, which provide protocol-specific, server-side access to the MBean server (for example, an HTTP adapter).

For more details on programming with JMX, see the Related information section.

Back to top

JMX in WebSphere Application Server

JMX is at the core of Application Server's administration capabilities. The application server contains a JMX agent. All of the system components are instrumented as MBeans. Application Server's JMX agent supports two types of connectors, RMI/IIOP and SOAP/HTTP(S), which provides remote access to the server's resources. All of the administration tools included with Application Server use these JMX facilities to accomplish their functions.

From Part 1, recall that in a base Application Server installation, servers exist and are administered individually. An administrative client connects directly to the application server in this environment. Also, recall that in a Network Deployment installation, a hierarchical topology groups application servers within nodes, and groups nodes within a cell. Administrative servers exist at the node level (node agents) and at the cell level (the deployment manager), and act as aggregation points for the administrative services in the subordinate servers. MBeans in all servers on a node are visible through that node agent, and MBeans in all nodes are visible through the deployment manager. Therefore, by connecting to the deployment manager, you can invoke operations, get and set attributes, and receive notifications for any MBean in the cell. Application Server provides an AdminService class that reflects the standard JMX MBeanServer interface, and wraps the MBeanServer so that it takes part in implementing this distributed management functionality.

Back to top

Getting an AdminClient

Since you're writing a client program, you need a connection to the desired server and you need a means to invoke methods on remote MBeans. The AdminClient class provides these capabilities. When an AdminClient object is created, it provides a proxy to the remote AdminService object through one of the supported JMX connectors. As a proxy to the remote AdminService, the AdminClient also reflects the MBeanServer interface. However, the AdminClient does not include methods of the MBeanServer that are not applicable on the client side of the connection.

Use the following code to create an AdminClient object that is connected to a server:

Listing 1. Creating an AdminClient

Properties clientProps = new Properties(); 
connectProps.setProperty(AdminClient.CONNECTOR_TYPE,  
                         AdminClient.CONNECTOR_TYPE_SOAP); 
connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost"); 
connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8879"); 
 
AdminClient adminClient = null; 
try 
{ 
   adminClient = AdminClientFactory.createAdminClient(clientProps); 
} 
catch (ConnectorException e) 
{ 
   System.out.println("Exception creating admin client: " + e); 
}

First, set up a Properties object with the properties required to get to your desired server. In this case, you will use the SOAP connector to reach the server; for the connector type, use the value AdminClient.CONNECTOR_TYPE_SOAP. For simplicity, you will run the client program on the same machine as the server; use localhost for the host name. To access a remote host instead of a local host, simply use a network resolvable name for that host. The final property that you need to set is the port number on which the server's SOAP connector is listening. In a single server installation, the default port number for the application server's SOAP connector is 8880. In a Network Deployment installation, the default port number for the deployment manager's SOAP connector is 8879.

After the connection properties are set, you can use the AdminClientFactory class and the Properties object to create an AdminClient object that is connected to your chosen server. Depending on factors such as your desired protocol and security environment, you might need to set other properties. For more detailed information about the AdminClient interface and additional creation examples, refer to the AdminClient javadoc.

Back to top

Accessing MBeans

Once you obtain an AdminClient instance, you can use it to access managed resources in the application and administration servers. Each managed resource registers an MBean with the MBeanServer in its process. In JMX, management programs do not directly access MBeans. Instead, they must direct requests to the MBeanServer, and reference MBeans by name. An MBean name takes the form of an ObjectName, which consists of a domain name followed by an unordered list of one or more key properties. The syntax looks like this:

[domainName]:property=value[,property=value]*

The domain name provides a partitioning of the ObjectName namespace within the JMX agent. It is optional; if it is not present, then the MBean server will use a default domain name. For WebSphere Application Server, the domain name is conveniently WebSphere.

A key property is a name-value pair. An ObjectName's list of key properties can consist of any number of key properties, but at least one needs to exist. The ordering of key properties in the list does not matter. The following table shows the most important key property names that WebSphere Application Server administration uses:

Table 1. ObjectName key property names in WebSphere Application Server

Some MBeans in Application Server use additional key properties. However, the above table contains the most important, minimally required key properties. An MBean without these key properties can be registered with the MBeanServer in an Application Server process, but such an MBean cannot participate in the distributed enhancements that Application Server adds (for example, request routing, distributed event notification, etc.).

If you know the complete set of key properties for an ObjectName, then you can use it to find the MBean it identifies. However, it is usually more practical and convenient to find MBeans without having to know all of their key properties. You can do this by using a wildcard character, * , for any key properties that you do not need to match. The following table provides some examples of ObjectNames with wildcard key properties that match single or multiple MBeans.

Table 2. Example of ObjectNames with wildcard key properties

The following example shows how to find the MBean for the NodeAgent of the node named MyNode:

Listing 2. Finding a node agent MBean

String nodeName = "MyNode"; 
ObjectName queryName = new ObjectName ("WebSphere:*,type=NodeAgent,node=" + nodeName); 
ObjectName nodeAgent = null; 
Set s = adminClient.queryNames(queryName, null); 
if (!s.isEmpty()) 
   nodeAgent = (ObjectName)s.iterator().next(); 
else 
   System.out.println("Node agent MBean was not found");

Begin by building an ObjectName with a query string that specifies the key properties of type and node. By using a wildcard for the remaining key properties, this pattern will match the ObjectNames for all MBeans of type NodeAgent on node MyNode. Since there is only one node agent per node, this is sufficient to identify the MBean that you want. Next, give this ObjectName to the queryNames method of AdminClient, which will perform the remote call to the AdminService to obtain the set of MBean ObjectNames that match the query. (The null second parameter to this method is a query expression (QueryExp) object that you can use as an additional query over the MBeans that match the ObjectName pattern in the first parameter.) Finally, use the set's iterator to get the first (and, in this case, only) element which is the node agent's MBean ObjectName.

So now that you have access to an MBean what can you do?

Back to top

Using MBeans

What a specific MBean lets you do depends on the management interface that it exposes. It may declare attributes that you can get or set. It may declare operations that you can invoke. It may declare notifications for which you can register listeners. For the MBeans provided by Application Server, you can find information about the interfaces they support in the MBean javadoc. This javadoc is also installed with Application Server in the \web subdirectory under the product installation root directory.

Invoking an operation

The following example invokes one of the operations available on the NodeAgent MBean that you located above. It starts the application server named MyServer:

Listing 3. Invoking an MBean operation

String opName = "launchProcess"; 
String signature[] = { "java.lang.String" }; 
Object params[] = { "MyServer" }; 
try 
{ 
   adminClient.invoke(nodeAgent, opName, params, signature); 
} 
catch (Exception e) 
{ 
   System.out.println("Exception invoking launchProcess: " + e); 
}

The AdminClient.invoke method is a generic means of invoking any operation on any MBean. The parameters are:

• the ObjectName of the target MBean
• the name of the operation
• an Object array that contains the operation parameters
• and a String array that contains the operation signature

In this case, the launchProcess operation has a single parameter: a string that identifies the server to start.

The invoke method returns an Object instance which the calling code could then cast to the correct return type for the invoked operation. The launchProcess operation is declared void so you can ignore the return value in this example.

Registering as an event notification listener

Besides managing resources, JMX also supports monitoring for specific administrative events. Certain events produce notifications, for example, when a server starts. Management applications might declare their interest in these events by registering as a notification listener. WebSphere Application Server provides a full implementation of the JMX notification model, and provides additional function so that you can receive notifications in a distributed environment. For a list of the notifications that the WebSphere Application Server MBeans emit, refer to the NotificationConstants class in the Javadoc. The following is an example of how an object can register itself for event notifications emitted from your node agent MBean:

Listing 4. Registering a notification listener

adminClient.addNotificationListener(nodeAgent, this, null, null);

In this example, the first parameter is the ObjectName for the node agent MBean. The second parameter identifies the listener object, which must implement the NotificationListener interface. In this case, the calling object is the listener. The third parameter is a filter that you can use to indicate which notifications you want to receive. When you leave this value as null, you will receive all notifications from this MBean. The final parameter is a handback object that you can set JMX to return to you when it emits a notification.

If your MBean is located on another server in the cell, you can still receive its notifications even though your administrative client program might be connected to the deployment manager server. This is because all notifications flow to the upstream server. For example, a notification from an application server will first flow to the local node agent and from there to the deployment manager.

Another enhanced feature that Application Server provides is the ability to register as a notification listener of multiple MBeans with one call. This is done via the addNotificationListenerExtended method of AdminClient, an extension of the standard JMX addNotificationListener method. This extension method even lets you register for MBeans which are not currently active. This is important in situations where you would like to monitor events from resources that can be stopped and restarted during the lifetime of your administrative client program.

Handling event notifications

Objects receive JMX event notifications via the handleNotification method, which is defined by the NotificationListener interface and which any event receiver must implement. The following example is an implementation of handleNotification that reports the notifications that it receives:

Listing 5. Receiving a notification

public void handleNotification(Notification n, Object handback) 
{ 
   System.out.println("******************************************"); 
   System.out.println("* Notification received at "  
      + new Date().toString()); 
   System.out.println("* type = " + n.getType()); 
   System.out.println("* message = " + n.getMessage()); 
   System.out.println("* source = " + n.getSource()); 
   System.out.println("* seqNum = "  
      + Long.toString(n.getSequenceNumber())); 
   System.out.println("* timeStamp = " + new Date(n.getTimeStamp())); 
   System.out.println("* userData = " + n.getUserData()); 
   System.out.println("*******************************************"); 
}

Back to top

Putting it all together

Building the program

Now you are ready to build the administrative client program. To do this, you simply need to to run javac and set the classpath to pick up the necessary JMX and WebSphere Application Server JAR files. The JAR files typically consist of jmxc.jar, admin.jar, and wsexception.jar. If Application Server is installed in w:\DeploymentManager, then the javac command would look as follows:

javac -classpath w:\DeploymentManager\lib\admin.jar; 
   w:\DeploymentManager\lib\wsexception.jar; 
   w:\DeploymentManager\lib\jmxc.jar AdminClientExample.java

See the download ZIP file for a complete administrative client program that contains all of the examples from this article.

Running the program

Run your administrative client program by setting up the run-time environment so that the program can find all of the necessary requirements. Many of the batch or script files in the \bin directory under the Application Server installation root perform a similar function. The code snippet below is an example of a Windows® batch file that runs an administrative client program named AdminClientExample; it is packaged in a JAR file of the same name. It uses the setupCmdLine.bat script that is installed in the Application Server \bin directory to set up the necessary environment for the process:

Listing 6. Launching an admin client program

@echo off 
 
call "%~dp0setupCmdLine.bat" 
 
"%JAVA_HOME%\bin\java" -classpath "%WAS_CLASSPATH%; 
   %WAS_HOME%\lib\admin.jar;%WAS_HOME%\lib\wasjmx.jar; 
   c:\test\AdminClientExample.jar" AdminClientExample %* 

Back to top

Conclusion

Administration features in WebSphere Application Server have been greatly enhanced in Version 5.0. JMX provides the foundation for these enhancements. The code samples presented in this article demonstrate how to get started with using JMX in Application Server from the client side. To continue exploring WebSphere Application Server and JMX, check out the URLs below and stay tuned for the remaining parts in this series.

Back to top

Related information

• WebSphere Application Server V5 InfoCenter
• WebSphere Application Server javadoc
• Java Management Extensions home page
• Tivoli TMX4J JMX implementation
• JMX articles:
• Superior App Management with JMX
• From black boxes to enterprises: Management, JMX 1.1 style
• JMX books:
• Java and JMX: Building Manageable Systems
• JMX: Managing J2EE with Java Management Extensions
• Java Management Extensions

Top of page

Back to top

Download

Name	Size	Download method
AdminClientExample.zip	2KB	FTP|HTTP

Information about download methods

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Overview of JMX
• JMX in WebSphere Application Server
• Getting an AdminClient
• Accessing MBeans
• Using MBeans
• Putting it all together
• Conclusion
• Related information
• Download
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers