Version 6

    JMX Notification Subscription List


    SubscriptionList is a configuration element used by MBeans extending 

    ListenerServiceMBeanSupport. It is necessary in order to specify a

    subscription specification, in other words, to tell the base class

    to which MBeans to subscribe and for which JMX Notifications.


    The SubscriptionList is externalized through the SubscriptionList attribute

    that appears on org.jboss.system.ListenerServiceMBean:

    public interface ListenerServiceMBean
       extends ServiceMBean
       public void setSubscriptionList(org.w3c.dom.Element list); 

    It is essentially an XML element that follows the


    It provides a declarative and convenient way to specify simple or potentially

    complex subscription specifications. The jboss-subscription.dtd can be seen

    in the following diagram:





    This is an example of a NotificationListener service based on

    ListenerServiceMBeanSupport, that is provided with the jboss distribution.

    It can be used to monitor and output to the console any JMX Notification

    produced by any MBean in the server.

     <mbean code=""
       <attribute name="SubscriptionList">      
           <mbean name="*:service=invoker,*" handback="anObject"></mbean>
           <mbean name="jboss.monitor:*"></mbean>
           <mbean name="JMImplementation:type=MBeanServerDelegate">
             <notification type="JMX.mbean.registered"></notification>
       [ ... your-other-mbean-attributes ...]

    You may specify one or more elements with each one matching

    one or more MBeans. For example:

      <mbean name="*:*"></mbean>                              -- matches all MBeans in the server
      <mbean name="jboss:*"></mbean>                          -- matches all MBeans in domain jboss
      <mbean name="jboss:service=invoker,*"></mbean>          -- matches all MBeans in domain jboss
                                                          whose service=invoker
      <mbean name="jboss:service=invoker,type=local"></mbean> -- matches this particular MBean

    You may optionally specify a handback attribute. All incoming notifications

    that occur due to this particular mbean subscription will carry the handback

    object (converted into a java.lang.String). This may be useful to distinguish

    quickly the origin of the notification.


    In addition, one or more elements may be optionally specified

    to filter notifications for a particular subscription, based on the notification

    type. For each subscription, a object

    will be instantiated and "enabled" with the specified notification types.

    For example, to get registration/unregistration events from the

    MBeanServerDelegate you could use:

      <mbean name="JMImplementation:type=MBeanServerDelegate">
        <notification type="JMX.mbean.registered"></notification>
        <notification type="JMX.mbean.unregistered"></notification>

    or the equivalent:

      <mbean name="JMImplementation:type=MBeanServerDelegate">
        <notification type="JMX.mbean"></notification>  -- matches both JMX.mbean.registered &


    It is interesting to point out that the baseclass will register for the

    specified notification at start-up, but it can also monitor for newly

    instantiated MBeans and subscribe to them dynamically, if they match

    the subscription specification.


    Updates for v3.2.8, v.4.0.2


    The filtering mechanism that supported only a "fixed" NotificationFilterSupport

    filter has been extended to support arbitrary filters, using a filter factory

    plugin mechanism. To activate this feature use the following configuration


       <mbean name="...">
          <!-- assign an arbitrary filter to this subscription -->
          <filter factory="filter-factory-class-name">
             <!-- configuration of the filter is different -->
             <!-- depending on the chosen factory           -->

    Filter factories must implement the org.jboss.system.NotificationFilterFactory

    interface. Three filter factories corresponding to the "standard" JMX notification

    filters are already implemented in the org.jboss.system.filterfactory package.

    As a convenience, for any filter within this package you don't need to specify

    the full package plus classname.


    The predefined filter factories are the following:




    This provides the same functionality with the existing filtering mechanism.

    You may want to switch to the new more explicit syntax, in case we deprecate

    the old one. As a result the two following examples are equivalent:

       <!-- filter in both JMX.mbean.registered & JMX.mbean.unregistered -->
       <mbean name="JMImplementation:type=MBeanServerDelegate">
          <notification type="JMX.mbean"></notification> 
       <mbean name="JMImplementation:type=MBeanServerDelegate">
          <filter factory="NotificationFilterSupportFactory">
             <enable type="JMX.mbean"></enable>



    This filter factory is really meant for filtering notifications from the

    MBeanServerDelegate mbean. Its primary purpose is to let you receive

    registration and/or unregistration notifications for selected ObjectNames

    (i.e. mbean instances). You need to configure both the notification types

    and the object names you are interested in. For example:

       <!-- filter in both JMX.mbean.registered & JMX.mbean.unregistered -->
       <mbean name="JMImplementation:type=MBeanServerDelegate">
          <filter factory="MBeanServerNotificationFilterFactory">
             <enable type="JMX.mbean.registered"></enable>
             <enable object-name="mydomain:name=somembean"></enable>
             <enable object-name="mydomain:name=anothermbean"></enable>




    This filter factory creates AttributeChangeNotificationFilters, configured

    to filter-in AttributeChangeNotifications for particular mbean attributes.

    For example, if you want to receive "State" change notifications from all

    mbeans in the jboss.system domain, use:

       <mbean name="jboss.system:*">
          <filter factory="AttributeChangeNotificationFilterFactory">
             <enable attribute-name="State"></enable>


    Update for v4.0.3




    This filter factory is really meant for filtering notifications from

    SubDeployer mbeans. Its primary purpose is to let you be notified

    when a particular package (e.g. my-app.sar) gets processed (i.e. inited,

    created, started, stopped, destroyed) by a SubDeployer. In every case,

    the subdeployer emits a Notification that contains a DeploymentInfo

    instance, stored in the UserData field. So we essentially filter on both

    the notification type and the DeploymentInfo.shortName field. You can "enable"

    a series of different short-names.


    For example, to be notified when "my-app.sar" gets started/stoped, you can use:

       <!-- filter subdeployer start/stop notifications for "my-app.sar"
       <mbean name="jboss.system:service=ServiceDeployer">
          <filter factory="DeploymentInfoNotificationFilterFactory">
             <enable type="org.jboss.deployment.SubDeployer.start"></enable>
             <enable type="org.jboss.deployment.SubDeployer.stop"></enable>
             <enable short-name="my-app.sar"></enable>


    Writing your own NotificationFilterFactory


    Simply implement org.jboss.system.NotificationFilterFactory:

    public interface NotificationFilterFactory
        * Create a notification filter implementation and initialize
        * it, using the passed xml element fragment.
        * @param filterConfig the xml fragment to use for configuring the filter
        * @return an initialized NotificationFilter
        * @throws Exception in case the xml fragment cannot be parsed properly
       public NotificationFilter createNotificationFilter(Element filterConfig)
          throws Exception;

    Use the passed org.w3c.dom.Element to configure and return a NotificationFilter

    implementation. You'll either re-use on of the existing JMX filters, or create

    one of your own. Have a look at the filter factories in org.jboss.system.filterfactory



    For more information, see ListenerServiceMBeanSupport.



    Referenced by: