9.2.1.1 Overview
9.2.1.2 Registering HTML Adaptor
9.2.1.3 HTML Page Generation
9.2.1.4 Viewing and Modifying MBean Attributes
9.2.1.5 Viewing Notifications
9.2.1.6 Searching for MBeans
A Multi-Protocol agent has common instrumentation that can be accessed through different protocols such as SNMP, TL1, HTML, CORBA, RMI, and HTTP. In case you want to access the Multi-Protocol agent using HTML Web browsers, the agent has to be created with an HTML Adaptor.
Once the Multi-Protocol agent with HTML adaptor is created and started, the MBean information of the agent is exposed by the HTML adaptor using HTML pages. These pages can be viewed from any Web browser using HTTP protocol. The attributes and operations of these MBeans can be viewed and manipulated using the HTML pages. Thus, the MBeans of the Multi-Protocol agent can be managed easily without the need for a separate manager application.
9.2.1.2 Registering HTML Adaptor
The HTML Adaptor is registered with the MBean server of the Multi-Protocol agent as an MBean and the HTML Adaptor exposes the MBean information of the Multi-Protocol agent with which it is registered. Therefore, before trying to register an HTML Adaptor, you must first create a Multi-Protocol agent. For this, please refer to the topic "Creating a Simple Multi-Protocol agent using JMX Compiler"
As the HTML Adaptor itself is registered as an MBean, its configuration parameters ( e.g. Port number, Authentication ) can also be viewed and changed through other protocol adaptors. The methods of registering the HTML Adaptor are explained in the ensuing sections.
The steps involved in creating a Multi-Protocol agent using the JMX Compiler are:
Creating a new project
Loading MIB in the JMX Compiler
Configuring the parameters for the Multi-Protocol agent
Generating code for the agent
Instrumenting the code
Compiling the code
Starting the Agent
While creating the Multi-Protocol agent, the HTML Adaptor can be registered with the Multi-Protocol agent in two ways:
9.2.1.2.1 Using UI
The HTML Adaptor can be added to the Multi-Protocol agent from the JMX compiler user interface before generating code for the agent. While creating a Multi-Protocol agent, the parameters for registering the HTML Adaptor can be configured from the JMX Compiler user interface. In case code has already been generated, it has to be regenerated after configuring the required parameters from the JMX Compiler UI. The steps to register the adaptor from the JMX compiler UI are given below:
Select Project->Settings menu option. The Settings dialog appears.
Select Adaptors->HTML->General option from the tree in the dialog.
Configure the following options in the General panel that appears on the right side:
Enable HTML Adaptor option.
Enter the Port Number (port at which HTML Adaptor must be started). By default the HTML adaptor is started at port number 8030.
Now, on generating code for the agent, code is generated to register the HTML adaptor with the MBean server. When the code is compiled and the Multi-Protocol agent is started, the HTML Adaptor is started at the specified port. The default port is 8030. The agent can be started from the JMX Compiler UI or from the command line, using the run.bat (for windows)/ run.sh (for Unix) file present in the <projectdir>/agent/bin directory.
Starting the agent from the command line offers you the flexibility of configuring port number by using command line options. The option [-hp html_port] allows you to specify the port at which the HTML Adaptor must be started.
9.2.1.2.2 Using APIs
The HTML adaptor can also be initialized by using API calls. This method can be used when code has been generated for the Multi-Protocol agent without enabling the HTML Adaptor. Here, the code required to enable the HTML adaptor has to added to the agent's main
file. Then, the code is compiled and the agent is started.
The com.adventnet.adaptors.html.HtmlAdaptor class acts as the HTML Adaptor. It implements the com.adventnet.adaptors.AbstractAdaptor. To initialize the HTML Adaptor using API calls, the following code has to be added to the registerAdventNetAdaptors() method of the agent main file.
private int htmlPort=8030;
private boolean isHtmlSSL=false;
private boolean isJarFile=false;
htmladaptor=newHtmlAdaptor();htmladaptor.setParentDir(agentDir);
htmladaptor.registerAuthentication();
htmladaptor.addHttpServerInterface(new HtmlAdaptorServerImpl());
name = "Adaptors:type=HTMLAdaptor";
server.registerMBean(htmladaptor, new ObjectName(name));
htmladaptor.setLogFile("agentDir/jmxprojects/<projectname>/agent/bin/HtmlNotif.ser");
AdventNet HTML Adaptor uses the Tomcat Web server. HtmlAdaptorServerImpl is the default implementation of HttpServerInterface for plugging in the Tomcat Server.
The htmlPort determines the port of the HTML Adaptor (8030 by default). isHtmlSSL is a boolean value which specifies if Secure sockets layer is used for communication. The topic "Using SSL for communication through HTML Adaptor" discusses about SSL in detail. isJarFile is a boolean value that specifies whether files are read from the jar.
The registerAuthentication() method can be used to enable authentication feature. For more information on Authentication feature please refer to the topic "Authentication in HTML Adaptor"
The setLogFile() method can be used to specify the name of the log file and the directory where it should be present. By default, it is generated as HtmlNotif.ser file in the ./jmxprojects/<projectname>/agent/bin directory . This is used for storing serialized notifications. If its file size exceeds 1000kb , HTMLNotif1.ser file will get generated.
The packages HtmlAdaptor and HtmlAdaptorServerImpl should be imported and this can be done by adding this code at the beginning of the agent main file:
import com.adventnet.adaptors.html.HtmlAdaptor;
import com.adventnet.adaptors.html.HtmlAdaptorServerImpl;
The following code (given in bold) must be added to the shutDownJmxAgent() method in the agent main file to stop the adaptor when the agent is shut down:
snmpadaptor.stopService();
htmladaptor.stopService();
MBeanServerFactory.releaseMBeanServer(server);
For registration, the HTML adaptor implements javax.management.MBeanRegistration interface. It is in the preRegister(...) method that the HTML adaptor actually gets registered. This preRegister method also allows the adaptor to perform any operations before getting registered with the MBean server.
The code snippet given above starts the HTML Adaptor at the port 8030.
Note: AdventNet HTML Adaptor uses Tomcat 3.2.4 Web server. In case you want to use a different Web server, please refer to the topic "Plugging in Your Own Web server".
9.2.1.3 Two Types of HTML Page Generation
Once the Multi-Protocol agent with HTML adaptor is created and started, you can connect to the HTML adaptor from a Web browser and view the agent information. For more information on starting the agent, please refer to the topic "Starting and stopping the Agent". The HTML adaptor exposes the agent information through HTML pages. These HTML pages are of two types:
9.2.1.3.1 Java Server Pages
The HTML Adaptor exposes the agent information in the form of HTML pages served by JSP For more information regarding the Java Server Pages refer to the topic "Using java server pages".
9.2.1.3.2 Dynamic HTML Pages
Dynamic HTML pages on the other hand are generated by the HTML adaptor as and when a query is received. These pages are generated at run time by the HTML Adaptor using the Jmx_dynamic servlet. These pages can be used to:
view and change MBean attributes
perform MBean operations
create and register MBeans at run time
These pages can also be customized according to the user's requirement. For more information, please refer to the topic " Using Dynamic HTML pages".
9.2.1.4 Viewing and Modifying MBean Attributes
To view the MBean attributes of the agent, follow the steps given below:
Start the Multi-Protocol agent. The agent can be started either from the JMX Compiler user interface or from the command line. For more information on starting the agent, please refer to the topic "Starting and stopping the Agent".
Open any Web browser . Specify the URL http://<agentHost>:<port number> for displaying the HTML pages using JSP. In case of dynamic HTML pages, specify the URL as http://<agentHost>:<port number>/Jmx_dyanmic. agentHost is the name of the machine where the agent is running and Port number specifies the port where the HTML adaptor is started. A sample URL: http://localhost:8030. Localhost may be used if the agent is running in the same machine where the browser is started. In case SSL support is enabled, the URL must be specified as https://<agentHost>:<portnumber>.
If Authentication is enabled, a login screen is displayed. Enter the User name and Password. Default user name and password are jmx and root respectively. Now, the HTML page with all the MBeans grouped under their respective domains is displayed.
Select the domain and click on the MBean whose attributes you want to view.
If the MBean is of a scalar group, then information regarding its attributes are displayed in a table format with five columns namely : Attribute Name, Attribute Type, Attribute Access, Attribute Value, and Attribute description. In case an attribute has a Read-Write access, then the Attribute value is displayed in an editable format and can be changed directly.
In case an attribute has values in an array, the Attribute value column has a link. On clicking this link, the values of the attribute are displayed in a separate table. In case the MBean attribute is of tabular data type, the values are displayed as a table.
New rows can be added to the table using the New Row button. Existing rows can be deleted by selecting the row and pressing the Delete Row button. Modifications can be done by selecting the corresponding row, changing the values in the editable text box and pressing the Save Values button.
Notifications are unsolicited messages sent by the agent to the managers when it encounters some critical events. Some of the critical events that trigger notifications are registering/ de-registering an MBean, performing SET on some MBean attribute (only when the Generate trap on SET option is enabled in the JMX Compiler UI), etc.
Notifications can also be triggered by configuring some services such as timer service (used to send predefined notifications at specified date and time) and monitor service (used to send notifications when the monitored attribute reaches a threshold value).
The notifications sent by the Multi-Protocol agent can be viewed through the HTML Adaptor. Both the JSP and dynamic HTML pages can be used to view these notifications.
9.2.1.5.1 Using JSP pages
Follow the steps given below to view the notifications sent by the agent through static HTML pages:
Start the agent.
Connect through HTML Adaptor using a Web browser by specifying the URL: http://<agentHost>:<portnumber>
Enter the user name and password in the login page. (This page is displayed only if Authentication is enabled. Default user name: jmx and password:root)
Select Alert option from the tree on the left side frame.
Notifications are listed in the form of a table on the right side frame.
9.2.1.5.2 Using Dynamic HTML Pages
Follow the steps given to view the notifications using the dynamic HTML pages:
Start the agent.
Connect through the HTML adaptor using a Web browser by specifying the URL: http://<agentHost>:<portnumber> /Jmx_dynamic
Enter the user name and password in the login page. (This page is displayed only if Authentication is enabled. Default user name: jmx and password:root)
Select View Notifications option under the Notifications section in the main page.
Notifications are listed in a separate page.
All the notifications sent by the agent are displayed in table format containing the following information: Sequence number, Type of Notification, Source from which the notification was received, Time stamp, Notification Message, and any other User data.
For more information on Notifications, please refer to the topic "Sending Notifications from MBeans".
Support to search for a particular MBean or a set of MBeans is available only in case of dynamic HTML pages. The HTML adaptor also allows you to search for a particular MBean or a set of MBeans, registered with the MBean server of the Multi-Protocol agent, based on the object name. The general syntax of the object name is : Domain name: Key=Value. You can search for both scalar and table MBeans using this option. T
9.2.1.6.1 Performing Search Operation
Click the Search Page link under the Search section. Now, the Search page is displayed. To perform the search follow the steps given below:
Enter the search string in the space provided. In case you want to view all the MBeans any one of the following can be used as the search string:
"*"
"*:*"
"*:*=*"
Select type of MBean to be searched, scalar, table or both.
Press the Search button.
9.2.1.6.2 Results of Search
All the MBeans that have the specified search string as part of their object name are listed. The MBeans are grouped according to their domains. Clicking an MBean will display the corresponding attribute page.
In case a non-admin user performs a search, those MBeans whose access is restricted to Admin users will not be displayed in the search result.
Let us take an example where you want to search for a scalar MBean with object name MyDomain:type=indexTable. The steps to be followed to perform the search is as follows:
Select Search Page option under Search section in the Main Page.
Enter the search string as MyDomain:type=indexTable (a part of the object name may also be used as search string, e.g., MyDomain:*=* or My*:type=*Table or indexTable).
Select the type of MBean as Scalar.
Press the Search button.
As the object name is specified as the search string, the corresponding MBean alone is listed. If only a part of the object name is used as shown, all MBeans having the search string as part of their object name will be displayed. Click the listed MBean to view its attributes.
Note: The search operation is case sensitive.