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

1. Display the agent view.

   This is the first page displayed by the HTML adaptor.

2. 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.

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.

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

1. Type a reload period of 5 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/.

3. 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 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.

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

1. 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.

Do not try to modify the attributes of the HTML protocol adaptor here. See 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

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.

List of Operations

The last part of the MBean view contains all 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 name is a link to its description. Parameter names are also active links that display a window with a description. 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 6–4 MBean Operations With a Description Window (Partial View)

We will not perform any operations on this MBean until after a brief explanation in Instantiating and Managing MBeans.

To perform an operation, fill in any and all parameter values in the corresponding text fields and click the operation's button. The HTML adaptor displays a page with the result of the operation, either the return value if successful or the reason why the operation was unsuccessful.