javax.management
Class QueryNotificationFilter

java.lang.Object
  javax.management.QueryNotificationFilter

All Implemented Interfaces:

Serializable, NotificationFilter

public class QueryNotificationFilter
extends Object
implements NotificationFilter

General-purpose notification filter. This filter can be used to filter notifications from a possibly-remote MBean. Most filtering decisions can be coded using this filter, which avoids having to write a custom implementation of the NotificationFilter class. Writing a custom implementation requires you to deploy it on both the client and the server in the remote case, so using this class instead is recommended where possible.

This class uses the Query API to specify the filtering logic. For example, to select only notifications where the type is "com.example.mytype", you could use

 NotificationFilter filter =
     new QueryNotificationFilter("Type = 'com.example.mytype'");
 

or equivalently

 NotificationFilter filter =
     new QueryNotificationFilter(
             Query.eq(Query.attr("Type"), Query.value("com.example.mytype")));
 

(This particular example could also use NotificationFilterSupport.)

Here are some other examples of filters you can specify with this class.

QueryNotificationFilter("Type = 'com.example.type1' or Type = 'com.example.type2'")

Notifications where the type is either of the given strings.

QueryNotificationFilter("Type in ('com.example.type1', 'com.example.type2')")

Another way to write the previous example.

QueryNotificationFilter("SequenceNumber > 1000")

Notifications where the sequence number is greater than 1000.

QueryNotificationFilter(AttributeChangeNotification.class, null)

Notifications where the notification class is AttributeChangeNotification or a subclass of it.

QueryNotificationFilter(AttributeChangeNotification.class, "AttributeName = 'Size'")

Notifications where the notification class is AttributeChangeNotification or a subclass, and where the name of the changed attribute is Size.

QueryNotificationFilter(AttributeChangeNotification.class, "AttributeName = 'Size' and NewValue - OldValue > 100")

As above, but the difference between the new value and the old value must be greater than 100.

QueryNotificationFilter("like 'com.example.mydomain:*'")

Notifications where the source is an ObjectName that matches the pattern.

QueryNotificationFilter("Source.canonicalName like 'com.example.mydomain:%'")

Another way to write the previous example.

QueryNotificationFilter(MBeanServerNotification.class, "Type = 'JMX.mbean.registered' and MBeanName.canonicalName like 'com.example.mydomain:%'")

Notifications of class MBeanServerNotification representing an object registered in the domain com.example.mydomain.

How it works

Although the examples above are clear, looking closely at the Query API reveals a subtlety. A QueryExp is evaluated on an ObjectName, not a Notification.

Every time a Notification is to be filtered by a QueryNotificationFilter, a special MBeanServer is created. This MBeanServer contains exactly one MBean, which represents the Notification. If the source of the notification is an ObjectName, which is recommended practice, then the name of the MBean representing the Notification will be this ObjectName. Otherwise the name is unspecified.

The query specified in the QueryNotificationFilter constructor is evaluated against this MBeanServer and ObjectName, and the filter returns true if and only if the query does. If the query throws an exception, then the filter will return false.

The MBean representing the Notification has one attribute for every property of the Notification. Specifically, for every public method T getX() in the NotificationClass, the MBean will have an attribute called X of type T. For example, if the Notification is an AttributeChangeNotification, then the MBean will have an attribute called AttributeName of type "java.lang.String", corresponding to the method AttributeChangeNotification.getAttributeName().

Query evaluation usually involves calls to the methods of MBeanServer. The methods have the following behavior:

• The getAttribute method returns the value of the corresponding property.
• The getObjectInstance method returns an ObjectInstance where the ObjectName is the name of the MBean and the ClassName is the class name of the Notification.
• The isInstanceOf method returns true if and only if the Notification's ClassLoader can load the named class, and the Notification is an instance of that class.

These are the only MBeanServer methods that are needed to evaluate standard queries. The behavior of the other MBeanServer methods is unspecified.

Since:

1.7

See Also:

Serialized Form

Constructor Summary

QueryNotificationFilter(Class<? extends Notification> notifClass, String query)
Construct a QueryNotificationFilter that evaluates the query in the given string to determine whether to accept a notification, and where the notification must also be an instance of the given class.

QueryNotificationFilter(QueryExp query)
Construct a QueryNotificationFilter that evaluates the given QueryExp to determine whether to accept a notification.

QueryNotificationFilter(String query)
Construct a QueryNotificationFilter that evaluates the query in the given string to determine whether to accept a notification.

Method Summary

QueryExp	getQuery() Retrieve the query that this notification filter will evaluate for each notification.
boolean	isNotificationEnabled(Notification notification) Invoked before sending the specified notification to the listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QueryNotificationFilter

public QueryNotificationFilter(QueryExp query)

Construct a QueryNotificationFilter that evaluates the given QueryExp to determine whether to accept a notification.

Parameters:

query - the QueryExp to evaluate. Can be null, in which case all notifications are accepted.

QueryNotificationFilter

public QueryNotificationFilter(String query)

Construct a QueryNotificationFilter that evaluates the query in the given string to determine whether to accept a notification. The string is converted into a QueryExp using Query.fromString.

Parameters:

query - the string specifying the query to evaluate. Can be null, in which case all notifications are accepted.

Throws:

IllegalArgumentException - if the string is not a valid query string.

QueryNotificationFilter

public QueryNotificationFilter(Class<? extends Notification> notifClass,
                               String query)

Construct a QueryNotificationFilter that evaluates the query in the given string to determine whether to accept a notification, and where the notification must also be an instance of the given class. The string is converted into a QueryExp using Query.fromString.

Parameters:

notifClass - the class that the notification must be an instance of. Cannot be null.

query - the string specifying the query to evaluate. Can be null, in which case all notifications are accepted.

Throws:

IllegalArgumentException - if the string is not a valid query string, or if notifClass is null.

Method Detail

getQuery

public QueryExp getQuery()

Retrieve the query that this notification filter will evaluate for each notification.

Returns:

the query.

isNotificationEnabled

public boolean isNotificationEnabled(Notification notification)

Description copied from interface: NotificationFilter

Invoked before sending the specified notification to the listener.

Specified by:

isNotificationEnabled in interface NotificationFilter

Parameters:

notification - The notification to be sent.

Returns:

true if the notification has to be sent to the listener, false otherwise.