Super Prev Next

Eclipse RCP

Note: information in this Chapter is applicable only to the Enterprise Edition of Excelsior JET.

Since version 6.5, Excelsior JET provides a protected environment for running Eclipse RCP applications. You may compile your RCP application to a native code executable and distribute it without the original class/jar files. As a result, all those Java decompilers become useless to the malicious programmers and attackers simply because Java classes are not included in the end user installations.

At the same time, compilation to native code substantially improves the security and IP protection of Eclipse RCP applications, as the sensitive code and data get protected from reverse engineering (see Chapter Intellectual property protection), tampering with the OSGi bundles becomes impossible, and the exposure of security vulnerabilities is reduced.


Super Prev Next

Overview

At a glance, the usage of Excelsior JET for an RCP application looks as follows:

  1. You specify the RCP application directory /This is a directory to which the application was exported either by the Product Export Wizard of the Eclipse IDE or by an automated build process./ to the JET Optimizer
  2. The Optimizer compiles OSGi bundles (plugins) into a native executable and places it into that directory. The executable looks like the standard executable launcher of RCP applications but it contains the native compiled code.
  3. To prepare the application for deployment, you use the JetPackII tool (see Chapter Deployment automation) specifying the RCP application directory and an output directory. JetPackII replicates the structure of the original directory adding the necessary JET Runtime files and removing the class/jar files which are no longer required.


Super Prev Next

The main functionality

As a result, you create the RCP application directory that can be deployed to end user systems. It has the same structure as the original one and contains the launcher executable. The two major differences are:

  1. the plugin classes/jars are not included – they are transformed into native code highly resistant to reverse engineering
  2. the compiled RCP application works without the JRE – no need to install (a particular version of) Java on end user systems

Note: If necessary, you or your end users may install other (non-compiled) plugins in the compiled RCP application as usual.


Super Prev Next

Extra features

In addition, you may author the application installer using the Installation Toolkit (see Excelsior Installer setup) bundled with Excelsior JET. Yet another Excelsior JET’s capability available to the developers of Eclipse RCP applications is download size reduction for the installation packages. Using the Java Runtime Slim-Down deployment model, you may leave the unused parts of the Java SE platform, such as Swing, out of the application installer  /The reduction can be achieved for small and medium-size applications that include a couple of thousands of classes. For large RCP applications, such as the Eclipse IDE, the removing of a few unused Java SE components will not reduce the total download size substantially./ .


Super Prev Next

Automated builds

To enable automated builds, you need to create two project files for each RCP application. One project is for the JET Optimizer to build the native executable and the other – for JetPackII to package the application, that is, to prepare it for deployment. The result of packaging is either a self-contained directory containing the application /It is similar to the directory created when the RCP application is exported but it is truly self-contained because the application no longer needs the JRE to run./ or a complete installation package powered by Excelsior Installer.

Once the projects have been created, you may use the command line interface to the JET Optimizer (see Invoking the compiler) and JetPackII (see xpack) to enable native compilation and packaging in an automated build process.

You use the JET Control Panel, to quickly set up the project for the JET Optimizer. The created project file has the extension .prj and can be used in automated builds with the command

    jc =p Compilation-project.prj

The JetPackII graphical tool helps you create the project for packaging. The project file has the extension .jpn and can be used in automated builds with the command

    xpack Packaging-project.jpn

Note: If you modify the RCP application, for example, add/remove some plugins, you do not need to create new projects nor edit the existing ones. When compiling the application, all changes will be automatically recognized and processed with the default settings. You open the projects with the JET graphical tools only if you need to change their settings.

The rest of this chapter contains a detailed description of how to use Excelsior JET for Eclipse RCP applications.


Super Prev Next

Compilation

To create a new project for compiling an RCP application, start the JET Control Panel and click Eclipse RCP Application on the Welcome Screen. The Start page will be displayed.


Super Prev Next

Step 1. Describing RCP application

On this page, browse for the directory to which your RCP application was exported either by the Product Export Wizard of the Eclipse IDE or by the existing automated build process.

Then, select the launcher executable of your RCP application /The Control Panel automatically detects it if there is the only launcher executable in the specified directory./ . Typically, the launcher executable comes with a configuration file that has the same name and the extension .ini. If the file exists, the Control Panel parses it and then creates the project for the RCP application.

At this point you may go directly to the page Finish (see Step 7. Building the executable) and compile the RCP application. It is recommended, however, to proceed to the next step and run the application in a special test mode using the JET Runtime.


Super Prev Next

Step 2. Test Run for RCP application

On the Test run page, you may run the application before compiling it to native executable.

Note: Test Run for large RCP applications may take a while, in particular, the application may start much longer than usual. That is expected behavior because the JET Runtime not only executes the application but also profiles it, which is useful for subsequent optimization. For more details, see Step 2: Performing a test run.

After the Test Run is over, you may go to the next page to check/modify the default settings for the application’s OSGi bundles (plugins).


Super Prev Next

Step 3. Settings for OSGi bundles

On the Classpath page, you may specify which bundles need to be protected by compiling to native code.


Super Prev Next

Grid

The central area of the page is occupied with a grid control. In the left column, the grid displays the names of the OSGi bundles marked with gray background. The other columns contain settings for the application’s bundles.

Bundles consisting of a single jar are displayed as single rows of the grid.

If a bundle contains several jars, it is displayed as follows:


Super Prev Next

Compilation settings for the bundles

If you need to protect the code from particular bundles, select the "all classes" option in the combo box from the Protect column. As a result, the contained classes will be native compiled and, therefore, will be omitted from the end user installation of your RCP application.

If, for some reasons, you want to keep certain OSGi bundles in bytecode form, adjust the settings in the respective grid rows as follows: select "auto-detect" in the Optimize column and "not required" in the Protect column. Such non-compiled bundles will be handled by the JIT compiler that comes with the JET Runtime.

Other controls available on this page are described in section Step 3: Selecting a compilation mode.


Super Prev Next

Step 4. Optimizer and Runtime options

The Options page does not contain any controls specific to Eclipse RCP applications. You may find a detailed description of this page in section Step 4: Setting options.


Super Prev Next

Step 5. Settings for the RCP executable

In the Executable settings pane of the Target page, you select the name of the native executable that will be created in the RCP application directory after compilation. By default, the Control Panel offers name Launcher-name-native but you may change it as you wish.

Also in this pane, you may enable protection of the application data (see Data protection) by checking the Encrypt strings and resources box.

Other controls available on this page are described in section Step 5: Specifying target settings.


Super Prev Next

Step 6. Application appearance

The page Appearance simply displays the splash screen image you selected when creating the RCP application. You cannot change it on this page. If you need to do that, you may replace the splash image in the RCP application before using Excelsior JET and the Control Panel will then automatically recognize the change.


Super Prev Next

Step 7. Building the executable

On the page Finish, click Build to compile the application. You will be prompted for saving the project. Using the filechooser select the name of the project file and the directory to which it will be placed. Note that the Optimizer will create temporary files (see Project Data Base) in that directory during compilation.

If you compile a large RCP application, it is not recommended to build it from within the Control Panel because less memory will be available to the JET Optimizer. Instead, click Create build script, select the project file name and directory and exit the Control Panel. Then launch the build_Project-name script created in the project directory.

As compilation is over, the native executable will appear in the RCP application directory you specified when creating the project.

Note: By default, the JET Control Panel automatically launches the resulting executable after compilation. It is done to collect profile data useful for reducing the application startup time. If you do not wish to enable the startup optimization, you may turn the profiling run off as described in section Configuring Startup Accelerator.


Super Prev Next

Packaging for deployment

To create a new project for packaging an RCP application, start JetPackII and click New Eclipse RCP Installation on the Welcome Screen. The Files page will be displayed.


Super Prev Next

Files to package

On this page, browse for the directory that contains the compiled RCP application. JetPackII will automatically add the necessary files to the package.

The structure and contents of the package are displayed in the Files to package pane. Notice that the plugin jars compiled to native code are not included in the installation package.

Later, if you need to add more files to the package or remove some previously added files, you may copy/remove them to/from the RCP application directory and JetPackII will automatically update the list of files to package. If you do that while JetPackII is running, select File/Refresh from the main menu to display the changes immediately.


Super Prev Next

Configuring the project

Other steps of creating the project are not specific to Eclipse RCP and described in Chapter Deployment automation.


Super Prev Next

Building the package

On the page Finish, select the full pathname to the installation package and click Create!. You will be prompted for saving the JetPackII project. Using the filechooser select the name of the project file and the directory to which it will be placed. Later you may use the project file to automatically build the installation as described in section xpack.

Depending on the install type you chose on the page Backend (see Step 5: Selecting a Back-End), JetPackII creates either application installer or self-contained directory in the specified location.


Super Prev Next

Known limitations

Excelsior JET imposes some limitations on the entire Eclipse RCP functionality and has some known issues:

  1. It is assumed that all bundles are placed in

          RCP-Directory/plugins subdirectory

    If your application is configured to use multiple bundle repositories, you may reconfigure it to use only the /plugins directory.

  2. The Eclipse RCP auto-update facility is not fully supported. Specifically, it is not possible to update pre-compiled bundles. This functionality is currently supported only for the bundles left in bytecode form.
  3. Compilation of very large Eclipse RCP applications (2x the size of the Eclipse IDE or larger) takes long or runs out of memory. See the Compilation takes way too long or the compiler terminates with an insufficient memory error for possible resolution.

These limitations will be removed in future versions of Excelsior JET.


Super Prev Next

FAQ

What are the supported versions of the Eclipse Runtime?

Excelsior JET 8.0 supports the Equinox OSGi runtime versions 3.1 through 3.6 out-of-the-box. In particular, it has been tested on the Galileo Release of the Eclipse Platform as well as on the previous Eclipse releases. More recent version of the Eclipse RCP will be added through Maintenance Packs available at

      http://www.excelsior-usa.com/jetdlupd.html

Versions prior to 3.1 are not supported.

Does Excelsior JET support the dynamic loading of plug-ins that were not pre-compiled?

Yes, of course. The JET Runtime includes a JIT compiler to dynamically load Java class files that were not pre-compiled. For more details, refer to Mixed Compilation Model.

Can I compile only certain OSGi bundles to native code and leave the rest intact?

Yes, it is possible. Configure the JET project as described in section Compilation settings for the bundles.


Super Prev Next

Throubleshooting


Super Prev Next

The Control Panel rejects the RCP application directory I specified

Reason: The directory is outdated or does not contain an RCP application launcher

Resolution: Export the latest version of the RCP application to this directory


Super Prev Next

Compilation takes way too long or the compiler terminates with an insufficient memory error

Reason: Under circumstances, the JET Optimizer does not scale well for very large RCP applications.

Resolution1: If you enabled the Global Optimizer, disable it as described in section Global Optimizer

Resolution2: Open the JET project file (.prj) with a text editor and modify it as follows:

  1. add the option -compilewithfixedheap+ to the beginning of the project
  2. increase the value of the COMPILERHEAP equation. For example, specify

          -compilerheap=1300m

    Note: your computer should have 2+ GB of RAM to build large applications

Resolution3: Disable native compilation for some of the application’s bundles which you do not need to protect as described in section Compilation settings for the bundles. Note, however, that it may negatively affect the application performance.