An Example Notification Listener Service

This is an example of a minimal notification listener MBean that you can

configure at deploy-time to intercept and log in the form of INFO messages

any kind of notification from any MBean. It can be used as a simple but

powerful notification debugging aid and it demonstrates how easy it is

to write a notification listener service.

The Management Interface

Our management interface is empty because we don't need any attribute or

operations in this minimal example. The interesting point to note is that

we don't extend org.jboss.system.ServiceMBean, rather

org.jboss.system.ListenerServiceMBean. By doing so we inherit the

settable attribute subscriptionList which is used at deploy time to

configure the subscription mechanism.

package jboss.example;

import org.jboss.system.ListenerServiceMBean;

public interface NotificationListenerMBean
   extends ListenerServiceMBean
{
   // empty
}

The Listener Service

Similarily, instead of extending org.jboss.system.ServiceMBeanSupport

we extend org.jboss.system.ListenerServiceMBeanSupport. By doing so,

we get all the standard facilities of ServiceMBeanSupport, plus an i

mplementation for the subscriptionList attribute, the decoding of

the xml subscription specification and the necessary notification

subscription machinery.

The internal API of ListenerServiceMBeanSupport consists basically of the methods:

   public void subscribe(boolean dynamicSubscriptions)
      throws Exception;

   public void subscribe(boolean dynamicSubscriptions, ObjectName listener)
      throws Exception;

   public void unsubscribe();

The service code can call one of the subscribe() methods and the

unsubscribe() method to activate/deactivate the subscriptions.

The only requirement is for the extending subclass to implement the method:

   public void handleNotification2(Notification notification, Object handback);

Notice the 2 in the name of method. This is important because the

base class overrides the standard handleNotification() in order to

intercept the incoming notification and implement dynamic subscriptions

to newly registered MBeans, before delegating to your code.

The Actual Listener Service Implementation

package jboss.example;

import javax.management.Notification; 
import javax.management.ObjectName; 

import org.jboss.system.ListenerServiceMBeanSupport; 

/** 
 * A simple JMX notification listener that outputs notifications as log.INFO 
 * messages, and demonstrates the usefulness of ListenerServiceMBeanSupport. 
 * 
 * @author <a href="mailto:dimitris@jboss.org">Dimitris Andreadis</a> 
**/ 
public class NotificationListener 
   extends ListenerServiceMBeanSupport 
   implements NotificationListenerMBean 
{ 
   // Constructors -------------------------------------------------- 
   /** 
    * CTOR 
   **/ 
   public NotificationListener() 
   { 
      // empty 
   } 

   // NotificationListenerMBean implementation ---------------------- 
   // No attributes or operations in this example to implement! 

   // Lifecycle control (ServiceMBeanSupport) ----------------------- 
   /** 
    * Start 
   **/ 
   public void startService() 
      throws Exception 
   { 
      // subscribe for notification, true=dynamic 
      super.subscribe(true); // listener is me! 
   } 

   /** 
    * Stop 
   **/ 
   public void stopService() 
      throws Exception 
   { 
      // unsubscribe for notifications 
      super.unsubscribe(); 
   } 

   // ListenerServiceMBeanSupport override ------------------------
   /** 
    * Overriden to add handling! 
   **/ 
   public void handleNotification2(Notification notification, Object handback) 
   { 
      log.info("Got notification: " + notification + ", handback: " + handback); 
   } 
} 

The MBean simply registers for notifications inside startService()

and unregisters for notification in stopService(). The true flag

in the call to subscribe() instructs the base class that the MBean

should monitor for registration events produced by the MBeanServer

itself and automatically subscribe to new instances of MBeans that

match the subscription criteria.

This solves a lot of dependency and chicken-egg problems, because you

can simply deploy your listener MBean and as soon you deploy your

notification broadcaster the listener will notice it and register

for notifications.

Method handleNotification2() simply logs the incoming notifications

whenever called.

Configuring the Subscription Specification

The subscription specification is provided inline in the mbean deployment

descriptor, by providing a composite value to the subscriptionList

MBean attribute.

You can always create a SAR (ServiceArhive, see ExampleHelloWorldService)

or you can simply deploy the service descriptor on its own, e.g. a

mylistener-service.xml could be the following:

  <server>
    <mbean code="jboss.example.NotificationListener"
           name="jboss.example:name=NotificationListener">

      <attribute name="SubscriptionList">      
        <subscription-list>
          <mbean name="*:service=invoker,*" handback="anObject"></mbean>
          <mbean name="jboss.monitor:*"></mbean>
             <notification type="JBOSS_MONITOR_NOTIFICATION"></notification>
          <mbean name="JMImplementation:type=MBeanServerDelegate">
            <notification type="JMX.mbean.registered"></notification>
          </mbean>
        </subscription-list>
      </attribute>
    </mbean>
  </server>

i.e.

1. subscribe to all notifications produced by MBeans that match the

  =":service=invoker," query. Return the handback object

  String("anObject") together with any notification that comes

  from this particular subscription

1. subscribe to notification of type "JBOSS_MONITOR_NOTIFICATION"

  that originate from any MBean in the "jboss.monitor" domain.

1. subscribe for "JMX.mbean.registered" notifications from the

  always-present"JMImplementation:type=MBeanServerDelegate".

Running the Example

By using the above subscription specification you should be able to

intercept the "JMX.mbean.registered" notifications produced for

every new MBean deployed in the server. Try to re-deploy any service

to see if you get the notifications. By using a specification like

the following you should be able to intercept all notifications in

the system:

      <attribute name="SubscriptionList">      
        <subscription-list>
          <mbean name="*:*"></mbean>
        </subscription-list>
      </attribute>

Related

• ListenerServiceMBeanSupport

• SubscriptionList

Referenced by: