Chapter 2 The HTML Protocol Adaptor

A protocol adaptor provides access to MBeans through a communications protocol. A protocol adaptor enables management applications to perform management operations on a Java Dynamic Management Kit (Java DMK) agent. For a Java DMK agent to be manageable, it must contain at least one adaptor. However, an agent can contain many adaptors, allowing it to be managed remotely through various protocols.

The HTML protocol adaptor acts as an HTML server. It enables web browsers to access agents through the HTTP communications protocol, to manage all MBeans in the agent. The HTML adaptor can be used as a tool for debugging and speeding the development of agents. The HTML protocol adaptor is implemented as a dynamic MBean.

The HTML protocol adaptor provides the following main HTML pages for managing MBeans in an agent:

• Agent View: Provides a list of object names of all the MBeans registered in the agent.

• Agent Administration: Registers and unregisters MBeans in the agent.

• MBean View: Reads and writes MBean attributes and performs operations on MBeans in the agent.

The HTML page displayed is generated by the HTML adaptor and enables you to perform the following operations on MBeans in the agen.:

• Read or write the attributes of an MBean instance

• Perform an operation on an MBean instance

• Instantiate an MBean

• Delete an MBean

2.1 HTML Connections

The HTML adaptor is an instance of the com.sun.jdmk.comm.HtmlAdaptorServer MBean. Your agent application must instantiate this class, register the MBean, and explicitly start the MBean by invoking its start method to allow HTML connections. When the HTML protocol adaptor is started, it creates a TCP/IP socket, listens for manager connections, and waits for incoming requests. By default, the HTML adaptor listens for incoming requests on port 8082. You can change this default value by specifying a port number:

• In the object constructor

• By using the setPort method before starting the adaptor

If a manager tries to connect, the HtmlAdaptorServer creates a thread which receives and processes all subsequent requests from this manager. The number of managers is limited by the maxActiveClientCount property. The default value of the maxActiveClientCount is 10.

When an HtmlAdaptorServer is stopped, all current connections are interrupted (some requests might be terminated abruptly), and the TCP/IP socket is closed. The HtmlAdaptorServer can perform user authentication. The addUserAuthenticationInfo method and the removeUserAuthenticationInfo method can be used to manage users and their corresponding authentication information. The HTML server uses the Basic Authentication Scheme, as defined in RFC 1945, section 11.1, to authenticate clients which connect to the server.

Before connecting a web browser to an agent, you must make sure that:

• The agent is running on a system that you can access by using the HTTP protocol

• The agent contains an instance of an HTML adaptor

• The compiled MBean classes are stored at a location that is specified in the CLASSPATH environment variable of the agent

To connect a browser to an agent, open the page given by the following URL in a web browser.

http://host:port

In the URL above, host is the host name of the machine on which the agent is running. The port is the port number used by the HTML adaptor in the agent. The default port number is 8082.

2.2 Limitations of the HTML Protocol Adaptor

The HTML protocol adaptor has the following limitations:

• The minimum value for the reload period is 5 seconds. The value 0 defaults to no reloading.

• Arrays of classes are always displayed in read-only mode.

• Arrays of dimension 2 and higher are not fully expanded.

• Supported attribute types for reading and writing are as follows.

  • boolean boolean[] Boolean Boolean[]

  • byte Byte Byte[]

  • char char[] Character Character[]

  • Date Date[] (for example, July 21st, 2002 8:49:04 PM CEST)

  • double double[] Double Double[]

  • float float[] Float Float[]

  • int int[] Integer Integer[]

  • long Long Long[]

  • Number

  • javax.management.ObjectName javax.management.ObjectName[]

  • short Short Short[]

  • String String[]

  In addition, com.sun.jdmk.Enumerated is supported for readable attributes. Because com.sun.jdmk.Enumerated is an abstract class, only write-only attributes whose actual subclass is declared in the signature of its setter can be set through the HTML adaptor.

  ---

  Note –

  For unsupported read-only attribute types, if not null, the toString() method is called. If the getter of a read-only or a read-write attribute throws an exception, the thrown exception name and message are displayed. In this case, this attribute cannot be set through the HTML adaptor even if it is a read-write attribute.

  ---

• Supported operation and constructor parameter types are as follows:

  • boolean Boolean

  • byte Byte

  • char Character

  • Date (for example, July 21st, 2002 8:49:04 PM CEST)

  • double Double

  • float Float

  • int Integer

  • long Long

  • Number

  • javax.management.ObjectName

  • short Short

  • String

  ---

  Note –

  When reading a value of type Number, the server tries to convert it first to an Integer, then a Long, then a Float, and finally a Double. The server stops at the first primitive type that succeeds.

  Use the “Reload” button displayed in the HTML page of an MBean view rather than the reload button of the web browser. Otherwise, you might reinvoke the setters of all attributes, if this was your last action.

  ---