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:
Example
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="org.jboss.monitor.services.NotificationListener" name="jboss.jmx:service=NotificationListener"> <attribute name="SubscriptionList"> <subscription-list> <mbean name="*:service=invoker,*" handback="anObject"></mbean> <mbean name="jboss.monitor:*"></mbean> <mbean name="JMImplementation:type=MBeanServerDelegate"> <notification type="JMX.mbean.registered"></notification> [...] </mbean [...] </subscription-list> </attribute> [ ... your-other-mbean-attributes ...] </mbean>
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 javax.management.NotificationFilterSupport 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> </mbean
or the equivalent:
<mbean name="JMImplementation:type=MBeanServerDelegate"> <notification type="JMX.mbean"></notification> -- matches both JMX.mbean.registered & JMX.mbean.unregistered </mbean>
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
syntax:
... <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> </mbean> ...
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:
NotificationFilterSupportFactory
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> <mbean name="JMImplementation:type=MBeanServerDelegate"> <filter factory="NotificationFilterSupportFactory"> <enable type="JMX.mbean"></enable> </filter> </mbean> ...
MBeanServerNotificationFilterFactory
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> </filter> </mbean> ...
AttributeChangeNotificationFilterFactory
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> </filter> </mbean> ...
Update for v4.0.3
DeploymentInfoNotificationFilterFactory
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> </filter> </mbean> ...
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
package.
For more information, see ListenerServiceMBeanSupport.
Referenced by:
Comments