Level: Intermediate James Kochuba (kochuba@us.ibm.com), Support Staff Engineer, IBM
09 Nov 2005 WebSphere® Extended Deployment (XD) provides autonomic capabilities -- dynamic clusters and health monitoring -- to enable WebSphere systems to adapt to changes in workload and health of the servers. However, WebSphere XD does not provide built in capability for logging the autonomic actions. This article shows you how to write a Java client that automatically logs the autonomic actions of WebSphere XD.
Introduction
WebSphere Extended Deployment (XD) provides autonomic capabilities -- dynamic clusters and health monitoring -- enabling WebSphere systems to adapt to changes in workload and health of the servers. However, the information about the actions it recommends and that it performs are transient; it does not provide built-in capability for logging the actions it takes, and thus does not allow auditing of those actions. This article shows you how to write a simple Java client that can perform logging.
WebSphere XD has three different modes of operation. The mode determines if the autonomic calculations for workload and health are enabled and whether the operator must execute the recommendation or whether it is executed automatically.
- Manual mode (only for dynamic clusters)
- No calculations are done, and no actions are performed.
- Supervised mode
- Calculations are made to determine how to maintain workload and health. Notifications of the calculated actions are sent to the deployment manager
process. Recommendations are not automatically executed, but are instead left up to the operator to perform. Messages are stored in the
deployment manager heap until process is recycled.
- Automatic mode
- Calculations are made to determine how to maintain workload and health, and the actions based on those calculations are automatically performed.
In WebSphere XD V5.1 no notifcations are created. In Websphere XD V6 notifications are sent and stored in deployment manager heap.
However, although, depending upon the mode, WebSphere XD does send notifcations based on its calculations, these notifications are transient. It does not provide built-in capability for auditing the autonomic actions. This article shows you how to create a Java client to automatically log the autonomic actions of WebSphere XD. You'll learn how to program a listener for the specific notification for auditing.
Note that in WebSphere XD V5.1, no notifications are sent in automatic mode; thus the client can only log notifications if WebSphere XD is in supervised mode. However, this is not good if the client really wants to automatically accept changes. Thus, the example in this article also shows you how a WebSphere XD V5.1 client can react to notifications, providing an automatic response while in supervised mode.
This article also provides a skeleton administrative client and custom service that can be easily modified for any WebSphere Application Server and WebSphere XD Management Bean (MBean) and explains how to compile and deploy them.
Developing a client to listen for, log, and accept autonomic task notifications
The Java client instance, which can be either an administrative client program or custom service, registers a listener for the websphere.taskmanagement.tasknew (Autonomic Task) event. The placement controller and health policies trigger this event. When this event occurs, the client creates a log entry for auditing. For WebSphere XD V5.1, it also accepts and acts on the notification.
The Java client must implement the NotificationListener class. Examples of what is required in such Java client can be found in the Information Center [1] or on developerWorks [2]. The client must:
- register a listener
- handle the event
This is described in the next two sections.
Register a listener
The Java client registers as a listener for websphere.taskmanagement.tasknew notifications to listen for the Autonomic Task notifications in the WebSphere XD environment. The following example shows how an object can register itself for these notifications, which are emitted from the TaskManagement MBean. The MBeans are the building blocks for WebSphere Application Server system administration and monitoring based on the Java Management Extensions (JMX) specification.
try
{
//Create an Object for the MBean search string we want to find.
//The * is used as a wildcard search allowing this to not be locked into a very specific MBean.
ObjectName query = new ObjectName("WebSphere:*");
//Create a filter object so this listener will only listen to specific MBean notifications, Thread_Hung.
NotificationFilterSupport filter = new NotificationFilterSupport();
//Adding the websphere.taskmanagement.tasknew notification to the filter.
filter.enableType("websphere.taskmanagement.tasknew");
//Adding a listener to multiple MBeans listening only for the filtered notifications.
//Note: adminService variable is the interface to the WebSphere administration functions
adminService.addNotificationListenerExtended(query, this, filter, null);
}
//Catch any exception thrown from the above actions and print to the system out to debug.
//Because this fails to properly add a notification to the interested MBean, we exit the program.
catch (Exception e)
{
//Print the error and stack information to the system out location for debug purposes.
System.out.println(e);
e.printStackTrace();
//Exit the program; we can pass any number noting the reason.
System.exit(-1);
}
|
The adminService variable is an Application Server API object; it interfaces with the WebSphere Application Server MBean, which is either an AdminClient object for the adminstrative client program or an AdminService object for the custom service. To listen to more event notifications, simply add more filter.enableType code lines.
Handle the event
The NotificationListener class defines the handleNotification method to handle JMX event notifications. This method then logs the notification. The following example is an implementation of handleNotification that logs and accepts the Autonomic Task.
The sample code initially parses the source of the notification to determine the task ID. The code first creates a String object (problemID), representing the MBean source information emitted in a notification that matched the filter. The user date string contains the task ID information (name and ID), where an equal sign separates name and ID inside the brakets, for example, {task.id=1458205428}. It retrieves the string and parses the taskID number, saving the results in the string called problemID.
public void handleNotification(Notification ntfyObj, Object handback)
{
String problemID = ntfyObj.getUserData().toString();
int idIndex = problemID.indexOf("=");
problemID = problemID.substring(idIndex+1);
int braketIndex = problemID.indexOf("}");
problemID = problemID.substring(0,braketIndex);
|
Next, the method creates an object for the TaskManagement MBean so that it can retrieve the task action information and accept the task.
ObjectName MBean = null;
try
{
//Create a String called query that will be used for a search string.
String query = "WebSphere:type=TaskManagement,*";
//Cast the query String into an ObjectName to meet the required input parameter type
ObjectName queryName = new ObjectName(query);
//Return all MBeans that meet the search string. Note the adminService object is interface
// into the WebSphere MBean server. This can be either an AdminClient or AdminService
// object based on the client program.
Set s = adminService.queryNames(queryName, null);
//Pull the MBean outside the Set object assuming the search string was specific enough to
// only get one MBean.
if (!s.isEmpty())
{
MBean = (ObjectName) s.iterator().next();
}
else
{
return;
}
}
//Catch any exception thrown from the above actions and print to the system out to debug.
catch (Exception e)
{
System.out.println(e);
e.printStackTrace();
System.exit(-1);
|
Next, it converts the data and logs the notification.
//Convert the problemID string into a Long, which is required for the MBean function to work.
Long problemNum = new Long(problemID);
//Create the object array noting all the parameters for the function this will invoke.
Object params[] = { problemNum };
//Create the signature string needed for the invoke command parameters. This notes the types
// of objects in the object array parameter.
String sign[] = {"long"};
//Log the autonomic task using the TaskManagement getActionPlan function for auditing.
// This function return a TaskActionPlan object, which has a toString function to output the
// specific task(s) the Autonomic Task will execute.
try
{
//Create a dummy object variable for the output of the function
Object displayTask = null;
//Execute the invoke command on the MBean to get the task information.
displayTask = adminService.invoke(MBean, "getActionPlan", params, sign);
//Log the task information to the System out for Auditing
System.out.println(displayTask.toString());
}
catch (Exception e)
{
e.printStackTrace();
} |
As output, this example sends the audit information in a raw form to the system standard out. The system out differs based on the client program; a Java client writes its output to the program's system out (for example, the command prompt) whereas the custom MBean writes its output this into the WebSphere server's SystemOut.log file.
In WebSphere XD V5.1, the client can include additional code to automatically accept the task:
//Accept the autonomic task using the TaskManagement Accept function.
try
{
//This function returns nothing, but executes the Autonomic Task actions.
adminService.invoke(MBean, "accept", param, sign);
}
catch (Exception e)
{
e.printStackTrace();
}
}
|
Note the above task acceptance will also work in WebSphere XD V6 in Supervised mode.
Notification output
Although the auditing program does not parse the output to make it user-friendly, the output is meaningful. Using the TaskManagement Mbean, the task steps to be executed by WebSphere XD are noted from the calculations. The "Operation", "MBean" and "Parameters" output will determine the exact action or actions needed to complete the Autonomic Task. Below is the output:
ID number = 1458205428
Got the object
Get Action Plan: 1458205428
Executor=WebSphere:type=HmmControllerMBean,*
TimeOut(ms)=600000
Number of Steps=2
Steps=
MBean=WebSphere:node=Node01,process=StockTrade_Node01,type=Server,*
Operation=stop
Signature={}
Parameters={}
MBean=WebSphere:node=Node01,type=NodeAgent,*
Operation=launchProcess
Signature={java.lang.String}
Parameters= {StockTrade_Node01}
|
The example output shows an Autonomic Task that came from the Health monitoring controls (Executor output). The task is a two-step process. The first action is to stop (Operation output) the StockTrade_Node01 server (MBean output). The second is for the node agent (MBean output) on node Node01 to start the StockTrade_Node01 server (Parameters output).
Compiling and running the sample client program
You can download a complete administrative client program that listens for the websphere.taskmanagement.tasknew notification and reacts by logging the actions for task accepting the task. Download ClientAuditXDMBean.java to the client machine. After changing the HostName and SoapPort to the appropriate values for your configuration, you can compile and run the client using the commands shown in this section. This section describes the steps for WebSphere XD V6. For information on WebSphere XD V5.1, see the WebSphere Application Server V5.1 Information Center [3].
To compile the client code for WebSphere XD V6, first set the environment variables JAVA_HOME and WAS_HOME to specify the appropriate locations, then issue the following command (all on one line):
%JAVA_HOME%\bin\javac -classpath
%WAS_HOME%\lib\admin.jar;%WAS_HOME%\lib\wsexception.jar;%WAS_HOME%\lib\management.jar;
%WAS_HOME%\lib\taskmanagement.jar ClientAuditXDMBean.java |
To run the client for WebSphere XD V6, again first make sure that the environment variables JAVA_HOME and WAS_HOME specify the appropriate locations, then issue the following command (all on one line):
%JAVA_HOME%\bin\java -Dwas.install.root=%WAS_HOME%
-Dwas.repository.root=%CONFIG_ROOT%
-Dcom.ibm.SOAP.ConfigURL=file:%USER_INSTALL_ROOT%/properties/soap.client.props
-Djava.ext.dirs=%WAS_EXT_DIRS%;%WAS_HOME%\java\jre\lib\ext
-classpath "." ClientAuditXDMBean |
The client stays in a wait state, listening for notifications and user input to end the program. The client outputs all the information about the notification. This client is not designed to work when global security is enabled, but you can easily modify the createAdminClient method to add the security parameters to the connectProps object. For more information about configuring the client connection with security, see the Information Center [1] under the "Application Server API" page; review the AdminClient article.
Compiling and running the sample custom service program
You can download a complete custom service program to listen for the new task notification and react by logging information about the task in a SystemOut.log. The program also can automatically accept the task. Download CustomServiceAuditXDMBean.java to your WebSphere XD machine. No modifications are required for this sample program; you can compile and run it using the commands shown in this section.
To compile the client code for WebSphere XD V6, first set the environment variables JAVA_HOME and WAS_HOME to specify the appropriate locations, then issue the following command (all on one line):
%JAVA_HOME%\bin\javac -classpath
%WAS_HOME%\lib\runtime.jar;%WAS_HOME%\lib\admin.jar;%WAS_HOME%\lib\wsexception.jar;
%WAS_HOME%\lib\management.jar;%WAS_HOME%\lib\taskmanagement.jar
CustomServiceAuditXDMBean.java |
Then package the class file in a JAR.
%JAVA_HOME%\bin\jar.exe cvf audit.jar . |
To install the custom service in WebSphere XD cell, start the Administration Console and follow these steps:
- Choose the server (dmgr) to add the custom service.
- Under the Additional Properties section, select Custom Services.
- Click New to create a new custom service.
- Fill out the appropriate information about the MBean (see Figure 1).
- Select Enable Startup so that the custom MBean starts every time the server starts.
- Fill in the Classname of this custom service:
com.ibm.support.CustomServiceAuditXDMBean
- Display Name is user defined and can be anything.
- Fill in Classpath with the location of the JAR file. This can be the absolute path or symbolic (as shown in the figure).
Figure 1. Specifying information about the MBean
The custom service needs to be running in the dmgr process to listen for all tasks. Also the custom service is not designed to work with Java 2 security enabled.
Conclusion
A Java client program to monitor Autonomic Task is the way to audit the autonomic actions built into WebSphere XD. The client developed in this article enables you to log actions for auditing. The skeletons can easily be redesigned to listen for any event notification, based on the filter design and query string, and react, based on handleNotification method implementation.
Downloads
Resources
About the author  | 
| | James Kochuba is currently a WebSphere Application Server Support Staff Engineer and the technical team leader for IBM support personnel whose focus on WebSphere Extended Deployment and WebSphere Application Server. This role requires focus on customer issues to help guide support engineers and customers alike towards problem source identification and ultimately problem resolution. |
Rate this page
| 
