Chapter 4 The HTML Protocol Adaptor

The HTML protocol adaptor provides a view of the agent and its registered MBeans through a basic interface on any web browser. It is the easiest way to access an agent since no further coding is necessary. For this reason, it can be useful for testing and debugging your MBeans in the minimal agent.

In fact, we will use your browser to "manage" the minimal agent and its MBeans. The HTML protocol adaptor outputs HTML pages which represent the agent and its MBeans. The adaptor also interprets the commands sent back by the buttons and fields appearing in your browser. It then interacts with the agent's MBean server in order to get information about the MBeans that it has registered and operate on them.

The HTML adaptor relies mostly on plain HTML. The only JavaScript^TM that the generated pages contain are pop-up windows for displaying information. Browsers that are not JavaScript enabled might give an incompatibility message and won't be able to display the information. Otherwise, the generated pages contain no further scripting (JavaScript, Visual Basic or other), no frames and no images that might slow down loading.

This topic relies on the minimal agent which you will need to launch first, as explained in "Running the Minimal Agent Example". Once you can connect to the HTML protocol adaptor in the minimal agent, you are ready to go through these topics:

• "The Agent View" is the main page for managing an agent through the HTML protocol adaptor

• "The MBean View" exposes an MBean's management interface

• The "Agent Administration" lets you instantiate new MBeans

• "Instantiating and Managing MBeans" shows how to modify attributes and invoke operations

• "Filtering MBeans" is used to select the MBeans displayed in the agent view

The Agent View

The first page displayed by the HTML adaptor is always the agent view. It originally contains a list of all registered MBeans. The following figure shows the agent view for the minimal agent. It contains four MBeans: the three communication MBeans, one of which is the HTML adaptor, and the MBean server delegate. The delegate is a special MBean covered in "The MBean Server Delegate".

Figure 4-1 Initial Agent View of the Minimal Agent

The text field for filtering by object name lets you modify the list of displayed MBeans. The filter string is initially *:*, which gives all registered MBeans. Further use of the filter is covered in "Filtering MBeans". The agent's registered domain tells you the name of the default domain in this agent. The number of MBeans on this page is the count of those listed beneath the separator line.

The "Admin" button is a link to the agent administration page which we will cover in "Agent Administration".

The MBean List

The MBean list contains all MBeans whose object name matches the filter string. Object names can be filtered by their domain name and list of key-value pairs. In this list, MBeans are sorted and grouped by their domain name. Each MBean name listed is an active link to the page of the corresponding MBean view.

After its initialization, the contents of an agent are dynamic: new MBeans may be created and registered into new or existing domains and old MBeans may be removed. These changes can also affect the functionality of the agent: new agent services may be registered (or removed) as well. We will demonstrate examples of dynamic management in "Instantiating and Managing MBeans".

The MBean Server Delegate

The MBean server delegate is an MBean that is automatically instantiated and registered by the MBean server when it is created. It provides information about the version of the Java Dynamic Management Kit which is running, and it represents the MBean server when sending notifications.

Notifications are events sent by MBeans, they are covered by the JMX specification and the notification example in examplesDir/Notification. Since the MBean server instance is not an MBean object, it relies on its delegate MBean to send notifications. The MBean server delegate sends notifications to inform interested listeners about such events as MBean registrations and de-registrations.

The exposed attributes of the delegate MBean provide vendor and version information about the MBean server. This can let a remote management application know which agent version is running and which version of the Java Runtime Environment it is using. The delegate MBean also provides a unique identification string for its MBean server.

Viewing the MBean Server Delegate Information

1. Click on the name of the delegate MBean to see its attributes. Version, vendor and identification information is listed in the table of attributes.

2. Click on the Back to Agent View link or use your browser's Previous page function to return to the MBean list in the agent view.

The MBean View

The MBean view has two functions: it presents the management interface of the MBean and it lets you interact with its instance. The management interface of an MBean is given through the name of the attributes, the operation signatures, and a self-description. You may interact with the MBean by reloading its attribute values, setting new values or invoking an operation.

Preparation

1. In the agent view, click on the object name of the HTML adaptor MBean: name=HTMLAdaptorServer in the default domain. This will bring up its MBean view.

The Header and Description

As shown in the following figure, the top part of the page contains the description of the MBean and some controls for managing it:

Figure 4-2 Description in the MBean View

The first two lines give the object instance (object name and class name) for this MBean. The MBean name is the full object name of this MBean instance, including the domain. The key-property pairs may or may not identify the MBean to a human reader, depending on the agent developer's intention. The MBean Java class is the full class name for the Java object of which this MBean is an instance.

The reload controls include a text field for entering a reload period and a manual "Reload" button. Originally, the reload period is set to zero indicating that the contents of the MBean view are not automatically refreshed. Clicking the reload button will force the page to reload, thereby updating all of the attribute values displayed. If you have entered a reload period, clicking the button will begin automatic reloading with the given period. The reload period must be at least five seconds.

Setting the Reload Period

1. Enter a reload period of five and click the "Reload" button. Every five seconds the page will blink as it reloads.

2. In another browser window, open another connection to the HTML adaptor at http://localhost:8082/. Observe the new values for the ActiveClientCount and LastConnectedClient attributes in the original window. Due to the way the adaptor works, you may have to try several connections before you see the attribute values change.

The reload period is reset to zero every time you open an MBean view.

The "Unregister" button is a shortcut for removing this MBean from the agent. Unregistering is covered in "Instantiating and Managing MBeans".

The MBean description text provides some information about the MBean. Because standard MBeans are statically defined, they cannot describe themselves, and the MBean server provides a generic text. Dynamic MBeans are required to provide their own description string at runtime according to the JMX specification. Except for the class name, this is the only way to tell standard and dynamic MBeans apart in the MBean view.

The Table of Attributes

The second part of the MBean view is a table containing all attributes exposed by the MBean. For each attribute, this table lists its name, its Java type, its read-write access and a string representation of its current value.

While MBean attributes may be of any type, not all types can be displayed in the MBean view. The HTML adaptor is limited to basic data types that can be displayed and entered as strings. For the complete list, see the Javadoc API of the HtmlAdaptorServer class. The table of attributes contains only those which can be displayed or entered as a string. Read-only attributes whose type support the toString method are also displayed.

Attributes with array types are represented by a link to a page which displays the array values in a table. If the attribute is writeable, you may enter values for the array elements to set them. Attributes of type com.sun.jdmk.Enumerated or its sub-classes are displayed as a menu with a pop-up selection list.

The name of each attribute is a link that pops up a dialog box containing the description for this attribute. Like the MBean description, attribute descriptions can only be provided by dynamic MBeans. The MBean server inserts a generic message for standard MBean attributes. The following figure shows the attributes of the HTML adaptor with a description of the Active attribute:

Figure 4-3 MBean Attributes with a Description Dialog

Viewing Attribute Descriptions

1. Click on the attribute names of the HTML adaptor to read their description. Since the HTML adaptor is implemented as a dynamic MBean, its attribute descriptions are meaningful.

   ---

   Note -

   Due to the use of JavaScript commands in the generated HTML, these pop-up windows might not be available on browsers that are not JavaScript-enabled.

   ---

Writable attributes have a text field for entering new values. To set the value of a writable attribute, you would enter or replace its current value in the text field and click the "Apply" button at the bottom of the attributes table.

You should not try to modify the attributes of the HTML protocol adaptor here, we will see why in "Instantiating and Managing MBeans".

Because there is only one "Apply" button for all attributes, this button has a particular behavior: it systematically invokes the setter for all writeable attributes, whether or not their field has actually been modified. This may impact the MBean if setters have side effects, such as counting the number of modifications as in the SimpleStandard and SimpleDynamic examples given in Chapter 1, Standard MBeans and Chapter 2, Dynamic MBeans.

The HTML adaptor detects attributes which are ObjectName types and provides a link to the MBean view of the corresponding MBean. This link is labeled view, and it is located just under the displayed value of the object name. Since MBeans often need to reference other MBeans, this provides a quick way of navigating through MBean hierarchies.

The Operations

The last part of the MBean view contains all of the operations exposed by the MBean. Each operation in the list is presented like a method signature: there is a return type, then a button with the operation name, and if applicable, a list of parameters, each with their type as well.

As with the table of attributes, the list of operations contains only those involving types that can be represented as strings. The return type must support the toString method and the type of each parameter must be one of basic data types supported by the HTML adaptor. For the complete list, see the Javadoc API of the HtmlAdaptorServer class.

Above each operation is a link to its description. Parameter names are also active links which pop up a window with a description text. Again, descriptions are only meaningful when provided by dynamic MBeans. The following figure shows some of the operations exposed by the HTML adaptor MBean and a description of the Start operation.

Figure 4-4 MBean Operations with a Description Dialog (Partial View)

We will not invoke any operations on this MBean until a brief explanation in "Instantiating and Managing MBeans". If we stopped the HTML adaptor or blocked it with an error, there would no longer be any way to connect with a browser: we would have to stop the minimal agent and restart it.

To invoke an operation, you would fill in any and all parameter values in the corresponding text fields and then click the operation's button. The HTML adaptor would then display a page with the result of the operation: the return value if successful or the reason the operation was unsuccessful.

Agent Administration

Preparation

1. Go back to the agent view by clicking the link near the top of the MBean view page. Then click on the "Admin" button in the agent view to bring up the agent administration page in your browser window.

The agent administration page contains a form for entering MBean information when creating or unregistering MBeans. You may 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 may specify a different class loader in the appropriate field if the agent contains other class loader MBeans.

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 fields define the object name, whether for a new MBean to be created or the name of 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 drop-down menu, you may select one of three actions on this page:

• Create - Instantiates the given Java class of an MBean and registers the new instance in the MBean server. If successful, the MBean will then appear 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 explicitly deleted, though if no other references to it exist, it will be garbage collected.

• 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 which do not have a no-parameter constructor.

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 may have to scroll down to see the result. The text fields are not cleared after a request so that you can do multiple operations. The "Reset" button will return the fields to their last posted value after you have modified them.

Instantiating and Managing MBeans

Sometimes, launching an MBean requires several steps: this is particularly the case for agent services which require some sort of configuration. For example, you can instantiate another HTML adaptor for connecting to a different port. Usually, this would be done programmatically in the agent application, but we need to do it through the browser for the minimal agent.

Creating 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

   Note: In previous versions of product, specifying the port number in the object name would initialize communication MBeans. Starting with the Java Dynamic Management Kit 4.0, 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 selected action is "Create" and send the request. If you scroll down the page, you should see if your request was successful.

   We can't connect to this HTML adaptor quite yet, we need to configure it first.

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

   We couldn't modify any of the adaptor's attributes before because the implementation is designed so that they can't be modified while it is on-line. 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 may also click the attribute names to get an explanation for them.

5. Scroll down the MBean view to the Start operation and click its button. This brings up a new page 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 should be able to access your minimal agent through a browser on port 8088. Try going to a different machine on the same network and connecting to the URL:

   http://agentHostName:8088/

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

Through this other connection, you could stop, modify or remove the HTML adaptor MBean using port 8082. In that case, your original browser will have to use http://localhost:8088/ as well to connect. Instead, we will manage the minimal agent from this other machine.

Instantiating MBeans with Constructors

1. From the browser on the other machine, go to the 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 given at the bottom of the page. The MBean name is also given: 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 will be appended to the bottom of the page. Scroll down and go to the MBean view with the provided link.

   Since 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 original browser window, click in the filter field and hit "Return" to refresh the agent view. Click on the new MBean's name and set its reload period to 15. Back on the other machine, type in a different string for the State attribute and click "Apply".

   On the original machine, you should see the MBean's attributes get updated when the MBean view is periodically reloaded.

4. On the other machine, click the reset operation button at the bottom of the MBean view page. This brings up the operation result page which indicates the success of the operation.

   This page also gives 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 original machine after it reloads.

The browser on the other machine is no longer needed, and we can remove the HTML adaptor on port 8088.

Unregistering MBeans

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

   Domain:	Communications
   Keys:	protocol=html,port=8088
   Java Class:	leave blank
   Class Loader:	leave blank

2. Select "Unregister" from the drop down menu and click the "Send Request" button. The result then appears at the bottom of the page.

   You can also unregister an MBean directly from its MBean view: just click the "Unregister" button on the upper right hand-side of the page.

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.

Preparation

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.

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 wild-card 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) finds all object names which contain that subset of keys

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

Quitting

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