test

Java Dynamic Management Kit 5.1 Tutorial

6.3.2 Filtering MBeans

Because 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 that match are counted and displayed.

Filters restrict the set of MBeans listed in the agent view. This might 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 enables managers to either get lists of MBean names or find a particular MBean instance.

Filters are typed as partial object names with wildcard characters or as a full object name for which to search, using the syntax domain:key. Here are the basic substitution rules for filtering.

  1. You can search for partial domain names, using the following characters:

    Asterisk (*)

    Replaces any number (including zero) of characters

    Question mark (?)

    Replaces any one character

  2. An empty domain name is replaced by the default domain string; an empty key list is illegal

  3. Keys are atomic; you must search for the full property=value key; you cannot search for a partial property name or an incomplete value

  4. An asterisk (*) can be used to terminate the key list, where it replaces 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 that contain that subset of keys

To Filter MBeans

  1. Go to the administration page and create three more standard MBeans. Modify only the number value in their object names so that they are numbered sequentially.

  2. In the same way as Step 1, create four dynamic MBeans starting with:

    Domain:

    Dynamic_MBeans

    Keys:

    name=SimpleDynamic,number=1

    Java Class:

    SimpleDynamic

    Class Loader:

    leave blank

  3. Go back to the agent view, that should display all the new MBeans.

  4. Type each of the filter strings given in Table 6–1 to see the resulting MBean list

    Table 6–1 Examples of Filter Strings

    Filter String (domain:key)

    Result 

    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 shows 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 *:*.

  5. When you are ready to stop the base agent example, go to the window where you started its class and press Control-C.