Note: information in this Chapter is applicable only to the Enterprise Edition of Excelsior JET.
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.
At a glance, the usage of Excelsior JET for an RCP application looks as follows:
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:
Note: If necessary, you or your end users may install other (non-compiled) plugins in the compiled RCP application as usual.
In addition, you may create a setup package for your application, powered by Excelsior Installer (see Excelsior Installer setup) bundled with Excelsior JET.
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 eithera 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
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.
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.
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.
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).
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:
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.
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.
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.
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.
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.
Other steps of creating the project are not specific to Eclipse RCP and described in Chapter Deployment automation.
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 will then create either an application installer or a self-contained directory at the specified location.
Excelsior JET imposes some limitations on the entire Eclipse RCP functionality and has some known issues:
If your application is configured to use multiple bundle repositories, you may reconfigure it to use only the /plugins directory.
These limitations will be removed in future versions of Excelsior JET.
What are the supported versions of the Eclipse Runtime?
Excelsior JET 15 supports the Equinox OSGi runtime and Eclipse RCP versions 3.3 through 4.7 out-of-the-box.
Versions prior to 3.3 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.
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
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 add the option -compilewithfixedheap+ to the beginning.
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.