Background on JMX Notifications

Typically, MBeans have attributes/operations and they can optionally

emit and consume notifications.

JMX Notifications are simple classes that extend javax.management.Notification.

This base class contains basic information (type, timestamp, source, etc.)

and there are a number of subclasses (e.g. javax.management.AttributeChangeNotification)

that provide additional information.

Developers can create their own notification subclasses and define their own

notification types (java-package-like strings that are used to identify

notifications by name, rather than class, e.g. "jmx.attribute.change"),

in order to convey any type of information.

Notifications provide a convenient way for an MBean (or an external non-MBean

listener) to be informed about various "events" that occur inside the

MBeanServer and its registered MBeans. For example, a monitoring MBean

may emit a notification to indicate a memory low condition. Another MBean

may subscribe with the MBeanServer to receive notifications whenever a new

MBean is registered or unregistered.

The power of Notifications is that the MBean that acts as a Notification

broadcaster is decoupled from any interested Notification Listeners that

register at runtime in order to receive notifications.

The JBoss helper class org.jboss.system.ServiceMBeanSupport

provides an excellent base for writing Standard MBeans that act as Notification

Broadcasters, too. Infact, the base class will emit

javax.management.AttributeChangeNotification to indicate the transition

between the STOPPED, STARTING, STARTED, STOPPING and FAILED states

(see ServiceLifecycle).

Writing a Notification Listener MBean

To write a Standard MBean that is a Notification Listener, too, you need

to follow all the usual steps for creating a Standard MBean (e.g.

ExampleHelloWorldService) and in addition implement the

javax.management.NotificationListener interface by providing

an implementation for the callback method:

void handleNotification(Notification notification, Object handback);

This method is called whenever an MBean that you have specifically

subscribed to receive notifications, emits a notification. As a result,

independently of what you do with those notifications, you must first

subscribe for receiving them, by optionally supplying a

javax.management.NotificationFilter object, that can filter

notifications at source.

Registering for notification is done at the MBeanServer separately

for each MBean that you want to receive notifications from, using

the following method:

void addNotificationListener(ObjectName name, 
                             ObjectName listener, 
                             NotificationFilter filter,
                             Object handback) 
                                throws InstanceNotFoundException

Design Issues

Except for relatively simple cases where MBean A registers for

notifications from MBean B, things can quickly become complex

considering the following:

• receiving notifications from multiple MBeans

• receiving selected notifications from MBeans

• specifying the registration settings declaratively

• registering dynamically to new MBeans

Since the process of managing notification registrations is independent

of the actual handling of the received notifications, we have factored out

the above functionality inside a helper base class that you can use

to build quickly your own extensible notification listener Standard MBeans.

ListenerServiceMBeanSupport

org.jboss.system.ListenerServiceMBeanSupport

is an abstract base class

that extends

org.jboss.system.ServiceMBeanSupport

and implements both

org.jboss.system.ListenerServiceMBean and javax.management.NotificationListener.

To create your standard listener MBean, follow the step for creating a

JBoss Standard Mbean (as in ExampleHelloWorldService), with the following

exceptions:

1. Extend ListenerServiceMBeanSupport instead of ServiceMBeanSupport.

2. Make your MBean interface extending ListenerServiceMBean instead of

  ServiceMBean. This will give your MBean interface an additional

  SubscriptionList attribute that will be used to configure the

  subscription mechanism at deploy-time.

1. Call subscribe(boolean dynamicSubs) at anytime in your code

  (e.g. in startService() to register to those MBeans and for

  those notifications that match the specified criteria in the

  SubscriptionList attribute.

1. Call unsubscribe() at anytime in your code (e.g. in stopService()

  to unsubscribe for notifications.

1. Override the handleNotification2() method, instead of the usual

  handleNotification() method to handle the incoming notifications.

Follow the link to ExampleMinimalNotificationListener, for a simple

notification listener that outputs to the console any notification

that you configure it at deploy time.

Referenced by: