Save This Page
Home » openjdk-7 » javax » management » [javadoc | source]
javax.management
public class: QueryNotificationFilter [javadoc | source]
java.lang.Object
   javax.management.QueryNotificationFilter

All Implemented Interfaces:
    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 {@linkplain Query Query API} to specify the filtering logic. For example, to select only notifications where the {@linkplain Notification#getType() type} is {@code "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.

{@code QueryNotificationFilter("Type = 'com.example.type1' or Type = 'com.example.type2'")}
Notifications where the type is either of the given strings.
{@code QueryNotificationFilter("Type in ('com.example.type1', 'com.example.type2')")}
Another way to write the previous example.
{@code QueryNotificationFilter("SequenceNumber > 1000")}
Notifications where the {@linkplain Notification#getSequenceNumber() sequence number} is greater than 1000.
{@code QueryNotificationFilter(AttributeChangeNotification.class, null)}
Notifications where the notification class is AttributeChangeNotification or a subclass of it.
{@code QueryNotificationFilter(AttributeChangeNotification.class, "AttributeName = 'Size'")}
Notifications where the notification class is AttributeChangeNotification or a subclass, and where the {@linkplain AttributeChangeNotification#getAttributeName() name of the changed attribute} is {@code Size}.
{@code QueryNotificationFilter(AttributeChangeNotification.class, "AttributeName = 'Size' and NewValue - OldValue > 100")}
As above, but the difference between the {@linkplain AttributeChangeNotification#getNewValue() new value} and the {@linkplain AttributeChangeNotification#getOldValue() old value} must be greater than 100.
{@code QueryNotificationFilter("like 'com.example.mydomain:*'")}
Notifications where the {@linkplain Notification#getSource() source} is an ObjectName that matches the pattern.
{@code QueryNotificationFilter("Source.canonicalName like 'com.example.mydomain:%'")}
Another way to write the previous example.
{@code 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 {@code 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 {@code Notification}.

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

The query specified in the {@code QueryNotificationFilter} constructor is evaluated against this {@code MBeanServer} and {@code 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 {@code Notification} has one attribute for every property of the {@code Notification}. Specifically, for every public method {@code T getX()} in the {@code NotificationClass}, the MBean will have an attribute called {@code X} of type {@code T}. For example, if the {@code Notification} is an {@code AttributeChangeNotification}, then the MBean will have an attribute called {@code AttributeName} of type {@code "java.lang.String"}, corresponding to the method AttributeChangeNotification#getAttributeName .

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

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

Constructor:
 public QueryNotificationFilter(QueryExp query) 
    Construct a {@code QueryNotificationFilter} that evaluates the given {@code QueryExp} to determine whether to accept a notification.
    Parameters:
    query - the {@code QueryExp} to evaluate. Can be null, in which case all notifications are accepted.
 public QueryNotificationFilter(String query) 
    Construct a {@code QueryNotificationFilter} that evaluates the query in the given string to determine whether to accept a notification. The string is converted into a {@code 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.
 public QueryNotificationFilter(Class<Notification> notifClass,
    String query) 

    Construct a {@code 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 {@code 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 {@code notifClass} is null.
Method from javax.management.QueryNotificationFilter Summary:
getQuery,   isNotificationEnabled
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from javax.management.QueryNotificationFilter Detail:
 public QueryExp getQuery() 
    Retrieve the query that this notification filter will evaluate for each notification.
 public boolean isNotificationEnabled(Notification notification)