Chapter 6HTML 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 this chapter, we will use your browser to "manage" the
base agent and its MBeans. The HTML protocol adaptor outputs HTML pages that
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 to get information about the MBeans that it
has registered and to operate on them.
The HTML adaptor relies mostly on plain HTML. The only JavaScript that the generated pages contain are pop-up windows for displaying
information. Browsers that are not enabled for JavaScript might give an incompatibility
message and will not 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 chapter relies on the base agent that you will need to start first,
as explained in Chapter 5, Base Agent. Once you can connect to the
HTML protocol adaptor in the base agent, you are ready to begin these topics:
6.1 Agent View is the main page for managing
an agent through the HTML protocol adaptor.
6.2 MBean View exposes an MBean's management
interface.
The 6.3 Agent Administration enables you to instantiate
new MBeans, modify attributes and invoke operations, and select the MBeans
displayed in the agent view.
6.1 Agent View
The first page displayed by the HTML adaptor is always the agent view.
It initially contains a list of all registered MBeans. The following figure
shows the agent view for the base agent. It contains four MBeans: three communication
MBeans, one of which is the HTML adaptor, and the MBean server delegate. The
delegate is a special MBean explained in 6.1.2 MBean Server Delegate.
Figure 6-1 Initial Agent View of the Agent
 The text field for filtering by object name enables you to modify the
list of displayed MBeans. The filter string is initially *:*,
which displays all registered MBeans. 6.3.2 Filtering MBeans describes
how to use the filter. The agent's registered domain indicates 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 links to the agent administration
page (see 6.3 Agent Administration).
6.1.1 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 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 can be created and registered into new or existing domains and old
MBeans can be removed. These changes can also affect the functionality of
the agent. New agent services can be registered (or removed) as well. We will
demonstrate examples of dynamic management in 6.3.1 Instantiating and Managing MBeans.
6.1.2 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 (Java DMK) that is running,
and it represents the MBean server when sending notifications.
Notifications are events sent by MBeans. They are covered in detail
in Chapter 8, Notification Mechanism. Because 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 unregistrations.
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.
To View the MBean Server Delegate Information
Click the name of the delegate MBean to see its attributes. Version, vendor and identification information is listed in the table
of attributes.
Click the Back to Agent View link or use your browser's "Previous
page" function to return to the MBean list in the agent view.
6.2 MBean View
The MBean view has two functions: it
presents the management interface of the MBean and it enables you to 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 can interact with the MBean by reloading its attribute values, setting
new values, or invoking an operation.
To Display the MBean View
Display the agent view. This is the first page displayed by the HTML adaptor.
In the agent view, click on the object name of the HTML adaptor MBean: name=HTMLAdaptorServer in the default domain. This will display its MBean view.
6.2.1 Header and Description
As shown in Figure 6-2, the top part of the
page contains the description of the MBean and some controls for managing
it.
Figure 6-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 might or might 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. Initially, the reload period
is set to zero indicating that the contents of the MBean view are not automatically
refreshed. Clicking the Reload button forces 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.
Note - Use the Reload button of the MBean view instead
of the browser's reload page button. After some operations, such as applying
changes to attribute values, the browser's button will repost the form data,
inadvertently performing the same operation again. To avoid undesirable side
effects, always use the Reload button provided in the MBean
view.
To Set the Reload Period
Type a reload period of 5 and click the Reload button. Every five seconds the page will blink as it reloads.
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. You might 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 6.3.1 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.
6.2.2 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 can 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. Read-only attributes whose type supports
the toString method are also displayed. Enumerated
types that are concrete subclasses of com.sun.jdmk.Enumerated
are displayed as a menu with a pop-up selection list. Boolean attributes are
represented as true-false radio buttons. Finally, attributes with array types
are represented by a link to a page that displays the array values in a table.
If the attribute is writable, you can enter values for the array elements
to set them.
For the complete list of supported types, see the Javadoc API of the HtmlAdaptorServer class. If an attribute type is not supported,
this is indicated in place of its value. If there was an error when reading
an attribute's value, the table shows the name of the exception that was raised
and the message it contains.
The name of each attribute is a link that displays a window 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 description for standard MBean attributes. Figure 6-3
shows the attributes of the HTML adaptor with a description of the Active attribute.
Figure 6-3 MBean Attributes With a Description Window
 To View an Attribute Description
Click on an attribute name in the table of attributes to read its description. Because 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, type or replace its current value in the
text field and click the Apply button at the bottom of
the attributes table.
Note - Do not try to modify the attributes of the HTML protocol adaptor
here. See 6.3.1 Instantiating and Managing MBeans.
Because there is only one Apply button for all the
attributes, this systematically invokes the setter for all writable attributes,
whether or not their fields have actually been modified. This might affect
the MBean if setters have side effects, such as counting the number of modifications,
as in the SimpleStandard and SimpleDynamic examples given in Part I, Instrumentation Using MBeans
The HTML adaptor detects attributes of the ObjectName
type and provides a link to the view of the corresponding MBean. This link
is labeled view and is located just under the displayed
value of the object name. Because MBeans often need to reference other MBeans,
this provides a quick way of navigating through MBean hierarchies.
|