Filtering MBeans

Since an agent can manage hundreds of MBeans, the agent view provides a filtering mechanism for the list that is displayed. An object name with wildcard characters is used as the filter, and only those MBeans which match are counted and displayed.

Filters restrict the set of MBeans listed in the agent view. This may not be particularly useful for our small agent, but it can help you find MBeans among hundreds in a complex agent. In addition, management applications use the same filter syntax when requesting an agent's MBeans through the programmatic interface of a connector. The filtering lets managers get either lists of MBean names or find a particular MBean instance.

Filters are entered as partial object names with wildcard characters or as a full object name for which to search. Here are the basic substitution rules for filtering:

1. You may search for partial domain names:the asterisk (*) stands for any number (including zero) of any characters;the question mark (?) stands for any one character

2. An empty domain name stands for the default domain string;an empty key list is illegal

3. Keys are atomic: you must search for the full property=value key, you may not search for a partial property name or an incomplete value

4. The asterisk (*) may be used to terminate the key list, where it stands for any number of any keys (complete property-value pairs)

5. You must match all keys exactly: use the form property=value,* to search for one key in names with multiple keys

6. Keys are unordered when filtering: giving one or more keys (and an asterisk) in any order finds all object names which contain that subset of keys

Instructions

1. Go to the administration page, and create three more of the standard MBeans. Modify only the number value in their object name so that they are numbered sequentially. In the same way, create four dynamic MBeans starting with:

   Domain:	Dynamic_MBeans
   Keys:	name=SimpleDynamic,number=1
   Java Class:	SimpleDynamic
   Class Loader:	leave blank

2. Go back to the agent view which should display all of the new MBeans.

3. Enter the following filter strings to see the resulting MBean list:

   Standard_MBeans:*	Gives all of the standard MBeans we created
   *_MBeans:*	Gives all of the standard and dynamic MBeans we created
   DefaultDomain:	Not allowed by rule 2
   :*	Lists all MBeans in the default domain
   *:name=Simple*,*	Not allowed by rule 3
   *:name=SimpleStandard	Allowed, but list is empty (rule 5)
   *:name=*	Not allowed by rule 3
   *_??????:number=2,*	Gives the second standard and dynamic MBean we created
   Communications:port=8088,protocol=html	Gives the one MBean matching the domain and both (unordered) keys
   empty string	allowed: special case equivalent to *:*

   Notice how the MBean count is updated with each filter: this count gives the number of MBeans that were found with the current filter, which is the number of MBeans appearing on the page. It is not the total number of MBeans in the agent, unless the filter is *:*.

4. When you are ready to stop the minimal agent example, go to the window where you launched its class and type <Control-C>.