Delivering notification with JMX

In the third article of this JMX series (part 1, part 2), we will look at how we can add JMX notifications into our JMX enabled Notepad application. JMX notifications can be used to inform users about an application fault, if the application has reached or exceeded a resource usage limit, or if the state of the application has changed.

We will continue with our Notepad example from the previous article by adding notification support to our Notepad MBean. To illustrate how to implement JMX notifications, we will add the support of "phrase matching". A "phrase matched" notification is delivered whenever a certain phrase is typed into a document. The phrase is set by the phrase property in our MBean.

Implementing JMX notification
A notification consists of two parts:

1. The notification event; the event will hold information about what we are interested in.
2. The source of the event which will be our MBean.

The notification object
We will implement our "phrase matching" notification by creating a notification object. All notification objects are a subclass of Notification. The management package in JDK 6 has some predefined notifications like AttributeChangeNotification, RelationNotification and TimerNotification. A typical notification object holds the following information:

• source of the MBean that generated the notification
• notification type expressed in dotted notation, similar to those used for naming Java properties. An example would be "my.mbean.notification"
• sequence number
• the time when the event occurs

As you can see it is quite simple. You can add additional methods in MatchNotification if you want the object to hold extra information like the sentence in which the phrase occurs.

Notification support
We will now need to modify our NotepadManagement class to support broadcasting notifications. To do this, we subclass NotificationBroadcasterSupport. The subclass will have to override the getNotificationInfo method; this returns an array of notifications that may be sent to the NotepadManagement MBean. Here is how the getNotificationInfo looks like in our scenerio:

Note that each notification information contains:

1. the type of notification
2. fully qualified classname of the notification object viz. MatchNotification in our case
3. a user friendly name of the notification

If an MBean generates more than one notification, then all of these notifications must be returned by getNotificationInfo(). For our convenience, we will add a method called notifyMatchFound to NotepadManagement. This method uses the sendNotification method from NotificationBroadcasterSupport class to notify all registered listeners. notifyMatchFound is implemented as follows:

Generating notifications
We are now ready to broadcast notification. To catch a monitored phrase, we implement the KeyListener. As the document is typed, we match the current phrase that is formed. If the phrase matches our monitored phrase, we will notify all listeners that we have found a match. The following code snippet shows this:

Subscribing to notifications
We are now ready to test the notification that we have just added into Notepad.

1. Start the Notepad application
2. Start jconsole and attach jconsole to the running instance of Notepad. See this article if you do not know how to. However jconsole has to be started with access to the Notepad class like so

for Solaris/Linux
jconsole -J-Djava.class.path=$JAVA_HOME/lib/jconsole.jar: $JAVA_HOME/lib/tools.jar:./classes:.

for Windows
jconsole -J-Djava.class.path=%JAVA_HOME%\lib\jconsole.jar;%JAVA_HOME%\
lib\tools.jar;.\classes;.

The reason is that when jconsole receives the MatchNotification, jconsole needs to have access to MatchNotification class file. So we need to include that in jconsole's classpath.

3. Open the Notepad MBean under the MBean tab and select Attributes. Enter a string in the 'Value' column of the 'Phrase' attribute. In the following diagram we have entered the string 'hello'.

Click to enlarge

4. Select the 'Notifications' node and click on 'Subscribe'. You will notice a zero (0) now appears beside the notification node. This number indicates the number of notifications that jconsole has received. So far we have not received any.

Click to enlarge
If you expand the 'Notifications' node, you will see all the notifications that are generated by the Notepad MBean. Ours have only MatchNotification listed.

5. Now type 'hello' into the Notepad and you will notice that we have received our first notification.

Click to enlarge

The source code of the Notepad and instructions to run it can be found here. In the next JMX article we will look at building on how we can develop custom applications to manage MBean instead of relying on jconsole.

Lee Chuk-Munn has been programming in the Java language since 1996, when he first joined Sun Microsystems in Hong Kong. He currently works as a senior developer consultant and technology evangelist for Technology Outreach at Sun in Singapore. Chuk's focus is in Java APIs, Java EE, Java SE, and Java ME. Chuk graduated in 1987 from the Royal Melbourne Institute of Technology in Melbourne, Australia, where his favorite subject was compiler theory.