9.6.1.1 Overview
9.6.1.2 Registering HTTP Connector
9.6.1.3 Testing the Agent Using MBean Browser
9.6.1.4 Testing the Agent Through Client APIs
A Multi-Protocol agent has common instrumentation that can be accessed through different protocols such as SNMP, TL1, HTML, CORBA, RMI, and HTTP. For accessing the agent information using HTTP protocol, the Multi-Protocol agent has to be created with an HTTP connector.
This topic guides you through the steps of creating a Multi-Protocol agent with HTTP Connector. Once the agent is created, you can test it using the MBean Browser or using client APIs.
9.6.1.2 Registering HTTP Connector
The HTTP Connector is registered with the MBean server of the agent as an MBean. It exposes the MBean information of the Multi-Protocol agent with which it is registered. Therefore, before trying to register an HTTP Connector, 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 HTTP Connector itself is registered with the MBean server 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 HTTP Connector 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 HTTP Connector can be registered with the Multi-Protocol agent in two ways:
9.6.1.2.1 Using UI
The HTTP Connector can be added to the Multi-Protocol agent by configuring the required parameters from the JMX compiler user interface before generating code for the agent. In case code has already been generated, then code has to be regenerated after configuring
the required parameters.
The steps to register the connector from the JMX compiler UI are given below:
Select Project->Settings menu option. The Settings dialog appears.
Select Adaptors->HTTP->General option from the tree in the dialog.
Configure the following options in the General panel that appears on the right side:
Enable HTTP Connector option.
Enter the Port Number (port at which HTTP Connector must be started). By default the port number is 8030
Now, on generating code for the agent , code is generated to register the HTTP Connector with the MBean server of the Multi-Protocol agent. When the code is compiled and the Multi-Protocol agent is started, the HTTP Connector is started at the specified port. The default port is 8050. The agent can be started from the JMX Compiler UI or from the command line using 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 using command line options. The option [-hcp http_port] allows you to specify the port at which the HTTP Connector must be started. For more information on command line options, please refer to the section "Starting and stopping the Agent".
9.6.1.2.2 Using APIs
The HTTP Connector can also be initialized by using API calls. This method can be used when the code has already been generated for the agent. Here, the code for registering the HTTP Connector can directly be added to the agent's main file. This code can be compiled and the agent can be started.
The com.adventnet.adaptors.http.HttpConnector class acts as the HTTP Connector. It implements the com.adventnet.adaptors.AbstractAdaptor class. To initialize the HTTP Connector using API calls, the following code has to be added to the registerAdventNetAdaptors() method of the agent's main file.
httpconnector= new HttpConnector();
httpconnector.setParentDir(agentDir);
httpconnector.addHttpServerInterface(new HttpConnectorServerImpl());
name = "Adaptors:type=HTTPConnector";
server.registerMBean(httpconnector, new ObjectName(name));
AdventNet HTTP Connector uses the Tomcat Web server. HttpConnectorServerImpl is the default implementation of HttpServerInterface for plugging in the Tomcat Server. You can also use your own Web server. For more information on this, please refer to the topic Plugging in Your Own Web Server.
The classes HttpConnector and HttpConnectorServerImpl also need to be imported and this can be done by adding the following code at the beginning of the agent main file:
import com.adventnet.adaptors.http.HttpConnector;
import com.adventnet.adaptors.http.HttpConnectorServerImpl;
The following code (given in bold) must be added to the method shutDownJMXAgent() in the agent main file to stop the adaptor when the agent is shut down:
snmpadaptor.stopService();
httpconnector.stopService();
MBeanServerFactory.releaseMBeanServer(server);
For registration, the HTTP Connector implements javax.management.MBeanRegistration interface. It is in the preRegister(...) method that the HTTP connector actually gets registered. This preRegister() method also allows the connector to perform any operations before getting registered with the MBean server. The code snippet given above starts the HTTP connector at the port 8050.
Note: AdventNet HTTP connector 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.6.1.3 Testing the Agent Using MBean Browser
Once the Multi-Protocol agent with HTTP connector is created, the attributes and operations associated with the MBeans are exposed through the HTTP connector. These can be viewed and manipulated using HTTP protocol.
This can be done either using the UI tool, MBean Browser, bundled with AdventNet Agent Toolkit or using the Client APIs. This section deals with testing the agent using MBean Browser.
9.6.1.3.1 Connecting to the Agent Through HTTP Connector
The MBean Browser is a UI tool that allows you to test the Multi-Protocol agent using RMI, CORBA, or HTTP protocol. To test the agent using HTTP protocol, you have to connect to the agent through the HTTP connector.
Once you connect to the agent through the HTTP connector, all MBeans registered with the MBean server of the Multi-Protocol agent are listed in the MBean Browser's GUI. You can now view the MBean's attributes, perform operations on the MBeans, view the notifications sent by the agent, and even create and register new MBeans with the MBean server.
Follow the steps given below to connect to the agent through HTTP connector:
Start MBean Browser from the Launcher or by executing the MBeanBrowser.bat/ MBeanBrowser.sh from the <Agent Toolkit Home>/bin directory.
Select Settings->Client Settings menu option. Enter the following the following details in the dialog that appears:
Client: Select the client through which you would like to connect to the server (select HTTP Client).
Host Name: Specify the machine name where the agent is running. If the agent is running in the same machine, specify Host Name as localhost.
Port Number: Specify the port in which the HTTP connector is running (default port is 8050).
If you created the agent with SSL support for HTTP connector, select Settings->HTTP SSL menu option and enter the following details in the dialog that appears:
Enable Use SSL option.
Select SSL tab and enter the details such as: Key store, Key Password, Type and Manager Algorithm.
Select Trusted Clients tab and enter the details such as: Trust Store, Key Password, Type, and Manager Algorithm.
Now, select Operations->Connect menu option.
In case Authentication is enabled, a dialog is displayed where you have to enter the user name and password. The default user name and password are root and public. Now, connection is established with the agent and all MBeans registered with the MBean server are listed in the left side tree of the MBean Browser.
9.6.1.3.2 Viewing MBean Attributes
Once you have connected to the agent using the HTTP Connector, as described in the previous section, all MBeans registered with the Multi-Protocol agent are grouped according to their respective Domains and listed under the root domain in the left side tree. The attributes and the operations of each MBean are listed as nodes.
Click the Attributes node of an MBean. The attributes of the MBean are displayed on the right frame.
If the MBean is a scalar, the attributes and their corresponding values are listed on the right frame.
Values of attributes having Read-Write access are displayed in editable format. Their values can be changed directly. Enter the new value for the attribute and press Submit button.
In case the MBean is of tabular data type, the table is displayed on the right frame. The index columns are highlighted.
New rows can be added to table MBeans using the Add Row button.
Existing rows can be modified or deleted by selecting a particular row in the table and clicking the Modify Row button or Delete Row button .
If an attribute's value is of type array, a button is displayed and on pressing the button, all the values are listed in a separate pop-up dialog.
When you connect to the Agent through the HTTP Connector, all the MBeans registered with the MBeans server are listed in the left hand side tree by default. The Filter MBean option can be used to restrict the MBeans that are listed in the tree view. For this you can use a filter condition such that only those MBeans having object names that satisfy the filter condition are displayed in the tree.
The syntax for the Object name is Domain:key=value. The filter condition may be a part of the object name such as:
Domain name alone. e.g., Adaptors:*
Here, all the MBeans registered under the domain "Adaptors" are listed
in the tree.
Key-value pair alone. e.g., *:type=AdiskTable
Here, all MBeans having the key-value pair "type=AdiskTable" are listed
in the tree eventhough they are registered under different domains.
Object name. e.g., JMImplementation:type=MBeanServerDelegate
Here, the MBean registered with object name specified (JMImplementation:type=MBeanServerDelegate)
alone is listed in the tree.
Follow the steps given below to filter the MBeans:
Enter the Filter condition at the top of the MBean tree. (The filter condition must resemble the format of the MBean's object name Domain:key=value.)
Press the Requery button at the bottom of the tree.
All MBeans with object names satisfying the filter condition specified are listed in the tree. To view all the MBeans enter the filter condition as *:*.
9.6.1.3.3 Performing Operations on MBeans
To view the operations available for an MBean, click the Operations node for the MBean from the tree. All operations associated with the MBean are displayed as buttons in the right frame. Press the corresponding button to perform the operation.
If the operation is a GET operation, the value retrieved is displayed in a pop-up dialog. If the operation is a SET operation, the dialog appears with a text field to enter the new value. Specify the value and press OK. This will perform the SET operation. Other operations such as Start service, Stop service, etc. are performed when the operation button is pressed.
9.6.1.3.4 Viewing Notifications Sent by the Agent
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.
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) also trigger notifications depending upon their
configurations.
Notifications sent by the Multi-Protocol agent can be viewed through the HTTP Connector. Follow the steps given below to view notifications using MBean Browser.
Select View -> Notifications menu option.
A dialog is displayed with the list of notifications.
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 additional User data, if any. The Remarks button at the bottom of the table can be used to view detailed information pertaining to a notification.
9.6.1.4 Testing the Agent Through Client APIs
The HTTP Connector of the agent acts as a server and exposes the agent information. In order to view this information AdventNet Agent Toolkit provides client side APIs. These APIs can be used to test or manage the Multi-Protocol agent through HTTP Connector.
AdventNet MBean Browser has been built using these client side APIs. They make the task of MBean management easier. They also support remote notifications allowing you to view the notifications sent by the agent.
The HttpClient API is present in the com.adventnet.adaptors.clients.http package. This class extends the com.adventnet.adaptors.clients.AbstractClient and implements the com.adventnet.adaptors.clients interface. This interface is a common interface to be implemented by all connector clients.
This HttpClient API has methods that allow you to do the following:
connect to the agent using the RMI Adaptor
query MBeans registered with the MBean server
get MBean attributes
set MBean attributes
listen to remote notifications
Please refer to the javadocs for more information on each method of HttpClient API.
The remote notifications can be viewed through the client side APIs by implementing the NotificationListenerInterface. The addNotificationListener method can be used to add the listener to any MBean registered with the MBean server of the Multi-Protocol agent. This hides the complexity involved in handling remote notifications and allows you to view the notifications easily.