19.0 Using Query Expressions

19.1 Query Expressions : An Overview

19.2 Classes and Interfaces Defined for Developing Query Expressions

19.3 Example

19.1 Query Expressions : An Overview

The MBeans registered with the MBean server can be retrieved using queryMBeans method.  Using Object name you can filter the MBeans according to its type. Using Query expression you can further filter the MBeans according to its attribute values.

A Query expression is the user-defined criteria for filtering MBeans based on the attribute values. If query method does not find any MBean with the given condition and/or if MBeans do not satisfy the given query expression, the returned set will not contain any element. Querying and filtering are actually performed by the MBean server itself, not by a separate MBean.

For example, a filter could select all the MBeans whose object name contains "MyMBeans" while a Query Expression in tandem with the filter would get all the MBeans whose ObjectName contains "MyMBeans" and attribute named color is equal to "red". The result of a query operation is a list of MBean object names, which can then be used in other management requests.

19.2 Classes and Interfaces Defined for Developing Query Expressions

• The QueryExp interface identifies objects that are complete query expressions. These objects can be used in a query or composed to form more complex queries.
  
  The ValueExp and StringValueExp interfaces identify objects that represent numeric and string values, respectively, for placing constraints on attribute values.

• The AttributeValueExp interface identifies objects that represent the attribute involved in a constraint.

• The Query class supports the construction of the query. It contains static methods that return the appropriate QueryExp and ValueExp objects.

In practice, users do not instantiate the ValueExp and QueryExp implementation classes directly. Instead, they rely on the methods of the Query class to return the values and expressions, composing them together to form the final query expression. The methods of the MBeanServer interface that perform queries are:

• queryMBeans(ObjectName name, QueryExp query) - Returns a Set containing object instances (object name and class name pairs) for MBeans matching the name and query.

• queryNames(ObjectName name, QueryExp query) - Returns a Set containing object names for  MBeans matching the name and query.

19.3 An Example

Let us assume an agent is generated for AGENT-SAMPLE-MIB with default settings given in JMX Compiler. The object name of agentSystem would be WebNMSJMXAgent:type=AgentSystemInstrumentExt.

To filter the MBeans which has an attribute "AgentAvailMemory" where the attribute value is equal to 1000 :

• For the first constraint, define an AttributeValueExp as follows :
  AttributeValueExp at1 = Query.attr("AgentAvailMemory");
  It takes care of filtering the mbeans which has an attribute "AgentAvailMemory". Here it is WebNMSJMXAgent:type =AgentSystemInstrumentExt.
   

• For the second constraint, define an ValueExp as follows :
  ValueExp v1 = Query.value(1000);
  Using the above expressions, QueryExp is defined as follows:
  QueryExp exp1 = Query.eq(at1,v1);
  ObjectName objectName = new ObjectName("*:*");
  Set set = server.queryMBeans(objectName, exp1)

This set will contain the MBean of agentSystem.

In case of more condition statements, composition of calls can be constructed by arbitrary nesting of constraints, as follows :
QueryExp exp = Query.and(Query.gt(Query.attr("age"),Query.value(5)), Query.match(Query.attr("name"), Query.value("Smith")));