Introduction

In this article we will go through a simple example of using Java virtualization in the addNumbers example program which is supplied with Rational¬ģ Integration Tester.

By the end of it you will be familiar with the various components involved in Java virtualization and how they interact.  You should be confident that you can virtualize your own Java applications.

This guide assumes that you have good knowledge of using Rational Integration Tester (RIT) and it is based on using a Windows system. It should be fairly simple to adapt the instructions for non-Windows systems.
Prerequisites:

  • Rational Integration Tester 9.0.1.1 or newer
  • Rational Test Control Panel (RTCP) 9.0.1 or newer
  • Network access from RIT to RTCP

Use this guide in conjunction with the technote: Diagnosing Java Virtualization Agent recording issues, and the Knowledge Center: Working with the Java method transport

Note that the sample addNumbers programs were changed in RIT version 9.0.1.1.  This version should be used in order to match the instructions.  Older versions can be used but screen images will vary.


Installation

The first task is to download the driver archive from the RTCP Tools page:


Tool

Extract all of these files to a folder of your choice, in this case we will use C:\JavaVirtualization.

Edit registration.xml to connect to your RTCP server.
By default, RTCP exports configuration files with its own hostname in there so you might need to change it.

server base-url="http://myRTCPServer:7819/RTCP"

Modify the addNumbers client program
Navigate to the examples folder of your RIT installation.

On Windows typically: C:\Program Files\IBM\RationalIntegrationTester\examples

On non-Windows typically: /opt/IBM/RationalIntegrationTester/examples

In the addnumbersclient folder, make a backup copy of startup.bat.

Edit startup.bat to add the Java Agent into the Java execution line as follows:

%JAVA_HOME%\bin\java %NET_PROPS% %SSL_PROPS%
-javaagent:C:\JavaVirtualization\greenhat.javaagent.jar -jar AddNumbersClient.jar

Ensure that it matches the folder location where the files were extracted to.


Verifying the Agent

The next step is to verify that the Agent can communicate with RTCP and that it appears in the Agents page.

Run startup.bat and you should see the addNumbers client window launch. The command line output will be similar to the following:

Jul 14, 2016 12:09:55 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: RIT Version: 9.0.0.1
Jul 14, 2016 12:09:55 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: Loading configuration from file:/C:/JavaVirtualization/registration.xml
Jul 14, 2016 12:09:55 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: HTTP proxy injection not enabled for Java Agent
Jul 14, 2016 12:09:55 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: Excluding these packages: [org.hibernate, org.springframework]
Jul 14, 2016 12:09:55 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: Using asm transformer
Jul 14, 2016 12:10:01 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: Loaded classes have been baselined
Jul 14, 2016 12:10:01 PM com.ibm.rational.rit.javaagent.repackage.logging.appenders.JULAppender log
INFO: Command socket open on 57304

Go to the RTCP Agents page and you should see the Java Agent:


Java Agent in RTCP


Creating the RIT Project

Create a new RIT project and ensure that you can connect to RTCP in Project Settings.

This is essential as recording requests are sent to RTCP and go from there to the Agent.

Create a Service in the Logical view of Architecture School and within that add a Java Application.


Operation and Transport

Configure the Recording Studio tab to contain only the following addNumbers method:

com.greenhat.addnumbersclient.AddNumbersClient#invokeApi

For older versions of the addNumbers client use the following:

com.greenhat.addnumbersclient.AddNumbersClient#addTheNumbers

Uncheck the invocation option shown:


Record

This will record a single Java method. With a real-world application you will need to speak to the Java developer to find out which methods to intercept. If you attempt to record too many methods, the Java application will be greatly slowed down. You might record so many events that you will not be able to find the ones you are interested in, and RIT memory could be fully exhausted.

The physical resource can be configured to use a specific Java Agent. For this exercise we will allow any to be used so the Host and Instance Name can remain blank.


Blank Host and Instance


Recording

Right-click on the Java Application and add an event monitor.


Add event monitor

Start recording and check for any warnings if the yellow icon is shown; click it.


Recording Studio Warnings

Stop and start recording after rectifying the problem.

Verify that the Recording rule appears in RTCP by clicking Show Rules or the magnifier icon for the Agent:


Rule1

Note the Activity destination host and port.  This is the Recording Studio location that the Java Agent will attempt to send recorded events to.  By default RIT uses a random port number for incoming events to Recording Studio.

If you have firewall rules between the Java application and RIT, fix this port in RIT Library Manager as follows:


Recording Studio listen port

Start the addNumbers server process by running:

C:\Program Files\IBM\RationalIntegrationTester\examples\addnumbers\startup.bat

Click Start Service to run it.


addNumbers Service

Enter some numbers into the client and click the = button.


Client

View the events:


Recorded

Click on one to view the content below it.


Recorded2

You can see the two input integers and the result integer.
The other parameters are for addNumbers internal use.


Creating the Stub

We will now create a hard-coded stub from the two messages to enable us to intercept the method and substitute our own result value.

Select the two messages and save as a stub.


Stub1

Follow the wizard steps to create the stub under the operation named invokeApi.


Stub2

Give the stub a suitable name.


Stub3

Open the stub in Test Factory and see that filtering is configured to process only when the input matches the values recorded.

In this case it will process only for the default settings for the addNumbers client, so 88 + 45 input.


Stub

Note that the stub is set by default to use pass-through.  This means that when it receives values that do not match the filtering, it passes the event to the addNumbers server.

Change the output to give an incorrect answer to the sum.


Stub Reply


Running the Stub

Run the stub and note the Routing rule in RTCP.


Rule2

Keep the addNumbers server process running and send the same 88 + 45 request from the addNumbers client.

Note that the new response is sent by the stub for these inputs.  For other values pass-through is invoked and the correct addNumbers answer is returned by the server.


HitStub

So in this case, anything other than 88 + 45 will produce the right answer.

Here is the stub execution console.  You can click on the Message Case (validation passed) and Send Reply entries to launch the Message Difference window to see the run-time values.

 


StubRun


Troubleshooting

Refer to the technote which contains an excellent flow chart on diagnosing recording problems:
Diagnosing Java Virtualization Agent recording issues

Which Methods to Record
A common problem is knowing which Java methods to record. The developer is an essential resource here, but the Java Agent has a web interface which can also help.

The Agent starts an HTTP server on a dynamic port number to allow diagnostic connections. The port number is reported in the console of the application, for example:

INFO: Command socket open on 56364

In this case you would connect to the Agent using a browser on http://<agent_host>:56364


Agent web page

Click the loaded-classes link to list all classes loaded by the application.


Classes

Browse the list and click on a class to display the methods:


Click on a method to invoke it.


Invoke method

If you are recording you will see the events in Recording Studio with default parameter values.


This can assist you in deciding which methods will be practical to intercept.


Conclusion

The Java Agent provides an easy way to intercept and modify or simulate the behaviour of Java programs.
In order to use it you need to have a good understanding of the Java program and its method calls. If in doubt, contact the developer responsible.

4 comments on"Rational Integration Tester Java Virtualization Walk-through"

  1. Great write-up!

  2. Nice!

  3. Awesome write up. Easy to follow.

  4. SteveBachini February 03, 2017

    Updated to incorporate 9.0.1.1 changes to the addNumbers methods.

Join The Discussion

Your email address will not be published.