About applying patches to IBM Rational Integration Tester

Answer

Purpose of document

This document is intended to give more information that can typically be contained in the README file which is included with the patch. This may be of interest to the reader, and may be of assistance when trouble shooting the installation of a patch.

It deals with the case of installing OSGi plugin JARs. Almost all RIT software patches are made up of one or more OSGi plugin JARs.

Introduction

This document does not deal with the installation of IBM Rational Integration Tester (RIT) or the upgrade of IBM Rational Integration Tester (RIT) but deals with the application of small patches which may be released to customers occasionally and is typically done to allow a customer early access to a particular enhancement or fix which will be made generally available in the next release.

A patch should always come with installation instructions in the form of a README file which accompanies the patch file. Typically this will contain details of how to install some new JAR files (which are OSGi plugins) for RIT. The document only deals with the installation of new OSGi plugin JAR files. Always consult the README associate with your patch as there may be other resources to upgrade.

The information in this document should be equally valid for installing a patch on RIT or RIT-Agent. RIT-Agent may be obtained as part of IBM Rational Test Virtualization Server (RTVS) or IBM Rational Performance Test Server (RPTS).

A typical patch

As an example we will show a patch which replaces this JAR

• com.ghc.example_1.900.0.v20160301_1410.jar

with this JAR

• com.ghc.example_1.900.0.v20160328_1525.jar

The README file which accompanies the patch should indicated the version of the software the patch is intended for and contain instructions along these lines:

1. Close RIT

2. Copy the new JAR file to C:\Program Files\IBM\IBMIMShared\plugins

3. Make a backup copy of:

C:\Program Files\IBM\RationalIntegrationTester\configuration\org.eclipse.equinox.simpleconfigurator\bundles.info

4. Edit it and replace line:

com.ghc.example,1.900.0.v20160301_1410,../IBMIMShared/plugins/com.ghc.example_1.900.0.v20160301_1410.jar,4,false

With the matching new line and file version:

com.ghc.example,1.900.0.v20160328_1525,../IBMIMShared/plugins/com.ghc.example_1.900.0.v20160328_1525.jar,4,false

5. Re-start first time from the command line with:

IntegrationTester.exe -clean -console

6. On the console window verify the patch is active by entering:

ss com.ghc.example

Note that the instructions do not suggest deleting the old JAR file as this is not necessary (and should be avoided lest other software is using the JAR or we have to restore the backup of bundles.info).

Patches often contain multiple JAR files, rather than just one as shown above (and so steps 4 and 6 will need to be executed multiple times).

There are sections below detailing steps 2, 4, 5 and 6 in greater detail.

The JAR filename

Typically RIT JAR files included in patches will be named following this convention:

[bundle-name]_[version]v[date]_[time].jar

And since the format of version is X.Y.Z and date is YYYYMMDD and time is HHMM in the 24 hour clock then this becomes:

[bundle-name]_X.Y.ZvYYYYMMDD

e.g. com.ghc.example_1.900.0.v20160328_1525.jar

Whilst not absolute rules you would normally expect that the replacement JAR has:

• The same bundle name as the original
• The same or a later version number
• A more recent date and time

Third party JAR files which are used as part of the RIT software may not conform to this naming standard.

The location of the IBM shared folder

The shared plugins live in a location which was selected during the installation of the first IBM product installed on the machine which made use of a shared resources directory.

The user may optionally change this location manually during installation but common locations are:

• C:\Program files\IBM\IBMIMShared
• C:\Program files (x86)\IBM\IBMIMShared
• /opt/IBM/IBMIMShared

Note that if the host operating system is a 64 bit version of Windows and the first IBM product installed using a shared folder was a 32-bit windows product and the default folder selected was therefore C:\Program files (x86)\IBM\IBMIMShared then that folder will also be the default for shared resources used by 64 bit applications including RIT.

To double check the location launch IBM Installation Manager and choose "modify". Select "IBM Rational Integration Tester" in the list of products (but do not click "Next"). The lower half of the display will show the "Shared Resources Directory".

The shared plugins folder is the plugins sub-folder of the IBM shared folder.


Step 2: Copying the JAR file

The file can be copied into the shared plugins folder using any reasonable method, including using copy and paste from Windows Explorer. Once this is done both the original and the new file should exist in the plugins sub-folder.

After copying the file it is a good idea to check that the new file has the same ownership and permissions as the old file.

On Windows use Windows File Explorer and right click the old JAR file and select "properties". Then look at the "security" tab. For each group or user listed in the top of the dialog click the group or use to see the associated permissions in the bottom of the dialog and make a note of the permissions. Now click the "Advanced" button to see the advanced dialog and on the "Owner" dialog make a note of the current owner. Now do the same for the new file, and if the permissions are different click the "Edit" button and correct the permissions. (Each tab on each dialog has it's own Edit button.)

On Linux or Unix open a command prompt and use ls -l to check the permissions, group and ownership of the two files. If these do not match then use chmod and chown to modify the settings for the new file.

The location of the RIT installation

The location of the RIT installation was configured when RIT was installed. Note that multiple copies of RIT may be installed on any given machine, and under those circumstances each will have it's own installation folder.

Typically the installation folder locations include:

• C:\Program Files\IBM\RationalIntgrationTester
• /opt/IBM/RationalIntegrationTester

To double check the location launch IBM Installation Manager and choose "modify". Select "IBM Rational Integration Tester" in the list of products (but do not click "Next"). The lower half of the display will show the "Installation Directory".

The format of the "bundles.info" file

IBM Rational Integration Tester (RIT) is an OSGi model product developed on the Eclipse platform. In common with all software based on version 3.4 or later of the Eclipse platform it has a file which lists the bundles (or software components) to load when the product starts and contains some sundry information about how those bundles should be loaded. This file is:

configuration/org.eclipse.equinox.simpleconfigurator/bundles.info

And this is found within the RIT installation folder.

After the first line of this file (which is typically #version=1) the lines each give details of a bundle in the format of a comma separated list of values. e.g.

com.ghc.a3,1.900.0.v20160224_2206,../IBMIMShared/plugins/com.ghc.a3_1.900.0.v20160224_2206.jar,4,false

There are 5 elements to that list which break down as:

1: The bundle symbolic name
e.g. com.ghc.a3

2: The version number of the bundle
e.g. 1.900.0.v20160224_2206

3: The JAR file location
e.g. ../IBMIMShared/plugins/com.ghc.a3_1.900.0.v20160224_2206.jar

4: The start level
e.g. 4

5: Should the bundle be started (by the Eclipse framework)
e.g. false

When installing a patch the values for the elements 1, 2, 4 and 5 should always be taken from the README instructions supplied. Sometimes the relative path in the third parameter will need to be modified.

The relative file path

Patch instructions typically assume that the location of the IBM Shared Folder is C:\Program files\IBM\IBMIMShared and that the location of the RIT installation folder is C:\Program Files\IBM\RationalIntgrationTester. This means that the relative path from the installation folder is ../IBMIMShared as shown at the start of the third parameter above.

Note that the relative path is given from the RIT installation folder (which is two folders above the bundles.info file).

If the location of either the IBM Shared Folder or the RIT installation folder is different on your system then you will need to adjust the path accordingly. For example if the IBM Shared Folder is C:\Program files (x86)\IBM\IBMIMShared but the RIT installation folder is still C:\Program Files\IBM\RationalIntgrationTester then the relative path of the IBM Shared Folder to the RIT installation folder will be ../../../Program%20Files%20(x86)/IBM/IMShared and the whole line in bundles.info will therefore read:

com.ghc.a3,1.900.0.v20160224_2206,../../../Program%20Files%20(x86)/IBM/IMShared/plugins/com.ghc.a3_1.900.0.v20160224_2206.jar,4,false

Rather than calculate the relative path it is simpler to copy the relative path from the line in the bundles.info file which is being replaced.

The path divider to use is / regardless of the host operating system.

Step 4: Editing the "bundles.info" file

After bundles.info has been backed up it can be edited in any text editor such as vi or Notepad. (The Notepad++ editor identified this file as having "ANSI Encoding" and hence Windows friendly CR LF line breaks.)

Typically a software patch contains replacement JARs so that for each JAR file there is one line to remove and one line to replace it with. The symbolic names of the line removed and the line should be the same. The relative file path (explained above) of the JAR file given in the fourth of the comma separated parameters should be the same before and after the change.

The above describes the only situation likely to occur during a patch. It is entirely possible to envisage a patch being produced in which an entirely new bundle was added to the bundles.info (to be used by another bundle which itself was being replaced). It is also possible to envisage a situation in which replacing one bundle could mean another bundle was no longer needed, but there would be no need to then remove a line from bundles.info (unless perhaps the fifth parameter were true).

Step 5: Restarting RIT cleanly with a console window

From version 9.0 of RIT onwards the product is launched using IntegrationTester.exe (on Windows) or an IntegrationTester binary (on other platforms). Earlier versions of RIT the launcher program is GHTester.exe (on Windows) or a GHTester binary (on other platforms). Typically no command line parameters are required.

When a patch has just been installed we need to add two command line switches.

• -console is a switch which causes the OSGi console to appear allowing the bundles loaded to be checked. On Windows the console appears in a new window, on other platforms the OSGi console appears in the window where the launch command was run.
• -clean is a switch which causes any data cached by the OSGi framework to be wiped clean. These files can be located in the configuration/ folder in the product install, in the users .eclipse/ or .rit8/ or .integrationtester/ folders all in the users home (or profile) folder.

The switches are the same as the Eclipse command line arguments given here.

The simplest way to add command line switches is from the command line. e.g on Windows

C:\> cd "C:\Program Files\IBM\RationalIntegrationTester"
C:\Program Files\IBM\RationalIntegrationTester_9000> IntegrationTester.exe -clean -console

or on Linux as root or the install user

$ cd /opt/IBM/RationalIntegrationTester

$ ./GHTester -clean -console

Step 6: Validating the patch installation

As RIT starts with the command line arguments from step 5 an OSGi console window will appear. The window should contain an osgi> prompt but sometimes it is not visible (because error output can also appear here) or the cursor might not be immediately after the prompt. Either press enter to get a prompt, or type any commands without a prompt.

The ss command will list the summary status of bundles. For example to see the summary status for the com.ghc.a3 bundle we use the command ss com.ghc.a3 and the first entry in the output shows the bundle information confirming that the bundle defined in bundles.info was loaded.

Further Reading

For more information on Eclipse bundle-management the interested reader may wish to take a look at the Developer Works article Understanding Eclipse's new bundle management mechanism.

For more information on the format of bundles.info see Configuring OSGi Framework Bundles in the Eclipse Virgo User Guide.