How to run Java or Eclipse RCP applications

Last edited on

Introduction

Java applications are run in a so called Java Virtual Machine (JVM). In order to start the JVM most Java application package ship with a program binary (a .exe file on Windows) to start the Java application. These program binaries are typically called launchers. (Sometimes, especially on Unix systems, a shell script is provided to start a Java application, but such shell scripts also use a launcher eventually.)

Several launchers from different groups and third parties exist, and the Java Runtime Environment (JRE) includes different launchers as well (<JRE>/bin/java, JRE/bin/javaw). Also, some developers choose to create proprietary launchers themselves.

Allowing Squish to hook into the application JVM

There are several mechanisms which can be use to let Squish hook into the JVM of the application. Most launchers only support one of these mechanisms (and unfortunately some do not support any of these mechanisms):

  1. Passing the path to the JVM .dll or shared library file to be used (instead of the standard .dll or shared library file, jvm.dll (Windows) or libjvm.dll (Unix).

  2. Passing arguments (so called "JVM args") to the JVM started by the launcher.

(Both mechanisms are supported for Eclipse equinox based launchers and the java/{javaw}} launchers of the JRE.)

Default hooking mechanism used by Squish

By default Squish hooks into Java applications by providing a custom JVM .dll/shared library, the Squish JVM.

The Squish JVM (SQUISHDIR\bin\jvm.dll on Windows) is used for hooking Java applications transparently with Eclipse-based applications and for applications which are being run via java.exe, javaw.exe, etc.

Using java/javaw/javaws launchers

To make the standard Java launchers (java, java.exe, javaw.exe, javaws, javaws.exe) use the Squish Java VM, Squish sets the environment variable JDK_ALTERNATE_VM to the directory of the Squish Java VM shared library file. The standard Java launchers support this environment variable and Squish should therefore be able to automatically hook into applications started via these launchers (also when using shell scripts or batch files).

Eclipse/RCP launcher

Eclipse/RCP applications should be detected by Squish automatically and the required parameters for the Eclipse launcher will be passed from Squish to that launcher.

The required parameter is -vm .

If a shell script or batch file is used to invoke the Eclipse launcher then the -vm parameter is passed to this shell script or batch file and must be passed on to the Eclipse launcher:

REM Run eclipse application
echo Starting Eclipse now
eclipse.exe "%1" "%2"

However, this only works if Squish recognizes the file system structure of an Eclipse/RCP application.

If Squish does not recognize the file system structure of an Eclipse/RCP application, then the alternative is to use the JDK_ALTERNATE_VM variable:

REM Run eclipse application
echo Starting Eclipse now
set _squish_jvm_arg=
if defined SQUISH_PREFIX set _squish_jvm_arg=-vm "%JDK_ALTERNATE_VM%"
eclipse.exe %_squish_jvm_arg%

Note that the -vm parameter should be passed before any other parameter.

Also note that Squish sets the environment variable JDK_ALTERNATE_VM.

Incompatible Eclipse launcher parameters

The parameters of the Eclipse launcher are usually stored in a file with the extension ".ini". For example in case of eclipse.exe the corresponding .ini file is eclipse.ini.

The following parameters cause failure to hook when specified in the .ini file:

The only known solution to automate an Eclipse based application with the above parameters in its .ini file are to remove those parameters from it.

The following steps demonstrate how to do this for the -vm parameter (without modifying the original eclipse.ini file):

Step 1: Create a copy of eclipse.exe and rename this copy to eclipse_squish.exe.

Step 2: Create a copy of eclipse.ini and rename this copy to eclipse_squish.ini.

Step 3: Remove the -vm parameter and the path following it from eclipse_squish.ini.

Step 4: Use eclipse_squish.exe as AUT (Application Under Test).

Third party launchers

See the documentation of your third party Java launcher tool on how to pass it the path to a different/the Squish Java VM, and also see Hooking via JVM Parameters .

Hooking via JVM Parameters