Super Prev Next

JET Control Panel

Excelsior JET Control Panel is a graphical tool that you use to quickly set up JET project files and compile your Java applications to native code. Its wizard-like interface guides you through the process of JET project creation step-by-step.


Super Prev Next

Before you begin

Before using Excelsior JET to compile your Java application, make sure that the application runs properly on the reference implementation of the Java platform, such as Oracle JRE 6.0.


Super Prev Next

Starting Excelsior JET Control Panel

To start the JET Control Panel, type

    jetcp

at the command prompt and press Enter.

A splash screen with a “Loading...” progress indicator will appear. When loading is over, the Welcome Screen will be displayed.

In the middle column, click:

The setup procedure is different for each type of project, thus you have to select it at the very beginning. You may change it later by selecting the respective item from the Project/Convert to menu.


Super Prev Next

JET Control Panel overview

Figure 1. Excelsior JET Control Panel

The user interface of JET Control Panel is organized as a series of “pages”. Each page represents one logical step in the process of setting up your project. As shown in Figure 1. Excelsior JET Control Panel, the most page space is occupied by page-specific controls, but there are also some common controls: sidebar on the left, main menu at the top, and help/navigation buttons in the bottom right corner.

You may navigate through the pages using the Next Page / Previous Page buttons, or go directly to a page by either clicking on the respective sidebar button or selecting that page in the Page menu.

Online help is available to assist you at any point. To display help information for the current page, click the Page Help button. To get help on a particular control, click the Context Help button. The mouse cursor will change shape to an arrow with a question-mark — click the control you want to learn about to get displayed the respective portion of the online help.


Super Prev Next

Working with projects

A JET project consists of configuration settings which together fully describes the final executable to be produced by the compiler. A project defines:

This information is stored in the project file which you create as described below in this chapter. JET project file names have the extension .prj


Super Prev Next

Creating a new project

You may create a new JET project by selecting the desired type of the application in the middle column of the Welcome Screen or by choosing those options in the File/New Project menu. If there is already an opened project, the JET Control Panel will prompt you to save it first.


Super Prev Next

Opening a project

You may open a previously created project by clicking the Open icon on the Welcome Screen or by selecting the File/Open menu item. A conventional file dialog will appear; use it to browse for the JET project file you want to open or select the desired project in the File name combo box.

Later you may quickly open an existing project by selecting it in the Recent Projects column of the Welcome Screen or using the File/Reopen menu item.

You may also open project files you created manually for jc, the JET command-line compiler (see Chapter JC reference.) However, the Control Panel recognizes only a subset of the project file syntax (see Project files), so it may refuse to open a project file that uses advanced features, such as preprocessing (see Control file preprocessing.)


Super Prev Next

Saving a project

You save a project by selecting the File/Save item from the Main Menu. When you save a newly created project for the first time, a conventional file dialog is displayed. Use it to specify the directory and name for your project. The default extension .prj is added to the file name automatically.

Note: during compilation the JET Optimizer will store Project Data Base into the project directory.


Super Prev Next

Saving a project under a different name

To save the current project under a different name or into another directory, select the File/Save As item from the Main Menu. A conventional file dialog will appear; use it to specify the new directory and/or name for your project.

Note: during compilation the JET Optimizer will store Project Data Base into the project directory.


Super Prev Next

Closing a project

You may close the current project by selecting the File/Close Project item from the main menu. This brings up the Welcome Screen. If the current project has been modified, the Control Panel will prompt you to save it first.


Super Prev Next

Step 1: Describing an application

This is the first step of creating a new project, where you describe your application to Excelsior JET Optimizer. To do that quickly, you can fill a simple two-question form placed in the Description form pane.

Note: if you are creating a project for a Tomcat or Eclipse RCP application, refer to sections Step 1. Describing Web applications or Step 1. Describing RCP application, respectively.


Super Prev Next

Description form

Note: if you use Excelsior JET Launcher to create a new project, all settings from the description form are made automatically so you do not need to fill it again. You may look through the form and the right-side panes to verify that the displayed settings are correct.


Super Prev Next

Question 1: Application’s working directory

Working directory of an application is the current system directory at the application’s start. When answering Question 1, you should specify the directory from which you launch your Java application on the system. For that, type the full path of the directory (e.g. ~/MyApp) in the entry field below, or click Browse to select it using a file dialog.

Note: the compiler will place the resulting executable into the specified directory to guarantee that the compiled application has the same working directory. Many Java applications should be run only from a particular directory, e.g. if they use relative path names to refer to classes or resources. That is why it is important to keep the same application’s working directory after compilation.

If you are pretty sure that your application runs from any directory, simply specify that where you want the compiler to place the executable.


Super Prev Next

Question 2: Classpath, main class, Java properties

Classpath is an ordered list of jar/zip files and directories which contain the application’s classes and resources. You specify the classpath when answering Question 2. In addition, you should select the application’s main class unless you want to produce a shared library. To complete the description, you may also set Java system properties required by your application, if any.

To specify all the settings at once, type or paste the command line you use to launch your application on a JVM, e.g.

    java -cp ./MyLib/MyApp.jar -Xmx128m MyMain

in the Command line field and click the Parse button to the right.

If you use an IDE, such as IntelliJ IDEA, JBuilder, or Eclipse, the java launcher command line is typically displayed at the top of a Run window that appears when you start your application from within the IDE. You can simply cut and paste it into the Command line field and then click the Parse button.

The JET Control Panel automatically extracts the parameters from the specified command so all you need to do is see if values of the settings displayed in the panes Classpath, Application main class, and Java system properties on the right appear to be correct. /Other settings specified in the command line, such as maximum heap size, are also parsed and added to the project. The Control Panel displays them on subsequent pages, for example, see Memory Management./

Note: if your application is launched with a complex script file that requires substitutions of environment variables, it is hard to figure out an exact command line. In such case, exit the Control Panel and use Excelsior JET Launcher to create a new project.

After completing the form, you may go to the next step unless you wish to modify some settings manually as the next section describes.


Super Prev Next

Manual setting

You can correct the description of your application, if necessary. For example, you may change values of Java system properties or add a new classpath entry. In such case, there is no need to fill the form again - you can use the controls placed on the right side of the page.


Super Prev Next

Editing classpath

The Classpath pane shows the application’s classpath. When looking for a class, the JET compiler inspects the classpath entries in the order they appear in the pane, from top to bottom.

Note: It is therefore important that you place classpath entries in the same order as a Java Virtual Machine accesses them when loading the application’s classes /This is the order in which classpath entries are listed in the java.class.path system property set by a "java" launcher./ . Otherwise, there is a chance that an other than intended version of a particular class will be used at run time. It may cause unpredictable changes of the application’s behavior. The same applies to resource files: the JET Runtime looks for them using the classpath so the order of classpath entries affects lookup of resources as well.

To edit the classpath, check Enable manual settings checkbox. These four buttons appear to the left of the Classpath pane:

Add   Move Up    
Remove   Move Down      

To add entries to the classpath, do the following:

  1. Click the Add button or right-click anywhere in the Classpath pane and then select Add classpath entries from the pop-up menu. A conventional file dialog will appear.
  2. Do one of the following:

To remove a classpath entry, do the following:

  1. Select an item you want to remove and click the Remove button or right-click the item and select Remove the entry from the pop-up menu. A confirmation box will appear.
  2. Click Yes to remove the entry or No if you decided to leave it in place.

To change the order of classpath entries, select the item you want to move and click the Move Up / Move Down buttons until the item is placed properly.


Super Prev Next

Specifying the main class

As you know, execution of a Java application starts with a public static void main (String[]) method. However, more than one class may contain such a method. When running your program on a JVM, you specify the name of the desired main class to the Java launcher as a command line parameter or in the manifest file of the jar file. Similarly, the JET Optimizer needs to know the name of the main class to make control passed to its main method on application startup.

You specify the main class as follows:

You do not need to select the main class if you want to build a shared library.


Super Prev Next

Setting Java system properties

To specify Java system properties required by your application (those passed to the Java launcher using the -D prefix), type them in the entry field from the Java System Properties pane, one on a line.

For instance, if you run your application using the command

    java -Dmyapp.debug -Dmyapp.log=/var/log/myapp MyApp

type the following in the field:

    myapp.debug
    myapp.log=/var/log/myapp


Super Prev Next

Step 2: Performing a test run

On this step, you can run your Java application before compiling it to native code /Excelsior JET Runtime will be used to execute application’s bytecodes/ which helps Excelsior JET:

To perform a test run, type application’s arguments in the field Arguments, if any, and click Run. The application’s output /Information printed into the standard output and error channels/ will be displayed in the Output pane. After the application terminates, the exit code will be also shown in this pane.

Note: the application is run in a special TEST MODE so disregard its modest start-up time and performance on this step.


Super Prev Next

Why is it?

It makes sense to perform a test run at least once when creating a new project. Doing so, you make sure that the description of your application is correct. For example, if you forgot to specify an application’s jar file on the previous step, the application will not work due to absence of some classes. You can see the respective exception message in the Output pane, add the missing jar file to the project, and run the application again. Thus, you will be sure that all project settings are correct when starting optimizing compilation on Step 7 (see Step 7: Compiling your application).

In addition, when you run the application, its execution profile is collected and saved into a file that will be added to the project automatically. The profile information will be used by:


Super Prev Next

Step 3: Selecting a compilation mode

Note: if you are creating a project for a Tomcat or Eclipse RCP application, first read sections Step 3. Settings for Web applications or Step 3. Settings for OSGi bundles, respectively.

The purpose of using the JET Optimizer varies for different Java applications. One may need to protect certain Java classes from decompilers, improve application performance, reduce download size and disk footprint of the installation or combine these requirements.

On this page, you choose a compilation mode suitable for your Java applications. The classpath grid and Global Optimizer controls (see Classpath grid and Global Optimizer) allow you to make the required settings. In addition, the Control Panel provides two "pre-defined" compilation modes which you can quickly select using optimization presets.


Super Prev Next

Optimization presets

To enable either pre-defined compilation mode, select "TYPICAL" or "SMART" radio button from the Optimization presets pane. Description of each option is given below.


Super Prev Next

Typical mode

This is the default compilation mode in which all classes from the application’s classpath are compiled into an executable. The standard Java classes need not be compiled because they are included in the JET Runtime (also in the native compiled form.)

Choosing the Typical mode, you enable most of performance optimizations and save compilation time. In addition, if you compile several executables, they will share the JET Runtime components. Note, however, that the Runtime includes all Java platform classes pre-compiled and it should be distributed "as is" /Any compatible Java implementation must include all the classes described in the Java SE platform specification even though a particular application never uses all of them/ . Even if your application actually uses only a small fraction of the Java SE API, size of the resulting installation package will be rather large.

If you need to reduce the download size and/or disk footprint of your application, consider the Smart mode.


Super Prev Next

Smart mode

The Smart mode relies on a simple observation: an application using a Java API actually requires only a part the API’s classes so there is no need to native compile the entire API implementation.

Choosing the Smart mode, you enable the Global Optimizer (see Global Optimizer) that detects the Java platform API classes which your application actually uses. Then, both application and used platform classes are compiled into a single executable. The remaining classes are kept in the bytecode form and handled by the JIT compiler, if the application tries to load them at run time. /Due to dynamic features of Java, the Global Optimizer cannot detect an exact set of used classes, e.g. those accessed from within native methods via JNI. That is why a few classes may be JITed at run time (see chapter Global Optimizer for details)/

Such mixed code packages are very effectively compressed by Excelsior Installer (see Excelsior Installer setup) so download size of the optimized Java applications is significantly reduced. In addition, the Global Optimizer improves start-up time and performance and reduces application disk footprint and memory usage. Note however that it takes more time and memory for compilation as compared with the Typical mode.


Super Prev Next

Custom mode

This option is selected automatically, if you change the default settings in the classpath grid or Global Optimizer controls described below.


Super Prev Next

Classpath grid

The classpath grid allows you to select how to compile your application at discretion of classpath entries (jar/zip files or directories.) That is, for each entry, you can enable/disable:

Note: by selecting an optimization preset (see Optimization presets), you reset the classpath grid in a default state. Therefore, you should use this control only if you need to modify the default settings.

The Classpath column shows the classpath entries you specified on Step 1. The next three columns display the properties, which you can change for each entry. You do that by selecting options from combo boxes placed into cells of the Protect, Optimize, and Pack into exe columns described in details below.


Super Prev Next

Code protection

If you need to protect your classes from decompilers, make sure that the respective classpath entries have the protection property enabled. It is displayed in Protect column under the name "all classes". For example, if your proprietary classes reside in a jar file, verify that protection is enabled for it. For sure, you can inspect which classes are contained in the jar file using the Class view dialog (see Class viewer.)

If you need to force protection for a certain classpath entry, select the "all classes" option from the combo box placed to the right.

Finally, if you have noticed that some entry has protection enabled but you actually do not need it, select the "not required" option from the respective combo box. It may reduce compilation time and the size of the resulting executable in some cases.


Super Prev Next

Selective optimization

By default, the JET Optimizer compiles all application’s classes into native code and all methods of every class are optimized for performance. For each classpath entry, this property is displayed in the Optimize column of the classpath grid under the name "all methods". For example, if you opted for the Typical optimization preset (see Optimization presets), all classpath entries have the "all methods" property enabled.

The other option you can select in this column is "auto-detect". It means that the Optimizer detects which classes from the classpath entry are used by the application and compiles the entry selectively leaving a part of classes in the bytecode form. It helps reduce compilation time and download size of the application /Significant reduction in download size is provided only if the Global Optimizer is turned on (see Global Optimizer)/ .

You may enable selective optimization for third-party APIs (jar files), if you are sure that your application uses only a small part of their implementing classes. However, it is not recommended to choose the "auto-detect" option for your own jar files, because, in general, the Optimizer cannot detect an exact set of used classes. The "missed" classes are handled by the JIT compiler at run time, which incurs some performance overheads.

Note that when you choose the Smart optimization preset (see Optimization presets), the Control Panel uses an heuristics to separate the classpath entries into the application part (your own classes) and API part (third-party classes). As a result, certain jar files related to the API part, have the "auto-detect" option enabled. If the heuristics proves to fail for some classpath entries, you can correct the settings using the combo boxes placed in the Optimize column.


Super Prev Next

Resource packing

Jar/zip files often contain resource files such as images, icons, media files, etc. By default, the JET Optimizer packs such files into the resulting executable. If selective optimization is enabled for a jar/zip file (see Code protection), the classes not compiled are also packed into the executable. As a result, original jar/zip files are no longer needed for the running application.

This is the default option displayed in the Pack into exe column under the name "auto-detect". Notice that it works only for jar/zip files so directories from the classpath are marked with "n/a" (not available) in this column.

Note: in most cases, you do not need to change the default setting. Other available options are considered advanced and described in section Resource packing.


Super Prev Next

Global Optimizer

The Global Optimizer provides higher performance and lower memory usage for the compiled application. In addition, the installation created for an executable built with the Global Optimizer has much smaller download size and disk footprint. In exchange, the Optimizer requires more time and memory to compile a Java application.

The Global Optimizer is enabled as a part of default settings for the Smart optimization preset (see Optimization presets). To enable it separately, select the "ON" option from the combo box placed in the Global Optimizer pane.

Important note: For optimal usage of the Global Optimizer, perform a test run for your application on the previous Step (see Step 2: Performing a test run). During a test run, application profile is automatically collected and then added to the project. The Optimizer will use it when creating the executable to achieve maximum performance for your Java application. Though test run is an optional step, it is recommended to perform it at least once for a new project.

For more details, consult Chapter Global Optimizer that presents an in-depth look at the Global Optimizer.


Super Prev Next

Inconsistency warnings

The information panel placed at the bottom of the Classpath page displays the number of inconsistency warnings detected by the Control Panel in the classpath. For instance, if two classes with the same full name are found in two different jar files from the classpath, class duplication warning is issued. Another typical example is absence of a referenced class. If the Control Panel detects that one class refers to another class that cannot be found in the classpath, class absence warning is issued.

If you want the Control Panel to analyze your project, click the Check consistency button on the right. It brings up the class view dialog that displays detailed information about each warning.


Super Prev Next

Class viewer

The class view dialog allows you to get information about:

Note that this viewer is provided for reference only and does not affect compilation in any way. You may open the class view dialog via the Project/View Classes menu.


Super Prev Next

Inspecting classpath entries

The Classpath pane on the left shows the application classpath, an ordered list of JAR/ZIP files and directories that include the application’s classes. You can inspect what classes and packages are contained in a classpath entry by expanding the entry’s node in this pane.


Super Prev Next

Examining import dependency

Import dependency of class A is a set of imported classes that includes

Import dependency of a package or classpath entry includes all import dependencies of the contained classes.

You need to examine the dependencies if you are going to compile your application into an executable and one or more dynamic libraries as described in chapter Dynamic Linking.

All classes and packages found in the classpath are displayed in the Classes pane. Each class or package name appears with a color tag displayed to the left. These tags indicate import dependencies between classes and packages as described below:

the class or entire package is marked by the user to examine its dependencies
the class or entire package is imported, that is, some classes marked by the user depend on it
the class or package is neither marked nor imported
the class is ignored because another class with the same full name was found earlier in the classpath or because this class belongs to the Java SE platform API. See Classpath inconsistencies for details
the package is partially imported, that is, it includes both imported and non-imported classes

When you open the class viewer for the first time, all class and package names have the tag displayed. Click on the tag of the class or package whose import dependency you want to see. As a result, the tag will change to the tag "selected" ( ) and the Control Panel will automatically mark all imported classes with the tag .

To cancel your selection, click the tag and the marking will be cleared. Note that you can also examine import dependency of an entire classpath entry by clicking on its tag in the Classpath pane. You can do the same actions using a pop-up menu: right-click the class, package, or classpath entry name and select the Mark item from the menu.


Super Prev Next

Classpath inconsistencies

The JET Control Panel can detect the following inconsistencies in the classpath:

If the Control Panel has detected any of such problems, the Warnings tab appears in the information area at the bottom of the dialog. Under this tab, the overall numbers of "problematic" classes are displayed for each type of inconsistency. Click the respective Details button on the right to display a dialog box with a list of involved classes.

Duplicated classes

When multiple classpath entries contain identically named class files, the entry listed in the classpath first prevails. As a result, the “overrides” tag is displayed next to the first occurrence of such a class in the Classpath pane. All other occurrences are displayed with the tags "overridden" and "ignored" .

To view the list of duplicated classes, do the following:

  1. Select the Warnings tab.
  2. Click the Details button next to the message “N duplicated classes”. A dialog box will appear.
  3. In the box, expand a class name to view the list of classpath entries that contain the duplicated classes.

    You can get this report in a plain text form: click the Copy to clipboard button and perform the paste operation in any text editor.

To resolve this issue, it is sufficient to check that the desired versions of duplicated classes appear in the classpath first. If necessary, you can reorder the classpath entries as described in section Editing classpath. After that, you may safely remove the overridden class files from the respective directories and JAR/ZIP files.

Conflicting classes

An application’s classpath should not contain classes from the Java SE platform API, because they are already included in the JET Runtime. When processing the classpath, the JET Optimizer automatically excludes such classes from compilation.

Conflicting classes are displayed with the "ignored" tag in the Classpath pane. In addition, classpath entries and packages that contain at least one conflicting class are marked with the “conflict” tag .

To inspect the list of conflicting classes, do the following:

  1. Select the Warnings tab.
  2. Click the Details button next to the message “N classes coinciding with Java SE API classes” to open a dialog box that displays the full list of conflicting classes.

    You can get this report in a plain text form: click the Copy to clipboard button and perform the paste operation in any text editor.

To resolve this inconsistency, remove all conflicting classes from the classpath. If such classes appear in third-party jars qualified as Endorsed Standard, you may create a new JET profile with Endorsed Standards Override.

Unresolved import

If a class A references another class not found in the classpath or among the platform classes, the “unresolved import” tag is displayed next to class A.

To browse the list of classes that have unresolved import dependencies, do the following:

  1. Select the Warnings tab.
  2. Click the Details button next to the message “N classes with unresolved import dependencies”. A dialog box will appear.
  3. Select the Unresolved tab to display the list of classes that have unresolved references. In the list, expand a class name to display the referenced classes not found.
  4. Select the Not Found tab to display the list of classes that are referenced by classes from in the classpath, but whose class files were not found.

    You can get these reports in a plain text form: click the Copy to clipboard button and perform the paste operation in any text editor.

To resolve this inconsistency, complete the classpath by adding directories or JAR/ZIP files that contain necessary classes. It may happen, however, that this problem is detected in a code that is not under your control, such as a third-party API or component. Fortunately, the JET Optimizer is able to compile the application even if it comprises classes that have unresolved references.

Note: The JET Runtime correctly handles the situation when a referenced class is not present at compile time but becomes available at run time. See Reflective shield for details.

To close this issue, you may file a complaint to the vendor that distributes software components with an incomplete set of Java class files.

Unresolved super classes

If class A extends another class (or implements an interface) which cannot be found in the classpath, the "unresolved super class" tag is displayed next to class A.

This is unfortunate because in such case, the JET Optimizer cannot compile class A into native code.

To browse the list of the concerned classes, do the following:

  1. Select the Warnings tab.
  2. Click the Details button next to the message “N classes with unresolved super classes”. A dialog box will appear.
  3. Select the Unresolved super classes tab to display the list of classes that have unresolved super classes. In the list, expand a class name to display the required super classes not found.
  4. Select the Not found super classes tab to display the list of super classes not found in the classpath. Expand the name of a super class to display the classes that extend it.

    You can get these reports in a plain text form: click the Copy to clipboard button and perform the paste operation in any text editor.

To resolve this serious issue, do complete the classpath by adding directories or JAR/ZIP files that contain necessary classes.

If, however, it is not possible, e.g. the required super class becomes available only at run time, the following happens:

  1. the classes that extend an absent class are packed into the executable in the bytecode form /Provided that the classes reside in a JAR/ZIP file from the classpath. If they come from a directory, you need to distribute such non-compiled classes along with the executable./
  2. if the application loads one of them, the JET Runtime compiles it on-the-fly using the JIT compiler (see chapter Mixed Compilation Model for details.)

This technique provides correct behavior of the running application, though some performance loss is possible.

Important note: classes that have unresolved super classes are never compiled into native code before execution and distributed in the bytecode form. As a result, Excelsior JET cannot protect them from decompilers. Use the class view dialog to make sure that the classes you need to protect are not affected.


Super Prev Next

Step 4: Setting options

On this step, you set various options of the JET compiler and Runtime, which affect performance and memory footprint of your application. The most important controls are available under the General tab, whereas the Advanced tab contains the settings that need to be changed only in rare cases.

Default values of the available options are suitable for a "typical application" so the controls are preset accordingly. Most probably, you will need to adjust the settings only after you get your application compiled and run. For example, you may wish to control its memory footprint or reduce the size of the resulting executable.


Super Prev Next

Optimizations

The optimizations implemented in the JET compiler are always enabled by default and most of them cannot be disabled at all. There are just two exceptions: allocation of objects on the stack, which may compromise scalability, and method inlining, which improves performance but also increases code size. You therefore have an option to disable stack allocation and adjust the criteria for inlining.


Super Prev Next

Allocating objects on the stack

As you know, the Java memory model has no stack objects — class instances put on the stack frame. All objects have to be allocated on the heap by the new operator and reclaimed by the garbage collector, even though the lifetimes of some objects are obvious. The JET compiler performs so called escape analysis to approximate object lifetimes and allocate some objects and small arrays on the stack where possible. As a result, compiled applications benefit from both faster object allocation and less intensive garbage collection.

This optimization may however result in higher consumption of stack memory by application’s threads. Therefore, in some cases, you need to increase the maximum stack size, which may compromise program’s scalability. If you are compiling a server-side Java application that runs thousands of threads simultaneously, you may wish to disable this optimization by unchecking the Allocate objects on the stack box.


Super Prev Next

Method inlining

When optimizing a Java program, the compiler often replaces method call statements with bodies of the methods to be called at run time. This optimization known as method inlining, improves application performance, especially when tiny methods are inlined such as get/set accessors. However, the inlining of larger methods increases code size and its impact on performance may be uncertain.

To control the aggressiveness of method inlining, select the desired level from the Inline expansion combo box. If you need to reduce the size of the executable, select the "Low" or "Tiny methods only" option. Note that it does not necessarily worsen application performance.


Super Prev Next

Memory Management


Super Prev Next

Maximum heap size

During application execution, the JET Runtime considers many factors, e.g. system workload, to control the Java heap size and collects garbage, when necessary.

Nevertheless, you may restrict the heap size by specifying an upper bound that the heap may not exceed at run time. For that, type it into the Maximum heap size field or drag the slider below. You may use suffixes “K” and “M” to denote kilobytes and megabytes, respectively.

Note: If the entered value is too small or too large, the warning icon is displayed next to the field until you correct the value appropriately.

To return to the default behavior, drag the slider to the leftmost position. The word “Adaptive” will be displayed in the Maximum heap size field.

See Maximum heap size for more information.


Super Prev Next

GC ratio

GC ratio is the percentage of execution time that the JET Runtime is allowed to spend for garbage collection. This setting effectively controls memory footprint because the greater GC ratio, the higher frequency of GC invocations, and, hence, the smaller Java heap needs to be allocated. At the same time, it may worsen performance to some extent because the greater GC ratio, the less time is left for execution of the application’s code. Thus, you may adjust GC ratio to set an optimal balance between the performance of your application and its memory footprint. See GC ratio for a detailed description of this technique.

GC ratio is measured in tenths of a percent, e.g. the default value equals 1.1%. To specify another value, type a fixed point number with one digit after the point into the GC ratio field or drag the slider below. The greatest value you can specify is 40.0%.

Note: If the entered value is too large or has a wrong syntax, the warning icon is displayed next to the field until you correct the value appropriately.

Though it’s not recommended, you can disable the mechanism. Drag the slider to the leftmost position, the word “Off” will be displayed in the GC ratio field.


Super Prev Next

Handling low memory

Under heavy system workload, your Java application may lack enough physical memory. This is the case, for example, if it runs simultaneously with another application that occupies a good part of total memory.

The JET Runtime invokes the garbage collector if it has detected the low memory state of the system. If that does not help, the Runtime exceeds the physical memory threshold and starts using virtual memory. Note that it acts very tactfully and tries to avoid the painful saving of heap data into paging files (see Handling low memory for details.)

You may however override the default behavior and opt for throwing OutOfMemoryError instead of using virtual memory under such circumstances. To do that, select the “throw OutOfMemoryError” option from the Handling low memory combo box.


Super Prev Next

JIT compiler

The JET Runtime includes a just-in-time (JIT) compiler, which allows a statically compiled application to load and use classes that were not pre-compiled (see Chapter Mixed Compilation Model for details.) In this pane, you select and configure the JIT compiler to be used for your application. You have the following options:

  1. In the JIT operation mode combo box, select the desired JIT compiler: "Fast" or "Optimizing".
  2. In the JIT caching mode combo box, define whether the dynamically compiled code have to be retained in the JIT cache:

Note: The optimizing JIT compiler and the JIT Caching Technology are now deprected features and will be removed in the next major release of Excelsior JET.


Super Prev Next

Advanced settings


Super Prev Next

Classpath consistency checks

These options control how the compiler treats classpath inconsistencies, such as absence of an explicitly imported class. By default, the compiler works around all inconsistencies, however, it may be worth fixing them instead. If you turn the checks on, the compiler will issue compilation errors on detected inconsistencies to help you correctly fix them.

Note: Sometimes inconsistencies are detected in a code that is not under your control, such as third-party APIs. In such case, you usually do not have a chance to remedy it quickly. However, you can at least check new versions of such API or file a complaint to its creators.

You can turn on the following checks:

See Bytecode consistency checks for details.


Super Prev Next

Stack size

The default thread stack growth limit in a JET-compiled application is 900 kilobytes, unless it was overridden using the -Xss Java launcher parameter you specified on Step 1.

You may need to increase the stack limit if your program employs highly recursive algorithms or the "allocating objects on the stack" optimization results in high consumption of stack memory.

You reduce it if your program needs to run lots of threads simultaneously (see Number of threads for more information.)

To specify the maximum thread stack size for your application, type it into the Maximum stack size field or drag the slider below. You may use suffixes “K” and “M” to denote kilobytes and megabytes respectively. The value you enter is rounded up to a multiple of 4 KB.

Note: If the entered value is too small or too large, the warning icon is displayed next to the field until you correct the value appropriately.


Super Prev Next

Additional options

The Additional options pane lets you explicitly specify command line options and equations of the JET compiler without editing the project file by hand. To do that, type the desired settings into the entry field, one on a line, for example:

    DISABLESTACKTRACE+
    INLINETOLIMIT=200


Super Prev Next

Step 5: Specifying target settings

On this step, you specify settings for the executable that will be produced by the compiler.


Super Prev Next

Executable settings

In the Executable settings pane, you specify the file name of the resulting executable and enable encryption of the application data.


Super Prev Next

Executable name

Type or select the desired name of the executable in the Executable Name combobox.


Super Prev Next

Application data protection

If you do not wish constant data, such as reflection info, Java string literals and packed resource files, to be visible in the resulting executable, you may enable data encryption by checking the Encrypt strings and resources box. For more details on data protection, refer to section Data protection.


Super Prev Next

Runtime selection

In the Runtime pane, you may select a particular version of the JET Runtime that will serve the compiled executable. Available versions of the Runtime are optimized for certain hardware and application types.

See Runtime Selection for a detailed description of the JET Runtime flavors.


Super Prev Next

Creating trial versions

You can create a trial version of your Java application that will expire in a specified number of days. As the evaluation period is over, the application no longer starts and shows the expiration message you specified when compiling it.

A detailed description of the functionality is given in section Creating trial versions.

Note: this feature is not available in Standard Edition of Excelsior JET.


Super Prev Next

Stack trace support

If you application requires printing stack trace of Java exceptions thrown, select the desired stack trace option from the Stack trace support combo box. The options are trade-off between availability of full stack trace information, such as line numbers, on the one hand, and application performance and the executable size on the other hand. For details, see Stack trace.


Super Prev Next

Multi-app executable

If you need to compile more than one application into a single executable, check the Multi-app executable box to create the executable that may have multiple entry points.

When starting such an executable, you will be able to select the application to be launched using the command line arguments. This way you may also specify Java properties and VM options at launch time. For more details, refer to section Multi-app executables.


Super Prev Next

Step 6: Selecting application appearance

On this page, you may also customize appearance of your application by assigning it a splash screen.

Note: if you are creating a project for an Eclipse RCP application, this page simply shows the properties. You cannot change them from within the Control Panel. Refer to section Step 6. Application appearance for more details.

Note: if you are creating a project for a Tomcat Web application, this page is not available.


Super Prev Next

Splash screen

In this pane, you specify settings for a splash screen to be displayed at the very startup of the resulting executable. A detailed description of each control is given in section Splash screen control extensions.


Super Prev Next

Step 7: Compiling your application

On this step, Excelsior JET Optimizer compiles your application to native code and produces a conventional Linux executable. You may invoke the compiler right from the JET Control Panel, optionally enabling the Startup Accelerator (see Configuring Startup Accelerator) integrated with the whole build process. Also, when building your application from the Control Panel you may get assistance in correcting possible project inconsistencies.

Another build option is to create a script that invokes the jc command-line compiler against the current project, which is suitable for automated builds.

If you compile a newly created project, the Control Panel prompts you to save the project first. Click Save, a conventional filechooser dialog will appear. Use it to specify the directory and name for the project. The default extension .prj is added to the file name automatically.

Note: during compilation the JET Optimizer will store Project Data Base into the project directory.


Super Prev Next

Configuring Startup Accelerator

The Startup Accelerator (see How to turn the Startup Accelerator on) improves the startup time of executables compiled with Excelsior JET. Thanks to its seamless integration with the Control Panel, it is very easy to use. Basically, the Control Panel automatically runs the compiled application immediately after build, collects the necessary profile information and hard-wires it into the executable just created. The JET Runtime will then use the information to reduce the application startup time.

You configure the Startup Accelerator in the respective pane at the top of this page. The Run and profile after build checkbox enables Startup Accelerator. Clear the box if you do not want the Control Panel to run the application and collect its profile after build. Otherwise, you may specify the duration of the profiling session in seconds in the field Profiling timeout. As the specified period has elapsed, the profiling stops and the running application is automatically terminated, so ensure the timeout value is large enough to capture the application startup. On the other hand, you may close the application manually if the profiling timeout proves to be excessively long.

Your application may require command line arguments to run. If this is the case, type them in the Application arguments field. For example, if your application opens files of specific types (associated with certain file extensions), you may specify a path to some input file as the application argument.

Finally, the Enable profiling in automated builds box (not set by default) controls if the application will be run and profiled automatically when building this project in the unattended mode with the command line JET compiler. For more information about this option, consult section Startup Accelerator in automated builds.


Super Prev Next

Building the executable

To start building the executable, click Build. If you need to do a full rebuild (see Make strategy) of the project, select Build/Rebuild All menu item.

The Control Panel first checks the project for consistency (see Fixing project inconsistencies). If there are no consistency issues, it invokes the compiler. The compilation dialog appears where the status area and the progress indicator are displayed to inform you about the build progress. If you need to view more detailed info about compilation, click Show log on this dialog and the compiler’s output will be displayed under the Filtered log and Full log tabs /Also, the full compilation log will be saved in the project directory with the name of the project and the extension .log./ .


Super Prev Next

Running compiled application

If everything goes well, the JET Control Panel runs the compiled application for a fixed time interval immediately after build to collect a startup profile / Unless you disabled the Startup Accelerator (see Configuring Startup Accelerator)./ and automatically terminates it.

Then, a message box appears to inform you that the build process is over and you may now run the compiled application to test how it works. You may do that by clicking Run on this box or by directly launching the executable from the application directory.

If the build process is not completed due to compile-time issues, such as low memory error, the Control Panel assists you in fixing them as described in section Correcting build errors.


Super Prev Next

Creating build script

If you want to run the JET Optimizer outside the Control Panel (e.g. to make more memory available for compilation or to create the executable using a makefile or a build script), click Create build script. The Control Panel first checks the project for consistency (see Fixing project inconsistencies). If there are no consistency flaws, it will create shell script build_target-name in the project directory you specified on Step 5. Use the script to build the application’s executable without invoking JET Control Panel.

Additionally, run_target-name script will be created in the project directory. The script defines the JETVMPROP environment variable that you may use to experiment with the JET Runtime settings without rebuilding the executable. For example, you may tweak parameters of the memory manager (see Memory management) to check how that affects performance and memory usage of your application.


Super Prev Next

Packaging your application

This is actually the final step, on which you prepare an installation that includes the compiled executable and any files it may need for execution. The resulting package can be then distributed and installed on other systems.

This functionality is not integrated into JET Control Panel. Clicking on Package, you close the Control Panel and invokes the JetPackII deployment wizard. If this is the first time you create an installation package for the executable, it will be automatically added to the list of package files. Otherwise, the JetPackII project previously created for the executable will be automatically opened.


Super Prev Next

Fixing project inconsistencies

When you click Build or Create build script, the JET Control Panel first checks the project for consistency. If it detects a problem, one of the following messages is displayed:

Save as dialog

Reason: You did not save a newly created project and did not specify the project directory.

Resolution: Do one of the following:

Main class is not specified

Reason: You chose to build an executable, but did not specify the main class.

Resolution: Click OK button on the error dialog, the Main class selection dialog will appear. If you indeed want to build an executable, select the main class from the dialog and click OK. Otherwise, click Cancel button and select shared library from the Application menu.

Compiler heap is too large

Reason: Value of the compiler heap setting is above the size of RAM installed on your machine. Starting the build may lead to excessive memory paging and significant slowdown of the compilation process.

Resolution:

  1. Close all applications you do not need at the moment.
  2. Set compiler heap size to adaptive (zero value) or to 70–80% of the RAM size (displayed to the left in this dialog.)
  3. Click Proceed
Low physical memory

Reason: The size of RAM installed on your machine does not meet the Excelsior JET system requirements (see System requirements). As a result, the compiler is unable to work with the fixed heap size used by default.

Resolution: Choose one of the following options:


Super Prev Next

Correcting build errors

Errors detected during build, if any, are displayed in red in the Filtered Log area. The JET Control Panel may assist you in fixing some typical errors caused by misconfiguration or bytecode inconsistencies.

To automatically fix such an error, select it in the Filtered Log area, and click the Fix it! button displayed below. If the button does not appear when you select an error, it cannot be fixed automatically. In this case, the error message contains some tips on finding out what caused the error and how to fix it.