Tutorials : Advanced JMX Application Management :

Advanced JMX Application Management

A companion piece to "Soup-to-Nuts Application Management with JMX," this article continues to explore the JMX world, building upon what you have learned previously. Thus, if you're unfamiliar with JMX concepts like MBeans, JMX agents, adaptors, notifications, it's best to start with part one—you will be using what you learned there in this article's examples.

Looking forard, you'll see how to exploit some of JMX's advanced features, generically named Agent Services. By definition, a JMX agent provides a set of services and every single service is termed an Agent Service:

Timer Service
Monitor Services
M-Let Service

Let's get started!

Developing a Timer Service

A Timer Service triggers notifications to all its listeners at specific dates and times or repeatedly at a constant interval. Figure 1 below reveals the place of the Timer Service in JMX architecture:

Figure 1: A Timer Service Architecture

Before developing a Timer Service, you need to keep in mind the following ground rules:

A Timer Service is implemented as a standard MBean.
Time Service management is handled by registering it with the MBeanServer.
Time Service notifications are triggered only when the Timer Service is running and there are no start/stop notifications.
Notifications that are lost when the Timer Service is inactive can be obtained by setting the sendPastNotifications to true.
Notifications are sent only to registered listeners.

Implementing a Timer Service is a multi-step process:

Create an instance of the Timer class. You can find this class in the javax.management.timer package, which provides an implementation of the timer MBean. Among other things, this class is responsible for managing a list of dated timer notifications and sending alarms at a specified time to all the listeners registered to receive timer notifications. It has a single empty constructor which can be called like this:
```
Timer timer = new Timer ();
```

Register the Timer Service with the MBeanServer. To do this, use the registerMBean method. First, create a MBeanServer instance. Then use the registerMBean as shown below (don't forget that every MBean must have a unique identity in the MBeanServer registry):


//Get the MBeanServer

mbeanServer = ManagementFactory.getPlatformMBeanServer();



//the timer MBean must have a unique indentifier

ObjectName myTimerName = new ObjectName("Services:type=Timer");

       

//register the timer MBean       

 mbeanServer.registerMBean(timer, myTimerName);

Register a notification listener to the notification broadcaster. To do this, call the addNotificationListener method as shown below:


//create a notification listener

TimerNotificationsListener notificationListener = 

new TimerNotificationsListener();

           

//set the notification listener

mbeanServer.addNotificationListener 

(myTimerName, notificationListener, null, new Object());

The Timer Service maintains a list of the dated notifications that it has to send. Notifications are added in this list using the Timer.addNotification methods. These methods return integers that represents a unique identifier for the corresponding timer notification. Here are the addNotification method syntaxes:
```
public Integer addNotification(String type, String message, Object userData,                               

Date date) throws IllegalArgumentException



public Integer addNotification(String type, String message, Object userData,                              

Date date, long period) throws IllegalArgumentException



public Integer addNotification(String type, String message, Object userData,                           

Date date, long period, long nbOccurences) throws IllegalArgumentException



public Integer addNotification(String type, String message, Object userData,                              

Date date, long period, long nbOccurences, boolean fixedRate) 

throws IllegalArgumentException
```
The above methods contain the following parameters:
- type: This string represents the timer notification type.
- message: This string represents the timer notification message.
- userData: This object represents the notification's user data object.
- date: This date represents the date when the notification occurs.
- period: This long represents the length of time the timer notification will take (in milliseconds). If this is set to zero or null, the notifications will not repeat.
- nbOccurences: This long represents the total occurences of the timer notification. If this is set to zero or null, and if period is not set to null or zero, notification will repeat indefinitely.
- fixedRate: This this is set to true, and if the notification is periodic, the notification is scheduled with a fixed-rate execution scheme. If this is set to false, and if the notification is periodic, the notification is scheduled with a fixed-delay execution scheme. This is ignored if the notification is not periodic.
Notice that the addNotification methods may throw an IllegalArgumentException exception. Most often, this exception is generated by one of the below situations:
- The date is set to null.
- The period or nbOccurences are specified with negative values.
- If the date is less than the current date, and if the period is specified zero or null.
- If the date is less than the current date and period is not null.
- If nbOccurences is specified, the timer updates the date value for every nbOccurence. The date value must exceed the current date in the specified number of nbOccurences.
Now, you can add a timer notification:
```
timer.addNotification ("Register", "Testing the timer service !", 

new String(), new Date((new Date()).getTime()+5000), 10000, 5);
```

Set the Timer.sendPastNotifications parameter to true or false. If this parameter is set to false, the notifications that are lost when the Timer Service is inactive cannot be retrieved:
```
timer.setSendPastNotifications (false);
```

Start the Timer Service by calling the Timer.start method. This is shown below:
```
timer.start();
```

Putting together steps one through six will result in the TimerExample.java file (see Listing 1).

Before testing your Timer Service example, you need to write a user class: TimerNotificationsListener (this is not a predefined class). This is a notification listener, whose only particularity consists in using a subclass of javax.management.Notification instead of the Notification itself. This subclass is called javax.management.timer.TimerNotification and it provides methods specific to Timer Services (actually, it provides a single method named getNotificationID that returns the unique identifier associated to the current timer notification). The TimerNotificationsListener source code is shown in Listing 2.

Author's Note: A class that receives timer notifications must be registered as an MBean listener (the timer MBean is also a notification broadcaster). When the timer is active and the due date has arrived, the Timer Service broadcasts this notification to all its registered listeners. The broadcasted notification contains the message, notification type, user data, and the notification's identifier within the timer.

Now, place the above two classes into a directory (for example, TimerService), and test the Timer Service. Open a command prompt and type:


�>java -D.com.sun.management.jmxremote -classpath . TimerExample.

The window should look like Figure 2:

Figure 2: Running the TimerExample Timer Service

Notice that calling the Timer.start method startes the Timer Service programmatically. You can determine whether the timer is running by invoking the timer method Timer.isActive. This method returns true, if the timer is running.

By default, the notifications are removed from the timer's list whenever this is necessary (for example, when a notification is not repeating or its number of occurrences has been reached). If you want to explicitly remove a notification from the timer's list, you can use one of the Timer methods listed below:

public void removeNotification(Integer id) throws InstanceNotFoundException: This method removes a notification by id.

public void removeNotifications(String type) throws InstanceNotFoundException: This method removes a notification by type.

public void removeAllNotifications(): This method removes all notifications.

Home / Articles / Advanced JMX Application Management / 1

Applet Index
(sorted alphabetically)
A B C D E F G H I J K
L M N O P Q R S T U
V W X Y Z #s

The Java Source
(applets w/source code)
A B C D E F G H I J K
L M N O P Q R S T U
V W X Y Z

How to Add Java Applets to Your Site

New on the Java Boutique:

New Review:

Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling API boasts simplicity, ease-of-integration, a well-rounded feature set, and it's free!

New Applet:

Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA sequences into three useful formats.