Introduction

In Part 2 of this article series, we learned how WebSphere^TM Application Server V5 Systems Management has at its core a Java^TM Management Extentions (JMX) server that provides a standard interface to manage the application server. In Part 3, we will describe in detail how to handle notifications, with emphasis on using notifications to determine when servers are started and stopped.

Back to top

A WebSphere Server Manager

To show a real example of how notifications can be used, we present a Swing-based administrative client which allows you to start and stop servers, as well as monitor their current state. It also shows all the notifications which are being emitted from various parts of the system. We will first describe how to run the system, and in the following sections explain how it works. The source code can be obtained from the download section at the bottom of this article. (The program requires WebSphere Application Server V5.0.1 or later, and you must use the version of Java that ships with WebSphere.)

To run the program, download the servermanager.jar file in a location such as c:\temp , set your classpath as shown below, and start the WebSphereServerManager :

The three parameters after the program name ( WebSphereServerManager ) contain the information needed to connect to a standalone server (for a WebSphere Application Server Base installation) or a deployment manager (in a WebSphere Application Server Network Deployment installation):

1. The hostname to connect to (for example, localhost ).
2. The port to connect to (Using the RMI connector: 2809 for Base or 9809 for Network Deployment. Using the SOAP connector: 8880 for Base or 8879 for Network Deployment).
3. The connector type to use, RMI or SOAP ; RMI is recommended as explained below .

After the program is started, the first thing to do is add a server by right-clicking on the WebSphere node to bring up a pop-up menu. If running a standalone installation, select Add server and enter the name of the server you connected to (for example, server1 ). After you add the server, you should see that the current state of the server is RUNNING (Figure 1). On the top right pane, you will see the type of each notification which this server has received. Since there are no processes sending notifications to the server, it contains only those that have originated from the server. If you select one of the notifications, all the information from that notification is displayed in the bottom right pane.

In a standalone installation, notifications are not often emitted. To get a sample notification to be sent, use the wsadmin utility to enter these commands:

In a Network Deployment installation, instead of selecting Add server you would select Add cell and provide the name of your cell. From there you would pop-up the menu on the cell and select Add node and provide the name of your node. Finally, select Add server from the node and provide the name of your server (Figure 2). You should get three notifications every minute if you have not modified the default node synchronization interval.

You can also start and stop servers from the pop-up menu. This changes the state of the server as displayed in the server tree, and also shows all of the notifications which are emitted. Note that you can only start a managed process, since there is no MBean interface to start deployment managers, node agents, or unmanaged processes.

Back to top

Starting and stopping servers

Information on starting and stopping servers can be found in Part 2 . In the example code, the ServerManager class starts and stops a particular server. You can see that approximately the same code was used in Part 2 for the getNodeAgentMBean method. The code to launch the process uses an overloaded invokeLaunchProcess operation that accepts an Integer for the amount of time to wait until the server is launched. We pass zero (0) for this value because we will be using notifications to determine when the server is actually running; this ensures that the client does not become inactive while starting the server.

The invokeStop method stops the server by invoking the stop operation on the Server MBean:

To start the server, the launchProcess operation is invoked on the NodeAgent MBean, but to stop a server, you invoke the stop operation on the Server MBean you would like to stop. The ServerManager class can only start ManagedProcesses (there is no way to start other servers with JMX), but you can stop any type of server.

Back to top

Using notifications

The launchProcess operation can be performed synchronously or asynchronously, but the stop operation is always asynchronous. This leads to the problem of not knowing when the process is fully stopped. One way of finding out could be to periodically search for the Server MBean, and when it cannot be found, the process is stopped. However, we can solve this problem with event notifications.

When certain events occur in the system, notifications are emitted to all listeners. Listeners can be registered in the same process as the server or in a remote process on the same or different machine. Registering a listener on a remote process simply requires obtaining an AdminClient and calling the addNotificationListener method. The following is an example which would listen to all the error and warning messages from server1:

In the above code:

• Line 17 performs the listener registration. It accepts four parameters, the last two of which are optional. These parameters are initialized in the preceding lines.
• Lines 1-3 create an ObjectName for the RasLoggingService MBean. A notification is emitted from a particular MBean, called the source . In this case, we want to listen to notifications whose source is the RasLoggingService on server1. An AdminClient is initialized as described in Part 2 .
• Lines 5-9 create an implementation of the class NotificationListener , which has a single handleNotification method. This method is called when a notification is emitted. The first parameter is the Notification object which was emitted, and the second is the handback , an opaque object which can be used if some sort of context is needed. The exact handback object passed during listener registration is passed on each handleNotification call for the registered listener.
• Lines 11-13 create a standard implementation of the NotificationFilter interface, an optional parameter for listener registration. Only notifications which the filter allows are passed to the listener. The NotificationFilterSupport class allows you to filter notifications based on type ; in this case, only websphere.ras.fatal and websphere.ras.error notifications are accepted. The WebSphere-provided class NotificationConstants contains useful constants for notifications.
• Line 15 initializes the handback object, which is the same object passed on line 6. In this case we don't need a handback object, so we use null.

To register a notification listener in the server process, you could use a servlet and perform the same general steps as above. However, the AdminService class is used instead of an AdminClient.

Removing a listener involves a similar call:

Here we pass the same ObjectName and listener which we used to register the listener.

Back to top

Notification attributes

We have already mentioned two attributes that a notification contains: a source and type. Although these are by far the two most useful pieces of information, there are others. The following is a list of the attributes a notification contains; although you cannot access them directly as attributes, they all have Get methods:

Back to top

WebSphere Application Server notification enhancements

Extended Listener Registration

The standard JMX way to add listeners has limitations. One is that the MBean must be present on the system to add a listener to it. Another is that if you want to add a listener to multiple MBeans, you have to register multiple times. WebSphere Application Server provides additional registration methods which allow you to do both of these:

As you can see, the parameters passed on the registration are the same. However, the value you can pass as the name parameter is different; instead of passing a full ObjectName, you can pass a partial ObjectName which uses the same syntax as that in queryNames . So for the example above, instead of passing rasMBean into addNotificationListener , we could have directly passed the partial queryMBean ObjectName into addNotificationListenerExtended , saving the queryNames call.

The other advantage of the extended registration method is that it will add listeners to MBeans which do not yet exist. So if a listener was registered to a set of MBeans, additional MBeans added to that same set would have the listener automatically added to it. It follows that you could pass a partial ObjectName which does not resolve to anything yet to addNotificationListenerExtended , and when that MBean gets activated, you will immediately receive notifications; if this was passed to addNotificationListener , an InstanceNotFoundException would be thrown.

The listener removal method is slightly different from the standard remove method, in that it does not take an ObjectName . Instead, all MBeans which were added with that particular listener will be removed. The different API is to make it clear that you cannot add a listener to a set of MBeans, and then remove the listener from a subset of those MBeans.

It is important to be aware that the removeNotificationListenerExtended(NotificationListener) method will be deprecated in a future release. In its place is a remove that exactly matches the standard remove method (it accepts an ObjectName and NotificationListener). This allows you to add a listener on two sets of MBeans (with two addNotificationListenerExtended calls) and remove it from only one set. It does NOT, however, allow you to remove the listener from a subset of the MBeans you added it to; the ObjectName given on remove must be exactly the same as that given on add. In this way it is more consistent with the standard add/remove listener operations.

Notifications in a Network Deployment installation

By itself, an application server only emits notifications to listeners registered locally (another MBean, for example) and clients registered remotely, as described above. In a Network Deployment installation however, all notifications from the application server are also sent to the node agent on the same machine. In the same way, all notifications in the node agent are sent to the deployment manager. We say that notifications are "propagated to the upstream server", as illustrated in Figure 3; arrows represent notifications which flow to the upstream server. This is an incredibly useful addition, as it allows you to register a single notification listener with the deployment manager to get notifications from MBeans on remote servers.

In WebSphere Application Server Version 5.0.1, notifications are not actually propagated upstream unless a listener is added. So if there is no listener for a particular notification, it will not actually be propagated. There is no external difference between the notifications emitted in Versions 5.0 and 5.0.1, although network traffic is reduced in Version 5.0.1.

Back to top

Handling notifications

The WebSphere Server Monitor application presented in this article subscribes to all notifications in a particular server, cell or node. The purpose for this is to allow you to see all the notifications which are being emitted. This should not be done in a production cell, as it causes ALL notifications from ALL servers to be sent to the deployment manager. As nodes are added, this can begin to swamp your network with all the notifications flowing. However, for the purpose of our example it is useful to illustrate all the notifications emitted.

The ServerMonitor object is created when a cell, node, or server object is added to the tree. One of its purposes is to register for all notifications which occur on that cell, node, or server. It does this in the addListener method:

private void addListener() throws ConnectorException {
ac.addNotificationListenerExtended(getMBeansListenedTo(),
this, null, null);
}

private ObjectName getMBeansListenedTo() {
if (mbeansListenedTo == null) {
StringBuffer buf = new StringBuffer();
buf.append("WebSphere:*");
if (cellName != null) {
buf.append(",cell=");
buf.append(cellName);
}
if (nodeName != null) {
buf.append(",node=");
buf.append(nodeName);
}
if (serverName != null) {
buf.append(",process=");
buf.append(serverName);
}
try {
mbeansListenedTo = new ObjectName(buf.toString());
} catch (MalformedObjectNameException exc) {
// ignore
}
}
return mbeansListenedTo;
}

The main part of this code is simply to create the partial MBean ObjectName . If listening to a cell, only the cellName attribute will be set, and so we might listen to WebSphere:*,cell=mycell ; since there is always exactly one cell, this matches all notifications emitted from the system. If listening to a server, all attributes will be set, so we might listen to WebSphere:*,cell=mycell,node=mynode,process=server1 ; this will match all notifications emitted from server1 running in the mynode node. The listener registration itself is very simple, passing this as the NotificationListener . Which means that this object implements the handleNotification method:

All notifications simply get added to listModel , an instance of NotificationListModel . This class has three purposes:

1. Limit the number of notifications we save to 100.
2. Extend the javax.swing.DefaultListModel class to make the job of displaying notifications easy.
3. Wrapper each notification in a NotificationWrapper . The reason for this is that the toString implementation in the Notification class does not display the type of the notification, which is arguably the most important part. So we override that method with an implementation which returns the notification's type and the time at which we received the notification.

This class also provides a method toDetailedString which returns a String containing all the data in the notification:

public String toDetailedString() {
StringBuffer buf = new StringBuffer();
buf.append("type = " + n.getType() + "\n");
buf.append("message = " + n.getMessage() + "\n");
buf.append("source = " + n.getSource() + "\n");
buf.append("seqNum = " + Long.toString(n.getSequenceNumber()) + "\n");
buf.append("timeStamp = " + new Date(n.getTimeStamp()) + "\n");
buf.append("userData = " + n.getUserData() + "\n");

if (n.getUserData() instanceof MessageEvent) {
buf.append(" (MessageEvent = " +
((MessageEvent) n.getUserData()).
getLocalizedMessage(Locale.getDefault()) + ")\n");
}
return buf.toString();
}

Note that for websphere.ras notifications which contain a MessageEvent as the userData, we invoke the getLocalizedMessage simply to display a readable version of the actual notification data.

Back to top

Using notifications to monitor servers

We now have enough knowledge to be able to monitor servers. First, we describe what notifications are actually emitted when a server is started and stopped:

• When a server is starting, the Server MBean emits a j2ee.state.starting notification.
• When it is completely started, it emits a j2ee.state.running notification.
• When a stop operation is issued, a j2ee.state.stopping notification is emitted.
• When it is completely stopped, it emits a j2ee.state.stopped notification.

In a Network Deployment environment, the "parent" server emits certain notifications on behalf of the "child" server. When an application server (child) starts, the NodeAgent MBean (parent, running in the node agent process) usually emits a websphere.process.starting notification. It also emits websphere.process.running , websphere.process.stopping , and websphere.process.stopped notifications shortly after the application server emits the j2ee.state notifications. In the same way, the DeploymentManager MBean (running in the deployment manager process) emits websphere.process notifications when the node agent starts or stops. The userData attribute contains a Properties object which contains the name of the process started (key NotificationConstants.KEY_PROCESS_NAME ), and for the node agent, the name of the node (key NotificationConstants.KEY_NODE_NAME ). Table 1 shows the notifications which WebSphere Application Server emits (additional notifications might be added, so this may not be a complete list).

* These notifications are only used internally by WebSphere Application Server; they should not be used by other external software products

It was stated earlier that the websphere.process.starting notification is usually emitted. Whether this notification is emitted or not depends on how the server was started. If the launchProcess operation was used to start the process, the websphere.process.starting notification is always emitted. If the startServer command is used to start the process, the websphere.process.starting notification is not emitted. Since the only way to start the node agent is with the startNode command, a websphere.process.starting notification is never emitted from the DeploymentManager MBean.

The reason for sending these notifications becomes apparent when you think about timing issues. You cannot add a listener before a server is completely started. Only after it is running can you add a listener to that server, and at that point the j2ee.state.starting and running notifications have already been emitted. Similarly, if you have a listener already registered, you might receive a stopping or stopped notification, depending on how fast the server actually stops (remember notifications are asynchronous). By registering a listener on the upstream server, you can be assured that you will receive notification when a downstream server is started or stopped.

In the sample code, the StateMonitor class monitors when servers are started and stopped. To monitor a managed application server (in Network Deployment) or node agent, the class uses the websphere.process notifications, since they are more reliable than j2ee.state notifications. To monitor an unmanaged application server (Base) or deployment manager, it uses the j2ee.state notifications because websphere.process notifications are unavailable. Some interesting points:

• The determineCurrentState method determines if the server is currently running or stopped, based on the existence of the Server MBean: if it finds the MBean, then it is running; if not, then it is stopped. Note that if the server is not defined, it will still be considered stopped.
• The monitor Process_Type Process adds the listener to the appropriate MBean (the server if listening to j2ee.state notifications, or the upstream process MBean if listening to websphere.process notifications). We use the extended add method so that we can listen to a server even if it is currently stopped (in which case the MBean is not yet activated).
• Two methods are used to create the filter: createJ2EEStateFilter and createWebSphereProcessFilter . It is usually best to pass a filter during registration, even if the current implementation only emits a certain type of notification. This protects you from unknown notifications which could be implemented in the future, and that your program might not be able to handle. Note that we use the constants defined in NotificationConstants here.
• The handleNotification method delegates to two other methods, based on what type of process we are monitoring. The handleWebSphereProcessNotification method is noteworthy, in that since a particular ServerMonitor could receive a notification for a server it was not monitoring for, we need to decide if the notification is important based on the userData attribute. Only if the name (server name or node name) matches the server form we are monitoring do we continue and actually change state.

Back to top

The SOAP versus RMI Connector

At the beginning of this article, we suggested using the RMI connector to run the WebSphere Server Manager instead of the SOAP connector. This requires some explanation. The SOAP connector has the advantage of having a better chance of making it through a firewall (since it is HTTP traffic) than RMI/IIOP. If there is a firewall in your installation, you will need to use SOAP instead of RMI. However, you will generally receive notifications faster with RMI than with SOAP. This is because the RMI uses a "push" model while SOAP uses a "pull" model.

When the RMI connector is used, a remote object is created on the client side and on the stub passed to the server side. Whenever a notification is received on the server, it is almost immediately sent (or "pushed") to the client and handed to the registered listeners. Unfortunately, this is not allowed with SOAP, as HTTP is a request/response protocol. With SOAP, at regular intervals, the client requests any notifications from the server for this listener. If there are any, they are returned from (or "pulled" from) the server and then handed to the listeners. This occurs approximately every 20 seconds, but can be more frequent if a large number of notifications are being received.

Since notifications can take up to 20 seconds to be received when using the SOAP connector, it is recommended that the RMI connector be used to receive notifications, when possible. To see the actual difference in times, you can run the sample code with both the SOAP and RMI connector and compare the results. The time the notification is received on the client is displayed on the top right pane, and the time the notification was actually sent is displayed on the bottom right pane, as seen in Figures 1 and 2. By comparing these two values, you will get an idea of how long notifications take to be received.

Back to top

Emitting your own notifications

Notifications are always emitted from MBeans. This generally means that to send a notification, you would need to create your own MBean and register it with the MBeanServer. (Registering your own MBeans will be described in Part 4 of the article series.) However, there is a way to send notifications without actually writing an MBean. This is done using the NotificationService MBean which exists on each server.

The NotificationService MBean contains an operation which allows client processes to emit notifications. By invoking the emitNotification method, a client can specify the type of notification, and optionally a message and userData, to be sent by the NotificationService MBean. The source of the MBean cannot be specified; it is always the NotificationService MBean itself. The following code uses the emitNotification(String notificationType, String message) operation to emit a notification:

ObjectName queryMBean = new ObjectName("WebSphere:type=NotificationService,process=server1,*");

// ... initialize adminClient ...

ObjectName notifMBean = (ObjectName) adminClient.queryNames(queryMBean, null).iterator().next();

String notificationType = "mycompany.myresource.myevent";

String message = "An event from myresource has occurred";

Object[] params = new Object[] { notificationType, message };

String[] paramTypes = new String[] { "java.lang.String", "java.lang.String" };

adminClient.invoke(notifMBean, "emitNotification", params, paramTypes);

WebSphere Application Server uses this method internally to allow the admin console to display the status of addNode or removeNode commands. Each message which is displayed on the console is actually a notification emitted from the command.

Another operation on the NotificationService MBean is propagateNotifications . This is used internally by downstream servers to propagate notifications to upstream servers. It should not be used by other applications.

Back to top

Conclusion

In this article we learned about the WebSphere Application Server notification system, and how you can register to receive notifications of events which occur on your system. We also examined a program with which you can start and stop servers and monitor their progress, as well as view all the notifications sent through the system. With this knowledge, you are well on your way to being able to develop nearly any management application which exists outside a server. In Part 4, Leigh Williamson will describe how you can write your own MBeans to extend the WebSphere Application Server itself.

Back to top

Downloads

Name	Size	Download method
servermanager.jar	0.1 MB	FTP|HTTP
servermanager-src.jar	0.1 MB	FTP|HTTP

Information about download methods

Resources

• WebSphere Application Server V5 InfoCenter
  • WebSphere Application Server javadoc
  • JMX javadoc (from Tivoli's TMX4J JMX implementation)
  • WebSphere MBean 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
  
  
  

About the author

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• A WebSphere Server Manager
• Starting and stopping servers
• Using notifications
• Notification attributes
• WebSphere Application Server notification enhancements
• Handling notifications
• Using notifications to monitor servers
• The SOAP versus RMI Connector
• Emitting your own notifications
• Conclusion
• Downloads
• Resources
• 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

My developerWorks community

Dig deeper into WebSphere on developerWorks

Cloud computing for developers

Virtual workshop: Learn how to build a cloud infrastructure and develop/deploy cloud-based applications. (6-8 Apr 2010)

Special offers