9.4 RMI Adaptor

9.4.1 Overview

RMI

Remote Method Invocation (RMI) enables the programmer to create distributed applications ( involving communication between different Java technology-based applications). RMI enables these applications to invoke methods of remote Java objects from other Java virtual machines, possibly on different hosts. A Java technology-based program can make a call on a remote object once it obtains a reference to the remote object, either by looking up the remote object in the bootstrap naming service provided by RMI or by receiving the reference as an argument or a return value. A client can call a remote object in a server, and that server can also be a client of other remote objects.

RMI Adaptor

The Multi-Protocol agent has common instrumentation that can be accessed through various protocols such as HTML, HTTP, RMI, CORBA, SNMP, and TL1. The RMI Adaptor enables the Java manager to access the Multi-Protocol agent information using the Java Remote Method Invocation (RMI) system.

This topic discusses adding the RMI Adaptor to the Multi-Protocol agent and testing the agent through RMI Adaptor.

9.4.2 Registering RMI Adaptor

To create a Multi-Protocol agent with RMI Adaptor, the adaptor must be registered with the MBean server of the Multi-Protocol agent. This can be done either from the JMX Compiler user interface or using API calls. It is the com.adventnet.adaptors.rmi.RMIAdaptor that acts as the RMI Adaptor. It extends the AbstractAdaptor class present in the com.adventnet.adaptors package.

This RMI Adaptor itself is registered with the MBean server as an MBean. Therefore, its configuration parameters can also be viewed and changed through other protocol adaptors. The various methods of registering the RMI Adaptor are explained in the following sections.

9.4.2.1 Using JMX Compiler UI

The RMI Adaptor can be added to the Multi-Protocol agent from the JMX Compiler user interface before generating code for the agent. Follow the steps given below to register the RMI Adaptor from UI:

Select Project -> Settings menu option. Settings dialog appears.
Select Adaptors -> RMI option from the tree in the dialog.
Configure the following in the panel that appears on the right side:

Enable RMI Connector option.
Enter the Port Number (Port at which the RMI Adaptor is to be started.

Now, when code is generated for the agent, code required for registering the RMI Adaptor is also generated in the agent's main file. For more information on creating a Multi-Protocol agent, please refer to the topic Creating a Simple Agent using JMX Compiler in the Buliding Multi-Protocol agent section.

When this code is compiled and the agent is started, the RMI Adaptor is started at the specified port. The default port is 1099. The agent can be started directly 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).

Starting the agent from the command line offers additional flexibility of configuring the port number using the command line options. The command line option [-rp rmi_port] allows you to configure the port number before starting the agent.

For more information on command line options, please refer to the section Starting the Agent in the topic Testing the Agent.

9.4.2.2 Using API

The RMI Adaptor can also be registered using API calls. For this, the following code has to be added to the registerAdventNetAdaptors() method of the Agent's main file:

rmiadaptor = new RMIAdaptor();
name = "Adaptors:type=RMIAdaptor";
rmiadaptor.setPort(rmiPort);
server.registerMBean(rmiadaptor, new ObjectName(name));

The package com.adventnet.adaptors.rmi.RMIAdaptor must also be imported into the agent's main file. Inorder to stop the adaptor when the agent is shut down, the following code (shown in bold) has to be added to the shutDownJmxAgent() method of the agent's main file:

rmiadaptor.stopService();
MBeanServerFactory.releaseMBeanServer(server);

When this code is compiled and the agent is started, the RMI Adaptor is started at the specified port. The default port is 1099. The setPort(rmiPort) method can be used to change the port at which the adaptor is started.

Note: In case the port number specified for starting the agent is already occupied, the server creation fails

9.4.3 Authenticating the User While Accessing the Agent Through RMI Adaptor

The RMI adaptor exposes the attributes and operations of all the MBeans registered with the MBean server of the Multi-Protocol agent. You may restrict the access to the MBean information. This can be done using the Authentication feature. Here, the user is authenticated based on the user name and password.

The Authentication feature of RMI Adaptor is exposed as a Service MBean. It may be enabled either from the JMX Compiler user interface or by using API calls. Both the methods are explained in Enabling Authentication Support in Multi-Protocol agent.

9.4.4 Using SSL for Communication through RMI Adaptor

SSL (Secure Sockets Layer) protocol is used for authenticated and encrypted communication between clients and servers. AdventNet RMI adaptor supports SSL. Secure Sockets Layer has been implemented on both the server and the client side of the RMI Adaptor. Thus, secured connection can be established between the server and the client.

For SSL support in RMI adaptor, a keystore and keypassword is mandatory on the server side and a trust store and trust store password is mandatory on the client side.

9.4.4.1 Enabling SSL Support

SSL can be enabled for the RMI Adaptor either from the JMX Compiler UI while generating the agent code or by directly adding the required code in the generated agent main file.

9.4.4.1.1 From UI:

Follow the steps given below to enable SSL support for RMI Adaptor from the JMX Compiler UI:

Select Project->Settings menu option. The Settings dialog appears.
Select Adaptors-> RMI ->SSL option from the tree in the left frame of the Settings dialog.
Enable the 'SSL Support' option.
Enter the Key Store value. The default value present is 'etc/adventnetkey'. In case you are using a keystore other than the sample adventnetkey, use the Browse button to specify the location of the keystore.
Enter the Key Password corresponding to the keystore specified. The password for "adventnetkey" is "adventnet".
Enter the Server Socket Factory and Client Socket Factory values. The default values are com.adventnet.adaptors.rmi.RMISSLServerSocketFactory and com.adventnet.adaptors.rmi.RMISSLClientSocketFactory respectively.
Enter the port through which SSL communication takes place. The default SSL Port value of '0' means that any anonymous port is selected for communication.
If Client Authentication is required, select the 'Client Authentication' check box and specify the necessary Trust Store and Trust Store Password values. The default values for Trust Store and Trust Store Password are 'cacerts' and 'changeit' respectively.
Click on OK to complete the configuration.

9.4.4.1.2 Using API:

To provide SSL support for RMI Adaptor using API, add the following code to the registerAdventNetAdaptors() method of the agent's main file.

rmiadaptor.setSSLEnabled(true);

        Hashtable sslProps = new Hashtable();
        sslProps.put("keyStore","etc/adventnetkey");
        sslProps.put("keyStorePassword","adventnet");
        sslProps.put("trustStore","etc/cacerts");
        sslProps.put("trustStorePassword","changeit");
        sslProps.put("clientAuth","false"); // If Client Authentication is required, "true" should be passed as value
        sslProps.put("rmiServerSocketFactory","com.adventnet.adaptors.rmi.RMISSLServerSocketFactory");
        sslProps.put("rmiClientSocketFactory","com.adventnet.adaptors.rmi.RMISSLClientSocketFactory");
        sslProps.put("sslPort","0");
        rmiadaptor.setSSLProps(sslProps);

Warning: If keystore is not present in the corresponding directory, a file not found exception will be thrown while starting the agent.

9.4.4.2 Packages for SSL Support

For SSL support, the packages related to SSL can be downloaded from Sun Microsystems Inc, ( http://java.sun.com/products/jsse/ ). After downloading the packages, the jars (jsse.jar, jnet.jar, jcert.jar) from the JSSE package must be set in the classpath of the agent and setenv.bat. The setenv.bat will be available under the <Agent Toolkit Home>/bin directory and this will be used by MBean Browser for setting the tools classpath.

Note: For jdk 1.4 and above, the JSSE packages are bundled with jdk itself.

9.4.5 Testing the Multi-Protocol agent Through the RMI Client

The RMI Adaptor exposes the Multi-Protocol agent information through the RMI protocol. Therefore, the RMI Client can be used to test the Multi-Protocol agent. For this, either of the following can be used:

MBean Browser, a GUI test tool.
RMI Client APIs.

9.4.5.1 Using MBean Browser

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 RMI Adaptor, you have to connect to the agent through the RMI Adaptor. Once you connect to the agent through the RMI Adaptor, all MBeans registered with the MBean server of the Multi-Protocol agent are listed. Now, you can use the MBean Browser to do the following:

View the MBean's attributes.

Perform operations on the MBeans

View the notifications sent by the agent

Create and register new MBeans with the MBean server

Follow the steps given below to connect to the agent through RMI Adaptor:

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 details in the dialog that appears:

Client: Select the client through which you would like to connect to the server (select RMI 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 1099).

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. Now, connection is established with the agent through the RMI Adaptor and all MBeans registered with the MBean server are listed in the left side tree.

9.4.5.1.1 Viewing MBean Attributes

The MBeans registered with the Multi-Protocol agent are grouped according to the Domains and listed under the root domain in the tree. The attributes and the operations of an MBean are listed as nodes.

Click the Attributes node. 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. In case the MBean is of tabular data type, the table is displayed on the right frame. The index columns are highlighted.

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 click Submit button.

New rows can be added to table MBeans using the Add Row button. Select a row in the table and click the Modify Row button or Delete Row button to modify or delete the row. If an attribute's value is of type array, a button is displayed and on clicking the button, all the values are listed in a separate pop-up dialog.

In order to view only a few MBeans from the list displayed in the tree, you can use the Filter MBean option. Here, you can filter the MBeans based on the Object name of the MBeans. 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.)
Click 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.4.5.1.2 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. Click the 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 click OK. This performs the SET operation. Other operations such as Start service, Stop service, etc., are performed when the operation button is clicked.

You can also register/unregister an MBean using the Settings -> Register/Unregister MBean option.

9.4.5.1.3 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 JMX Notification 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 RMI Adaptor. 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.4.5.2 Using Client APIs

The RMI Adaptor acts as a server and exposes the agent information. In order to access and manipulate this information, AdventNet Agent Toolkit provides client-side APIs. The RMI Client APIs can be used by Java Managers to connect to the agent and access its information through the RMI Adaptor. These APIs make the task of MBean management easier. They also support remote notifications allowing you to view the notifications sent by the agent.

The RMIClient API is present in the com.adventnet.adaptors.clients.rmi 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 RMIClient 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 RMIClient API. AdventNet MBean Browser is also built using these APIs.

The remote notifications can be viewed through the client-side APIs by implementing the NotificationListenerInterface. A client-side application, which implements NotificationListener, can register to the MBeans in the MBean Server of the Multi-Protocol agent using the addNotificationListener. This hides the complexity involved in handling remote notifications and allows you to view the notifications.