6.3 Agent Administration

The agent administration page contains a form for entering MBean information when creating or unregistering MBeans. You can also instantiate an MBean through one of its public constructors. In order to instantiate an MBean, its class must be available in the agent application's classpath. Optionally, you can specify a different class loader if the agent contains other class loader MBeans.

To Display the Agent Administration Page

1. Go back to the agent view by clicking the link near the top of the MBean view page.

2. Click on the Admin button in the agent view to display the agent administration page in your browser window.

The first two fields, Domain and Keys are mandatory for all administrative actions. The Domain field initially contains the string representing the agent's default domain. Together, these two fields define the object name, whether for a new MBean to be created or for an existing MBean to unregister. The Java class is the full class name of the object to be instantiated as a new MBean. This field is ignored when unregistering an MBean.

Using the pull-down menu, you can choose one of three actions:

• Create – Instantiates the given Java class of an MBean and registers the new instance in the MBean server. If successful, the MBean appears in the agent view. The class must have a public constructor without parameters in order to be created in this way.

• Unregister – Unregisters an MBean from the MBean server so that it is no longer available in the agent. The class instance is not deleted explicitly, though if no other references to it exist, it will be collected by the garbage collector.

• Constructors – Displays the list of public constructors at the bottom of the administration page for the given Java class. This lets you provide parameters to a specific constructor and create the MBean in this manner. This is the only way to create MBeans that do not have a constructor without parameters.

When you click the Send Request button, the HTML adaptor processes the action and updates the bottom of the page with the action results. You might have to scroll down to see the result. The text fields are not cleared after a request, enabling you to perform multiple operations. Clicking the Reset button returns the fields to their last posted value after you have modified them.

6.3.1 Instantiating and Managing MBeans

Sometimes, starting an MBean requires several steps, especially for agent services that require some sort of configuration. For example, you can instantiate another HTML adaptor for connecting to a different port. Usually, this is done programmatically in the agent application, but we must do it through the browser for the agent.

To Create a New HTML Adaptor MBean

1. On the agent administration page, fill in the fields as follows:

   Domain

   Communications

   Keys:

   protocol=html,port=8088

   Java Class:

   com.sun.jdmk.comm.HtmlAdaptorServer

   Class Loader:

   leave blank

   In versions of the Java DMK prior to version 4.0, specifying the port number in the object name would initialize communication MBeans. Now, the names and contents of key properties no longer have any significance for any components of the product. We must set the port in other ways.

2. Make sure the action selected is Create and send the request. If you scroll down the page, you will see whether your request was successful.

   We cannot connect to this HTML adaptor quite yet. First we need to configure it .

3. Go to the new HTML adaptor's MBean view with the provided link.

   Remember that we could not modify any of the adaptor's attributes in To View an Attribute Description because the implementation does not allow them to be modified while the HTML adaptor is online. Our new HTML adaptor is instantiated in the stopped state (the StateString attribute indicates OFFLINE), so we can change its attributes.

4. Set the Port attribute to 8088 and MaxActiveClientCount to 2, then click the Apply button.

   If the page is reloaded and the new values are displayed, the attribute write operation was successful. You can also click the attribute names to get a description them.

5. Scroll down the MBean view to the Start operation and click the Start button.

   A new page is displayed to tell us the operation was successful. If you go back to the MBean view with the provided link, you can see that the StateString is now indicating ONLINE.

6. Now you can access your agent through a browser on port 8088. Try going to a different host on the same network and connecting to the following URL:

   http://agentHostName:8088/

   In the above URL, agentHostName is the name or IP address of the host where you launched the BaseAgent. If you reload the MBean view of the new HTML adaptor on either browser, the name of this other host should be the new value of the LastConnectedClient attribute.

Through this new connection, you can stop, modify or remove the HTML adaptor MBean using port 8082. In that case, your original browser will also have to use http://localhost:8088/ to connect. Instead, we will manage the agent from the second host.

To Instantiate MBeans With Constructors

1. From the browser on the second host, go to the agent administration page. Fill in the fields as follows and request the constructors:

   Domain:

   Standard_MBeans

   Keys:

   name=SimpleStandard,number=1

   Java Class:

   SimpleStandard

   Class Loader:

   leave blank

   The list of constructors for the SimpleStandard class is displayed at the bottom of the page. The MBean name is also shown. This is the object name that will be assigned to the MBean when using one of the listed constructors. As you can see, the SimpleStandard class only has one constructor that takes no parameters.

2. Click on the Create button. The result is appended to the bottom of the page. Scroll down and go to the MBean view with the provided link.

   Because it is a standard MBean, all of its description strings are generic. This shows the necessity of programming meaningful attribute names.

3. In the agent view on the first browser window, click in the filter field and press Return to refresh the agent view.

4. Click the new MBean's name and set its reload period to 15.

5. On the second host, type in a different string for the State attribute and click Apply.

   On the first host, you should see the MBean's attributes are updated when the MBean view is periodically reloaded.

6. On the second host, click the Reset operation button at the bottom of the MBean view page.

   The operation result page is displayed and indicates the success of the operation.

   This page also provides the return value of the operation when it is not void. If you go back to the MBean view, you will see the result of the operation on the attributes. You should also see it on the first host after it reloads.

The browser on the second host is no longer needed and we can remove the HTML adaptor on port 8088.

To Unregister an MBean

1. Go to the administration page and fill in the object name of the HTML adaptor you want to remove (you do not need its Java class to unregister it):

   Domain:

   Communications

   Keys:

   protocol=html,port=8088

   Java Class:

   leave blank

   Class Loader:

   leave blank

2. Choose Unregister from the pull-down menu and click the Send Request button.

   The result is displayed at the bottom of the page.

   You can also unregister an MBean directly from its MBean view. Click the Unregister button on the upper right side of the page.

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.