Super Prev Next

Tomcat Web applications

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

Since version 7.0, 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.


Super Prev Next

Overview

At a glance, the usage of Excelsior JET for Tomcat Web applications looks as follows:

  1. You specify Tomcat home directory to the JET Optimizer. The directory should contain the Tomcat Server with Web applications deployed into it.
  2. The Optimizer compiles Tomcat along with all deployed Web applications into a native executable and places it into bin-native/ subdirectory of the Tomcat directory. To start the compiled Tomcat Server, you may simply run the created executable.
  3. To prepare the Web application(s) for distribution, you use the JetPackII tool (see Chapter Deployment automation), specifying the Tomcat home directory and an output directory. JetPackII replicates the structure of the original directory adding the necessary JET Runtime files and omitting the class/WAR files which are no longer required.


Super Prev Next

The main functionality

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:

  1. the class/WAR files are not included as they were transformed into native code
  2. the compiled Tomcat and Web application work without the JDK – no need to install (a particular version of) Java on target systems

Note: If necessary, you may deploy other (non-compiled) Web applications on the compiled Tomcat Server as usual.


Super Prev Next

Extra features

In addition, you may author the application installer using the Installation Toolkit (see Excelsior Installer setup) that comes with Excelsior JET.

Yet another Excelsior JET’s capability available to the developers of Web applications is reduction of the install package size. Using the Java Runtime Slim-Down deployment model, you may bundle a light version of Java runtime with Tomcat leaving 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 Web applications, the removal of unused Java SE API classes will not make much difference./ .


Super Prev Next

Automated builds

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

    xpack Packaging-project.jpn

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.


Super Prev Next

Compilation

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.


Super Prev Next

Step 1. Describing Web applications

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.


Super Prev Next

Tomcat customization

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. You may find an example of the Tomcat main class in the subdirectory samples/TomcatCustomization of your Excelsior JET installation directory.


Super Prev Next

Troubleshooting

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 Throubleshooting. 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.


Super Prev Next

Step 2. Test Run for Web applications

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, the initial response time of a large Web application may be lower than usual. That is expected behavior because the JET Runtime not only executes the applications but also profiles them, 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.


Super Prev Next

Step 3. Settings for Web applications

On the Classpath page, you may specify which classes, jars, or WAR files 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 where the Control Panel shows the Tomcat directory contents organized as a set of sections.

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:


Super Prev Next

Compilation settings

If you need to protect a particular Web application, 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, omitted from the end user installation of your Tomcat Web application.

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.

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 Tomcat Web applications. You may find a detailed description of this page in section Step 4: Setting options.


Super Prev Next

Step 5. Settings for the Tomcat executable

In the Executable settings pane of the Target page, you select the name of the native executable that will be created after compilation in Tomcat-home/bin-native/ directory. The Control Panel offers some default name for the executable but you may change it, if necessary. Also in this pane, you may enable protection of the application data (see Data protection) by checking the Encrypt strings and resources box.

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.


Super Prev Next

Step 6. Application appearance

This page is not available under Linux.


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 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.


Super Prev Next

Packaging for distribution

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.


Super Prev Next

Files to package

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.


Super Prev Next

Configuring the project

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.


Super Prev Next

Trial Run

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.


Super Prev Next

HTTP port

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. This will enable the user to specify a (valid) HTTP port number for the Tomcat Server installation (see Installer).

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

    my.app.http.port=port-number

to the conf\catalina.properties configuration file.


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 8.0 imposes the following limitations on the Apache Tomcat functionality:

  1. It is assumed that all Web applications must be deployed into a subdirectory of Tomcat-home. It may be webapps/ or another directory.

    If your Web applications are located outside of Tomcat-home, you should reconfigure their deployment location to use Excelsior JET.

  2. As Web applications are compiled together with Tomcat into one executable, hot re-deployment of a running pre-compiled application is not possible.

    You would need to stop Tomcat, replace the executable, and start it again.

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


Super Prev Next

FAQ

What are the supported versions of Apache Tomcat?

Excelsior JET 8.0 supports Apache Tomcat 5.0.x /Starting from version 5.0.1/ , 5.5.x, and 6.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.


Super Prev Next

Throubleshooting


Super Prev Next

The Control Panel rejects the Tomcat directory I select

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


Super Prev Next

JetPackII rejects the Tomcat directory I select

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


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 Web 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 jars which you do not need to protect as described in section Compilation settings. Note, however, that it may negatively affect the application performance.