The XMOJO Project
<< Prev Chapter 2.4 Notification Model Next >>

Notifications


Generally, the communication between a manager (a manager can be a protocol adaptor or another MBean listening for notification), JMX agent (JMX agent is explained in the next topic Agent Level), and the managed resource, will be :

Step 1 : Manager asks for a request
Step 2 : JMX agent forwards the request to the managed resource and obtains the information from the managed resource
Step 3 : JMX agent sends back the response received to the manager

There may be some special scenarios, where a JMX agent sends some information to the manager when some events occur.  These events are termed Notifications.

 javax.management.Notification Class 

The Notification Class represents a notification emitted by an MBean.  The Notification object contains the below fields:
  1. Type -- A String expressed in a dot notation. For example, Server.started
  2. SequenceNumber -- A long value expresses a serial number identifying a particular instance of notification in the context of the notification broadcaster
  3. TimeStamp -- A time stamp indicating when the notification was generated
  4. Message -- A String representing the explanation for the notification
  5. UserData --  A hash table representing the additional data that the notification broadcaster wishes to communicate to its listeners

 Sending Notification 

An MBean or a Java class capable of sending notifications is termed as Notification Broadcaster.  Any type of MBean, such as Standard, Dynamic, or Model MBean, can broadcast notification.  For an MBean or Java class to broadcast notification, it must implement the NotificationBroadcaster interface.  Another easier approach is that the MBean or Java class can extend the NotificationBroadcasterSupport.  The NotificationBroadcasterSupport implements the NotificationBroadcaster and also provides a method called sendNotification, which takes a object of type javax.management.Notification.  Notification can be broadcasted by calling this sendNotification method.  When this sendNotification method is called, Notification will be sent to all the registered listeners.

 Registering Listeners 

A listener can be an MBean or any other object which implements the NotificationListener interface.  
Any number of listeners can be registered to a Notification Broadcaster. A listener is registered to the broadcaster by invoking the addNotificationListener method on the broadcaster.  The method syntax is

public void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)

When the above method is invoked, the listener object or the listener MBean is registered to the broadcaster as one of the listeners.  The Object handback that is used while registering the listener MBean will be sent unmodified along with the Notification when sendNotification is invoked.  We will see more about NotificationFilter in the section Filtering Notification.  

A listener can be registered only once with a broadcaster.  For registering it more than once with the same broadcaster, then the Object handback passed while invoking the addNotificationListener should be different.

 Receiving Notification 

Any object or MBean can receive the notification sent by any MBeans.  To achieve this, the object or MBean should
  1. Register itself as one of the listeners to the MBean or Java class from which Notification has to be received.
  2. Implement the NotificationListener interface.
To register the object or MBean as one of the listeners, refer to the section Registering Listeners provided above.

Implementing the NotificationListener Interface:

The NotificationListener interface has only one method called handleNotification.  The method syntax is

public void handleNotification(Notification notif, Object handback)

This handleNotification is a call back method.  When sendNotification is invoked, the broadcaster sends a notification to all the registered listeners, and the handleNotification is method is invoked on each of the listeners.  The handback Object obtained will be the one which have been used in the addNotificationListener method.

 Filtering Notification 

When a notification listener is registered itself to the notification broadcaster, then any notification sent by the broadcaster will be received.  There may be scenarios where the listener wants to receive only specific notification from the broadcaster.  

This is achieved by defining a notification filter and passing it while registering the listener to the notification broadcaster.  Any object that implements the NotificationFilter interface acts as a notification filter.  The NotificationFilter interface defines a unique method isNotificationEnabled and the method syntax is

public boolean isNotificationEnabled(Notification notif)

Easier approach for creating a NotificationFilter is to extend NotificationFilterSupport Class.  NotificationFilterSupport has defined methods like disableType(String type) and enableType(String type).  So, by invoking disableType("Server.restart") on the NotificationFilter object, the notification of type Server.restart will not be received.

 Notification Mechanism 

  1. A notification is generated by calling the sendNotification method on the notification broadcaster MBean.
  2. The notification broadcaster checks the list of listeners registered with it.
  3. For each listener registered, it checks whether any filter is applied,  i.e, it invokes the isNotificationEnabled(Notification notif).
  4. If isNotificationEnabled returns false, then no notification will be sent to that listener.
  5. If isNotificationEnabled returns true, then the notification object along with the handback object of the corresponding listener will be sent to that listener.  This handback object will be the one which is provided while invoking addNotificationListener(... , ..., Object handback)
  6. When a notification is sent to a listener, the handleNotification method of that listener is called.
To see a sample demo of the working of Notification Mechanism, try out this example.

Points to Remember
  1. Any type of MBean, standard, dynamic or model or a non-MBean class can be either a notification broadcaster, a notification listener, or both at the same time.
  2. For an MBean or Java class to be a notification broadcaster, it should implement the NotificationBroadcaster interface.  Easier approach is to extend NotificationBroadcasterSupport.
  3. For an MBean or Java class to be a notification listener, it should implement the NotificationListener interface.  For receiving notification, it should be registered as one of the listeners with the notification broadcaster.
  4. Notification can be filtered by passing a NotificationFilter object while invoking the addNotificationListener method.
  5. Notification filtering can be based on notification type, or notification message, or any other thing depending on how the NotificationFilter is implemented.
  6. Conversion of a notification into protocol-specific implementation, such as SNMP Trap, is the responsibility of the protocol adaptors.

<< Prev Home Next >>
Writing a Model MBean
Agent Level