ExampleMinimalNotificationListener

    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: