Note: information in this Chapter is applicable only to the Enterprise and Embedded Editions of Excelsior JET.
Excelsior JET enables you to protect Apache Tomcat Web applications from decompilation.
You may compile the Tomcat Server along with your Web application to a native code executable and distribute it without the original class/WAR 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 Tomcat Web applications, as the sensitive code gets protected from reverse engineering (see Chapter Intellectual property protection) and the exposure of security vulnerabilities is reduced.
At a glance, the usage of Excelsior JET for Tomcat Web applications looks as follows:
As a result, you create the Tomcat directory with the deployed Web applications that can be distributed to end users. It has the same structure as the original one, contains the compiled executable and, optionally, standard Tomcat scripts. The two major differences are:
Note: If necessary, you may deploy other (non-compiled) Web applications on the compiled Tomcat Server as usual.
In addition, you may create a setup package for your Web application, powered by Excelsior Installer (see Excelsior Installer setup) that comes with Excelsior JET. In particular, you may configure the setup to install the compiled Tomcat as a Windows service and run it immediately after installation.
To enable automated builds, you need to create two project files. 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 distribution.
The result of packaging is either a self-contained directory with the application /It is similar to the Tomcat directory but is truly self-contained because the compiled Tomcat no longer needs the JDK 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 remove/modify the Web applications located in the Tomcat directory or deploy a new application, you do not need to create new projects nor edit the existing ones. When compiling Tomcat, 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 Tomcat Web applications.
To create a new project for compiling Tomcat Web application(s), start the JET Control Panel and click Tomcat Web application on the Welcome Screen. The Start page will be displayed.
On this page, select the Tomcat home directory that contains the Tomcat Server and Web application(s) you want to compile. The Control Panel scans the specified directory and displays the detected Tomcat version and the names of found Web applications in the Tomcat Server and Web applications pane.
At this point you may go directly to the page Finish (see Step 7. Building the executable) and compile Tomcat along with the Web applications. It is recommended, however, to proceed to the next step and run the application in a special test mode using the JET Runtime as described in section Step 2. Test Run for Web applications.
When developing Web applications running on Tomcat, you may have changed the default Tomcat bootstrap sequence, used your own main class for the Tomcat Server and so on. If that is the case, you need to describe the modifications when creating the project.
Click Customize Tomcat to open the Tomcat customization dialog where you may add more jars files/directories to the classpath, change the default Tomcat entry point – the main class, and specify extra VM options. If you run the Tomcat Server as a Windows service and wish to customize the service initialization and termination, you may also specify your own service main class (see Excelsior WinService API) in place of the default service main used by the JET Runtime for Tomcat. Examples of custom Tomcat main and service main classes may be found in the subdirectory samples/TomcatCustomization of your JET installation directory.
As a result of the Tomcat directory scanning, the Control Panel may detect severe errors that would block native compilation of Tomcat unless they are corrected. For example, if the directory contains an ancient version of Tomcat not supported by Excelsior JET or the directory structure is corrupted, the creation of a native executable is not possible.
If such errors are displayed in the Tomcat Server and Web applications pane, you need to fix them to proceed to the next steps as described in section Troubleshooting. Note that you may do that without exiting the Control Panel - just click the Refresh button after the errors are fixed and the scan procedure will be repeated.
On the page Test run, you may run the Tomcat Server and your Web application(s) on the JET Runtime before native compiling them.
Note: During Test Run, throughput of a large Web application may be lower 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 Web applications.
On the Classpath page, you may specify which classes, jars, or WAR files need to be protected by compiling to native code.
Each Web application deployed to the Tomcat Server is displayed as a separate section. The other sections are:
In the left column, the classpath grid displays the names of sections marked with gray background. The other columns contain settings for the jars, WAR files, or directories that belong to the section.
Sections consisting of a single file or directory are displayed as single rows of the grid. If a section contains several jars, e.g. an application WAR file or directory, it is displayed as follows:
If, for some reasons, you want to keep certain applications 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 jars will be handled by the JIT compiler that comes with the JET Runtime.
In the Pack into exe column, you choose how to handle resource files from this classpath entry. Note that in case of Tomcat applications, the resource packing functionality (see Resource packing) has two noticeable additions:
Other controls available on this page are described in section Step 3: Selecting a compilation mode.
If you do not want your end users to inspect or modify the Tomcat configuration files – those located in Tomcat-home/conf/ – you may tell the JET Optimizer to place them into the executable so the files will not appear in conf/ subdirectory of end user installations of your Web application. For that, check the Hide Tomcat configuration files box in the Misc pane.
If you use standard Tomcat scripts from Tomcat-home/bin/, such as startup, shutdown, etc., and wish to continue using them with the compiled Tomcat, check the Generate standard Tomcat scripts box in the Misc pane. As a result, the scripts working with the compiled Tomcat will be created in Tomcat-home/bin-native/ along with the executable.
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 Web 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 build_Project-name script created in the project directory.
As compilation is over, the native executable will appear in the bin-native/ subdirectory of the Tomcat 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 startup time of the Tomcat server. 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 the compiled Web applications, start JetPackII and click New Tomcat installation on the Welcome Screen. The Files page will be displayed.
On this page, browse for the Tomcat directory that you specified when compiling the Tomcat Server and Web applications. It should contain bin-native/ subdirectory with the compiled executable. JetPackII will then 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 Web application jars compiled to native code are not included in the install 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 Tomcat 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 packaging Tomcat Web applications and described in Chapter Deployment automation. There are some minor differences which are given below.
The Trial Run procedure for Tomcat applications is mostly the same as for applications of other types (see Step 4: Performing a Trial Run).
When the Trial Run is over, press Ctrl+C in the console or launch the bin/shutdown script from the Trial Run directory to stop the compiled Tomcat Server. Note that JetPackII cannot automatically detect whether a Trial Run session for Tomcat Web applications has been completed successfully. To set the Trial Run status, JetPackII asks you to confirm that everything worked as expected and, just for sure, inspect the Tomcat log files created during Trial Run.
If you use Excelsior Installer, you may allow the user to change the Tomcat’s default HTTP port when installing your application. For that, check the Allow the user to change the default Tomcat port box on the Misc page of JetPackII. As a result, Excelsior Installer will display a dialog prompting the user to type the HTTP port number for the Tomcat Server installation.
Note: Before enabling this capability, you may need to correct Tomcat configuration files. Specifically, if the HTTP port number is explicitly set via the port attribute of the <Connector> tag in the conf\server.xml configuration file, you should replace the default value 8080 with a newly introduced VM option of your choice, e.g. my.app.http.port. JetPackII displays a detailed instruction on the necessary changes when you try to check the box.
If the user skips the step of changing the HTTP port number when installing your application, the default port will be 8080. You may define another default value by adding the line
to the conf\catalina.properties configuration file.
If you opted for Excelsior Installer on the page Backend (see Step 5: Selecting a Back-End), you may configure the setup to install the compiled Tomcat Server as a Windows service. For that, check the Install Tomcat as a service box on the page Services. Other controls displayed on the page are not specific to Tomcat and described in section Step 7: Specifying Installation Settings Of Windows Services.
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.
Excelsior JET 15.3 imposes the following limitations on the Apache Tomcat functionality:
If your Web applications are located outside of Tomcat-home, you should reconfigure their deployment location to use Excelsior JET.
You would need to stop Tomcat, replace the executable, and start it again.
These limitations may be removed in future versions of Excelsior JET.
What are the supported versions of Apache Tomcat?
Excelsior JET 15.3 supports Apache Tomcat 5.0.x /Starting from version 5.0.1/ , 5.5.x, 6.0.x, 7.0.x, 8.0.x, 8.5.x, 9.0.x
Versions prior to 5.0 will not be supported.
Can I deploy additional applications on the native compiled Tomcat?
Yes, you can do that using the standard Tomcat deployment procedure. Web applications deployed this way will be handled by the JIT compiler that comes with the JET Runtime. For more details, refer to Mixed Compilation Model.
Can I compile only certain Web applications to native code and leave the rest intact?
Yes, it is possible. Configure the JET project as described in section Compilation settings.
Reason: The directory is outdated or does not contain a Tomcat Server structure
Resolution: Rebuild the Tomcat directory, ensure that your Web applications are deployed to the Tomcat Server
Reason: The directory does not contain bin-native/ subdirectory with the compiled Tomcat Server.
Resolution: Recompile the Tomcat Server with Excelsior JET, ensuring that the right Tomcat directory is specified in the project
Reason: Under circumstances, the JET Optimizer does not scale well for very large Web applications.