5.5 Finding MBeans

A management application will operate on at most a subset of the MBeanServer's MBeans. Very simple management applications may require only a static set of MBeans; the object names for that set may even be hard-coded. The majority of management applications, however, must deal with a dynamic set of MBeans whose identity is not known a priori . Therefore we have to answer the question, How does a management application select the MBeans it needs from the MBeanServer?

The MBeanServer provides a simple query service as part of its public API that allows management applications to select a set of registered MBeans on the basis of their names and the values of one or more of their attributes.

5.5.1 Query Expressions

The javax.management.QueryExp interface is the fundamental building block of the MBeanServer's query service. QueryExp defines two methods :

 void setMBeanServer(MBeanServer mbserver);  boolean apply(ObjectName objname); 

The apply() method evaluates a QueryExp instance against the MBean specified by objname . The setMBeanServer() method specifies the MBeanServer that apply() will use to look up objname .

QueryExp represents an expression in a simple constraint language. The language expresses constraints on the values taken by an MBean's attributes. For example, suppose we have a JobQueue MBean with attributes Priority , PendingJobs , AvgWaitTime , and MaxServiceTime ; we might be interested in JobQueue instances with

 Priority > 10 and AvgWaitTime > 100 

or for which

 PendingJobs * AvgWaitTime > MaxServiceTime 

The expressions represented by QueryExp in the query service constraint language are built up by the static methods of the javax.management.Query class.

The constraint language's primitive data are instances of type javax.management.ValueExp . ValueExp represents the Java primitive numeric types ( boolean , int , long , float , and double ) and Java numbers ”for example, Integer , Long , BigInteger . The class javax.management.StringValueExp represents Java strings, and the class javax.management.AttributeValueExp represents the value of an MBean attribute. Instances of ValueExp , StringValueExp , and AttributeValueExp are created by the Query methods:

 static AttributeValueExp attr(String attrname);  static AttributeValueExp attr(String attrcls, String attrname); static AttributeValueExp classattr(); static StringValueExp value(String val); static ValueExp value(boolean val); static ValueExp value(double val); static ValueExp value(float val); static ValueExp value(int val); static ValueExp value(long val); static ValueExp value(Number val); 

You can perform simple math on numeric instances of ValueExp using the Query methods:

 static ValueExp plus(ValueExp v1, ValueExp v2);  static ValueExp minus(ValueExp v1, ValueExp v2); static ValueExp times(ValueExp v1, ValueExp v2); static ValueExp div(ValueExp v1, ValueExp v2); 

Instances of QueryExp are built up by the application of one or more of the Query class's relational, logical, set, and regular expression methods to appropriate ValueExp instances. The signatures for those methods are

 // Query relational methods  static QueryExp eq(ValueExp v1, ValueExp v2); static QueryExp geq(ValueExp v1, ValueExp v2); static QueryExp leq(ValueExp v1, ValueExp v2); static QueryExp gt(ValueExp v1, ValueExp v2); static QueryExp lt(ValueExp v1, ValueExp v2); static QueryExp between(ValueExp val, ValueExp min, ValueExp max); // Query logical methods static QueryExp and(QueryExp q1, QueryExp q2); static QueryExp or(QueryExp q1, QueryExp q2); static QueryExp not(QueryExp query); // Query set methods static QueryExp in(ValueExp val, ValueExp[] valset); // Query regular expression methods static QueryExp initialSubString(AttributeValueExp attrval,                                  StringValueExp prefix); static QueryExp finalSubString(AttributeValueExp attrval,     StringValueExp suffix); static QueryExp anySubString(AttributeValueExp attrval,     StringValueExp substr); static QueryExp match(AttributeValueExp attrval,     StringValueExp pattern); 

Whereas the relational and logical operations have standard programming language semantics, the set and regular expression methods require a little explanation. The Query.in() method compares the values represented by the ValueExp instances, not the object references of those instances, as in this example:

 ValueExp[] velist = {Query.value(2), Query.value(4),      Query.value(6), Query.value(8) }; QueryExp q = Query.in(Query.value(4), velist); 

Applying q to an arbitrary ObjectName instance yields true , even though the object references for the two 4 values may be different:

 q.apply(new ObjectName("examples:name=setquery"));  // evaluates                                                      // to  true  

The *SubString() methods test their second argument against the value of the attribute specified by their first argument:

 // Evaluates to true if the value of the Status attribute begins  // with "SUCCESS" QueryExp q1 = Query.initialSubString(Query.attr("Status"),     Query.value("SUCCESS")); // Evaluates to true if the value of the URL attribute ends // with "html" QueryExp q2 = Query.finalSubString(Query.attr("URL"),     Query.value("html")); // Evaluates to true if the value of the Response attribute // contains "failed" QueryExp q3 = Query.anySubString(Query.attr("Response"),     Query.value("failed")); 

Finally, the match() method tests simple regular expressions specified by its second argument against the value of the attribute specified by the first argument. The regular expressions are a combination of wildcards ( * , which matches zero or more characters ; and ? , which matches a single character), character sets (specified by the characters in the set being enclosed in square brackets, as in [AaEeIiOoUu] ), and character ranges (specified by a hyphen [ - ] placed between the first character in the range and the final character in the range, as in [0 “9] ). To negate a regular expression, add an exclamation point as a prefix ”for example, ![AaEeIiOoUu] specifies the set of all upper- and lowercase consonants:

 // Evaluates to true if the value of the Id attribute consists of  // a two-digit number that begins with a 7 QueryExp qm = Query.match(Query.attr("Id"), Query.value("7[0-9]")); 

Now let's see how the JobQueue queries from the beginning of this section look expressed in terms of Query methods:

 QueryExp q1 = Query.and(Query.gt(Query.attr("Priority"),            Query.value(10)),           Query.gt(Query.attr("AvgWaitTime"), Query.value(100))); QueryExp q2 = Query.gt(Query.times(Query.attr("PendingJobs"),           Query.attr("AvgWaitTime")),           Query.attr("MaxServiceTime")); 

To evaluate one of these queries, we first specify the MBeanServer to use as a context and then apply the query to an ObjectName instance:

 q1.setMBeanServer(mbs);  boolean excessiveAvgWait =     q1.apply(new ObjectName("examples:name=MyJobQueue")); 

5.5.2 Query Scope and Pattern Matching

The QueryExp apply() method is useful if we know the object name of the MBean we want to evaluate the expression against. What if we don't know the object name a priori, in which case we can't hard-code it into the application or supply it via a .properties file, and the management application runs unattended, so that the object name can't be supplied by the user at runtime? What if there is a set of MBeans we want the expression evaluated against? How do we determine which object names to apply to the expression in these rather common situations?

JMX provides ObjectName patterns that allow you to specify a subset of the object names in the MBeanServer's registry. An ObjectName pattern is an object name whose domain and key properties components may contain wildcard characters. An asterisk ( * ) in the domain component matches zero or more characters. A question mark ( ? ) in the domain component matches a single character. An asterisk in the key properties component matches zero or more name/value pairs. The set of object names that match a pattern is called the query scope.

For example, assume we have the following object names in the registry:

 http:name=H001, pool=Primary  http:name=H002, pool=Reserved https:name=H003, pool=Primary smtp:name=H011, pool=Primary smtp:name=H012, pool=Primary ftp:name=H101, pool=Primary queues/http:id=FF01, servicelevel=Gold queues/http:id=FF02, servicelevel=Silver queues/smtp:id=FF11, servicelevel=Gold logs/http:filename=access.log, ownerid=FF01 logs/http:filename=error.log, ownerid=FF01 

Here are some valid patterns and their associated query scopes:

 queues/*:*    // all the queues   queues/http:id=FF01, servicelevel=Gold   queues/http:id=FF02, servicelevel=Silver   queues/smtp:id=FF11, servicelevel=Gold *:filename=error.log   // all the object names with just the filename=error.log key   // property  no matching ObjectNames  *:filename=error.log, *   // all the object names with a filename=error.log key property   logs/http:filename=error.log, ownerid=FF01 http*:*, pool=Primary   // all the "http"-related object names with a Primary pool key   // property   http:name=H001, pool=Primary   https:name=H003, pool=Primary queues/*:servicelevel=Gold, *   // all the queues with a Gold service level   queues/http:id=FF01, servicelevel=Gold   queues/smtp:id=FF11, servicelevel=Gold logs/*:*, ownerid=FF01   // all the logs owned by FF01   logs/http:filename=access.log, ownerid=FF01   logs/http:filename=error.log, ownerid=FF01 

The patterns *:* and "" (the empty string), are equivalent and match all the object names in the MBeanServer's registry. To specify a pattern on the MBeanServer's default domain, omit the domain component of the object name; for example, :* selects all object names in the MBeanServer's default domain.

5.5.3 MBeanServer Query Methods

The MBeanServer's two query methods bring together query scopes (specified by ObjectName patterns) and query expressions (specified by instances of QueryExp ). Here are the signatures for those methods:

 Set queryMBeans(ObjectName pattern, QueryExp constraint);  Set queryNames(ObjectName pattern, QueryExp constraint); 

Both versions select the set of object names matching the pattern parameter from the MBeanServer's registry. Both versions then apply the constraint parameter to the MBeans associated with the selected object names. The queryNames() method returns the set of object names for which the constraint parameter was true . The queryMBeans() method returns the equivalent set of ObjectInstance instances.

For example, suppose we're interested in obtaining the object names of all of the queues with a Gold service level that are experiencing excessive average wait times. Here's a call to queryNames() that returns the object names we're interested in:

 ObjectName gq = new ObjectName("queues/*:servicelevel=Gold, *");  QueryExp eaw = Query.gt(Query.times(Query.attr("PendingJobs"),                                     Query.attr("AvgWaitTime")),                                     Query.attr("MaxServiceTime")); Set badgq = mbs.queryNames(gq, eaw); 

The queryNames() method first uses gq to select the set of queues with a Gold service level. It then applies the eaw query expression to each of them and returns the set of queue ObjectName instances for which the QueryExp eaw was true .