Installing a Java™ virtualization agent into a Java™ application

To enable the Java™ virtualization agent to capture Java™ method calls being used by a Java™ application, you must load the agent into the application's Java™ virtual machine (JVM).

About this task

To load the agent into the application's JVM, modify the startup parameters of the application. The Java virtualization agent comprises the following three JAR files, and an XML file for registration (registration.xml):

greenhat.javaagent.jar
greenhat.javaagent.ext.jar
greenhat.javaagent.linkage.jar

These JAR files provided in the JavaAgent package with HCL® Quality Server must always be in the same directory. The directory should be one that the application can access.

The registration.xml file in JavaAgent package need not be in the same directory as the JAR files, but by default, it is assumed that it is. If you place the registration.xml file in a different location, specify the path in the javaagent property in the following format: -javaagent:location of greenhat.javaagent.jar file=location of registration.xml file.

Note: In the following procedure, it is assumed that the files are present in the C:\RITJavaVirtualizationAgent directory. You must update the path as applicable to your environment.

Procedure

Set the javaagent property in the application environment in such a way that it points to the location of the greenhat.javaagent.jar file.
The procedure of setting the property depends on the environment in use. The following sections outline steps for setting the property in a few commonly used environments. If you are using an environment that is not listed, see the relevant documentation to learn how to set the property.
- For a Standalone Java application, perform either of the following actions:
  - Add the javaagent property to the command line that is used to launch the application. For example,
    java -javaagent:C:\RITJavaVirtualizationAgent\greenhat.javaagent.jar sample.MyClass
  - Before starting the Java application, set the JAVA_TOOLS_OPTIONS environment variable. For example,
    JAVA_TOOL_OPTIONS="-javaagent:C:\RITJavaVirtualizationAgent\greenhat.javaagent.jar"
    
    Note: When you set JAVA_TOOL_OPTIONS as a system environment variable, this option is used by all Java programs on your computer. This can affect application performance and can cause each Java program to register Java agents with HCL® Quality Server.
- For WebSphere Application Server, perform the following actions:
  1. In the Websphere Integration Solution Console, click Servers > Websphere Application Server and select the server to be configured.
  2. Click Java Process Management > Process definition > Java virtual machine.
  3. In the Generic JVM arguments field, add the following code:
    -javaagent:C:\RITJavaVirtualizationAgent\greenhat.javaagent.jar
- For Apache Tomcat, perform the following actions:
  1. Go to Apache Tomcat installation directory/bin.
  2. Depending on your environment, open either the setenv.bat file or the setenv.sh file in a text editor.
  3. Edit the CATALINA_OPTS variable to include the javaagent property.
    The following example shows how the property is set in the setenv.bat file:
    SET CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"C:\RITJavaVirtualizationAgent\greenhat.javaagent.jar"
- For Redhat JBoss server, perform the following actions:
  1. Go to RedHat JBoss install directory/bin.
  2. Depending on your environment, open either the standalone.conf.bat file or the standalone.conf file in a text editor.
  3. Edit the JAVA_OPTS variable to include the javaagent property.
    The following example shows how the property is set in the standalone.conf.bat file:
    SET JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\RITJavaVirtualizationAgent\greenhat.javaagent.jar"
When you use the Java virtualization agent with an application server such as IBM® WebSphere® Application Server that has a Java 2 Security Manager, the agent might not run. In such cases, the application server might fail to start unless you configure the Security Manager correctly.
To configure a Java 2 Security Manager to work with the Java virtualization agent, add a permission of the following format to the server.policy file:
```
grant codeBase "file:C:/RITJavaVirtualizationAgent/*" 
{ 
permission java.security.AllPermission; 
};
```
Note: If you use the WebSphere Application Server, the server.policy file is located in ${was.install.root}/profiles/${appserver.name}/properties.
Restart the application or the server for the changes to take effect.

Results

The application environment is configured to use the Java virtualization agent. Before you can capture any Java™ method calls in the Recording Studio perspective, you must create a Java™ method transport in HCL OneTest™ API. For information about how to create a Java™ method transport, see Creating logical Java application resources.