Excelsior JET Control Panel is a graphical front-end 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.
Note: Some advanced features are not accessible through the Control Panel. In such case, use the command-line compiler as described in Chapter JC reference.
Before using Excelsior JET to compile your Java application to native code, make sure that its bytecode version is present on your system and runs properly on the particular version of the virtual machine which you selected when installing JET.
Important: Ensure that your class files were compiled with optimizations disabled (e.g. the javac option "-O" was not used), otherwise the JET optimizer would become less efficient.
To start the JET Control Panel, type
LaunchPad
at the command prompt and press Enter.
A splash screen with a “Loading...” progress indicator shall appear. When loading is over, three buttons shall be displayed:
Figure 1. Excelsior JET Control Panel
Excelsior JET user interface is built as a series of “pages”, each representing one logical step in the process of setting up your project. As can be seen on Figure 1. Excelsior JET Control Panel, most of the page space is occupied by page-specific controls, but there are also some common controls: sidebar at the left edge, main menu at the top, and help/navigation buttons in the bottom right corner.
You may iterate through the pages using the Next Page / Previous Page buttons, or go directly to a particular page by either clicking on the respective sidebar button or selecting that page in the Page menu. Depending on the context, some of the pages may be unreachable — their respective sidebar buttons and Main Menu items shall be disabled then.
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 particluar control, click the Context Help button. The mouse cursor shall change shape to an arrow with a question-mark — click the control you want to learn about, and the respective portion of the online help shall display.
A JET project consists of a project configuration and a set of files, which together fully determine the final executable produced by the compiler. A project defines:
This information is stored in the project file which you create as described further in this Chapter. JET project files have the extension “.prj”.
You may create a new JET project by either clicking the New button on the JET splash screen, clicking the New sidebar button or by selecting the File/New menu item. This brings up the New page (if there was already an open project, you shall be prompted to save it first.)
You may open a previously created project right on JET startup by clicking the Open button on the JET splash screen, or later by selecting the File/Open menu item (if there was already an open project, you shall be prompted to save changes first.) A conventional file dialog shall display. Use it to select the JET project file you want to open.
You may also open project files you created manually for the JET command-line compiler jc. However, the Control Panel only recognizes a subset of the project file syntax (see Project files), so it may refuse to load a project file that uses advanced features, such as preprocessing (see Control file preprocessing.)
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 that a project is not actually created until you reach Step 3, so the item File/Save is disabled on Steps 1 and 2.
You can save the current project under a different name or into another directory by selecting the File/Save As item from the Main Menu. A conventional file dialog shall display; use it to specify the new directory and/or name for your project.
Note: Saving the project under a different name also changes the name of the generated executable (see Step 6: Specifying target settings.)
A project is not actually created until you reach Step 3, so the item File/Save As is disabled on Steps 1 and 2.
This is the first step when creating a new project, where you select the target executable type and choose an application description source.
Excelsior JET may create two types of Linux executables:
The project setup procedure is slightly different for each executable type, thus you have to select it at the very beginning. You may change it later by selecting the respecitve item from the Application menu.
In order to compile your Java application to native code, you have to specify the classes comprising it, resources (images, audio clips, etc.) it uses, system properties, etc., to the Excelsior JET compiler. You may do that manually, but JET is also capable of retrieving the necessary information automatically from the command line of the java launcher or the shell script invoking it.
Click one of the application description sources for automatic information retrieval or click Manual Setting to skip that step.
On this step, you provide the details for the application description source you selected on Step 1. Depending on your selection, one of the two versions of the Source page shall be displayed:
This step is skipped if you select Manual Setting on Step 1.
This version of the Source page is displayed if you select JVM command line as the application description source on the New page.
To make JET retrieve the description of your application from its JVM command line, do the following:
javaw -cp ~/MyLib -Xmx20m -jar MyApp.jar
This version of the Source page is displayed if you select Batch file as the application description source on the New page.
To make JET retrieve the description of your application from the batch file used to run it on the VM, do the following:
Note: JET is not capable of correctly parsing batch files in which the JVM launcher java/javaw is invoked using full path, e.g.:
/usr/java/jdk1.3.1_03/jre/bin/java Main
$JRE_DIR/bin/java Main
or is not invoked at all (the JVM is launched by an executable that has a different name.)
On this step, you define:
The Classpath Entries pane contains a list of archive files and directories from which the JET compiler shall retrieve classes on Step 7. All packages and classes found at those locations are displayed in the Compilable Classes pane to the right.
If you did not skip Step 2, the lists of classpath entries and classes should be prefilled, as well as the main class name. If all those settings appear to be correct, you may safely go to the next step.
Classpath entries are disk locations (directories and jar/zip files) containing your application’s classes. When looking for a particular class, JET processes classpath entires in the order in which they appear in the Classpath Entries pane, from top to bottom.
Note: It is therefore important that you place classpath entries in the same order as they are accessed by the virtual machine when it loads your application’s classes /This is the order in which classpath entries appear 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 shall be read by the JET compiler, in which case the behavior is unpredictable.
You edit the classpath using the pop-up menu displayed when you right click the Classpath Entries pane, or using the five buttons appearing to the left:
 |
Add |  |
Move Up |  |
Toggle Enforcement Status | ||
 |
Remove |  |
Move Down |
To add a classpath entry to the list, do the following:
To remove a classpath entry from the list, do the following:
A confirmation box shall appear.
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 properly placed. You may need to do this if there are two or more classes located along the classpath that have exactly the same (full) name See “Duplicated classes” in Project inconsistencies for details.
The Compilable Classes pane displays all packages and classes found in directories and jar/zip files listed in the Classpath Entrires pane. You may also display the list of classes and packages found at a particular classpath entry by expanding that entry.
The status of each particular class, or package with respect to whether it shall be compiled is indicated by a color tag displayed to the left of the class or package name:
 |
the class or package is expliciltly included into the compilation set by the user |
 |
the class or package is included in the compilation set by import (explicitly included classes depend on it) |
 |
the class or package is not included in the compilation set either explicitly or by import |
 |
the class file is ignored because a class file with the same name was found earlier in the classpath or because this class belongs to the Java 2 API. See Project inconsistencies for details |
 |
the package is partially included in the compilation set |
You have to explicitly include at least one class into the compilation set. The main class is included automatically. So in the simplest case you specify the main class and JET adds the remaining classes by scanning import dependencies.
JET is unable to detect classes that are loaded dynamically at run-time. If you know such classes beforehand, force them into the compilation set as described below.
However, your application may also load classes from the network (e.g. in the RMI Distributed Object Model) or even create them at runtime (Dynamic Proxy API) To handle this situation, employ the Mixed Compilation Model.
To force a class into the compilation set or to cancel enforcement, do one of the following:
To force an entire (sub)package into the compilation set or to cancel enforcement of all its classes, do one of the following:
To force all classes found at a particular classpath entry into the compilation set, do one of the following:
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 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 your application’s jar.
Similarly, JET needs to know the name of the main class to make control passed to its main method on application startup. It also traverses the import graph of that class to determine the minimal set of classes that have to be compiled for the application to be successfully linked.
If you did not skip Step 2, JET must have already set the Application Main Class field to a proper value. If you chose Manual Setting and went directly to Step 3, you need to specify the main class yourself. You may also want to switch between the multiple main methods to create different executables from a single project.
To specify the main class, do one of the following:
You do not need to select the main class if you want to make a shared library.
Whenever you add, remove, or change relative position of a classpath entry, or mark/unmark classes or packages for explicit inclusion into the compilation set, JET scans the import graph of the whole project, starting from the main class and classes forced into the compilation set, and assigns the imported/omitted/ignored tags to the remaining classes. This is called import scanning.
The import scan cycle for a large project involving thousands of classes takes a considareble amount of time, and automatic scan after each classpath/compilation set change can become annoying. If this is the case, disable automaic import scanning by unchecking the Scan Automatically checkbox. You shall be able to run import scanning manually after making changes to the classpath or the compilation set by clicking the Start button in the Import Scanner pane.
Note: If you have automatic import scanning disabled, run the import scanner before leaving the Classes page to conduct consistency checks.
The import scanner is also capable of detecting the following inconsistencies in the project:
If any such inconsistency is detected, the Warnings tab shall appear in the information area at the bottom of the page. Under that tab, the overall numbers are displayed for each type of inconsistency. Click the respective Details button to display a dialog box with a list of classes involved.
When multiple class files for the given full class name are found along the classpath, the file located in the entry that is closer to the beginning of the classpath prevails. The “overrides” tag 
is displayed next to the first occurence of such class in the Classpath Entries pane, whereas all other occurences have the “ignored” tag and the “overridden” tag 
.
To browse the list of duplicated classes, do the following:
To resolve this inconsistency, it is sufficient to ensure that the desired versions of class files appear in the compilation set by adjusting the order of classpath entires. You may then remove the overridden class files.
Any JET-compiled application should use the Java 2 platform classes precompiled during JET installation. Classes coinciding with Java 2 platform classes are displayed with the “ignored” tag and the respective classpath entries and packages are marked with the “conflict” tag 
in the Classpath Entries pane.
To browse the list of conflicting classes, do the following:
To resolve this inconsistency, remove all classes coinciding with Java 2 platform classes from the classpath. If such classes appear in third party jars, try enabling the Ignore conflicting classes option on the Options page. See Bytecode consistency checks for more information.
If a class A that is part of the compilation set explicitly imports another class that is not part of the Java 2 API and could not be located along the classpath, the “unresolved import” tag 
is displayed next to the class A.
To browse the list of classes that have unresolved import dependencies, do the following:
To resolve this inconsistency, add directories and/or archives containing necessary classes to the classpath. It may happen, however, that this problem is detected in a code that is not under your control, such as a third-party class library or component. In such case, file a complaint to the vendor of that software and specify that class absence should result in a run-time error on the Options page. See Bytecode consistency checks for more information.
JET may correctly handle the situation when an imported class is not present at compile time but becomes available at run time. See Reflective shield for details.
By clicking the Statistics tab, you display complation set statistics:
On this step, you define the resourcepath - a set of directories and jar/zip files where your application’s resources (images, audio clips, property files, etc.) are stored, and specify whether the JET compiler should bind resources and, optionally, classfiles to the resulting executable.
The Resourcepath pane contains the list of all locations (directories and jar/zip files) along the resourcepath, in the order they have to be searched by the application at run time. By default, this list is synchronized with the list of classpath entries you define on Step 3: whenever you add or remove a classpath entry, it is added to or removed from the resourcepath, and the relative order of such entries is preserved. You may also add entries specific to the resourcepath. Entries derived from classpath are displayed in italic.
Two buttons are displayed to the left of the Resourcepath pane:
| |
Add |
| |
Remove |
To add a resourcepath entry, do the following:
To remove a resourcepath entry from the list, do the following:
A confirmation box shall appear.
Note: Removing a resourcepath entry that is present in the classpath disables syncronization with the classpath.
To switch sychronization with the classpath on or off, select the Synchronize With Classpath checkbox. If you had removed any resourcepath entires that are present in the classpath, they shall be added back to the resourcepath when synchronization is restored.
Excelsior JET is capable of binding Java resources to the resulting executable, much like it is done when programming native Windows applications. This allows you to transform your application’s jars into a single self-contained executable.
A status tag is displayed before each resourcepath entry, indicating the way it shall be handled by the compiler:
 |
The entry is left intact by the compiler. This is the only option for resourcepath entries that are directories. |
 |
Resources are bound to the resulting executable, class files are filtered out. This is the default for jar/zip files |
 |
The entire jar/zip file, including class files, is bound to the resulting executable. Presence of the original class files at runtime is required by some APIs, such as Java Crypto Extension. You may also wish to use the Mixed Compilation Model to compile some classes at run time. |
To switch resource handling for a particular resourcepath entry, do one of the following:
See also Resource binding.
On this step, you specify options that control various aspects of behavior of both the JET compiler and the resulting application.
This set of options controls how the compiler treats bytecode inconsistencies, such as absence of an explicitly imported class. By default, they result in compilation errors. However, when an inconsistency is detected in bytecode that is not under your control, such as a third-party class library, you usually do not have a chance to remedy it quickly. If you encounter such problem, contact the vendor who supplied the inconsistent bytecode, and toggle the respecitve JET options to make the compiler treat bytecode inconsistencies as warnings:
The compiler will report warnings and will insert the code throwing java.lang.NoClassDefFoundError for all locations where absent classes are referenced, i.e. where instantiation, static method call, or static field access takes place.
Note: If however your application relies on lazy classloading (imported classes become available at run time before they are used), you need to use the reflective shield instead. If this is the case, select that class absence must lead to dynamic compilation.
The compiler will report warnings and will insert the code throwing java.lang.NoSuchMethodError or java.lang.NoSuchFieldError for all locations where absent members are referenced.
See Bytecode consistency checks for details.
By default, JET does not produce code for assertion statements, because generation of that code has negative impact on application performance and footprint. If you need assertions to be present in the resulting executable, check the Generate asserts box.
See Assertions for information on how to enable assertions at run time.
Note: Assertions were first introduced in J2SE 1.4.0, so if the active profile (see Profiles) includes JRE version 1.3.x, the Generate asserts box is not displayed.
Just like a Java application, the JET compiler uses garbage collection to reclaim memory /Although the compiler is written in a language other than Java./ . It may therefore be necessary, for optimum performance of the compiler, to adjust the maximum amount of memory that it is allowed to use.
To specify the maximum amount of memory JET may use when compiling your application, type it into the Compiler Heap 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 on the right of the field until you correct the value appropriately.
You have to increase this setting, if you get the "out of memory" (F950) message. See Correcting build errors for more information.
Vice versa, intensive page file access during compilation indicates that the compiler heap size setting is too large for your system configuration.
You may also let the compiler determine the proper heap size dynamically at run time. To do that, drag the slider to the leftmost position until the word “Adaptive” is displayed in the Compiler Heap field. Please note, however, that in this mode the compiler shall under nocircumstances use more memory than the amount of available physical memory, so using adaptive compiler heap is not recommended on low-end systems.
See Compiler memory usage for more information.
By default, the Java VM uses certain heuristics at run time to determine the maximum amount of memory the application is allowed to allocate without garbage collection, depending on the system load. You may also specify that amount explicitly using the -Xmx parameter of a JVM launcher. Using heuristics is the default in JET-compiled applications as well, unless the -Xmx parameter was specified in the application description source. You may adjust this setting or revert to the default behavior at any time.
To specify the maximum amount of heap memory your application should be allowed to allocate at run time, type it into the 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 on the right of the field until you correct the value appropriately.
To return to the default behavior, drag the slider to the leftmost position. The word “Adaptive” shall be displayed in the Heap Size field.
See Application memory usage tuning for more information.
The default thread stack growth limit in a JET-compiled application is one megabyte, unless it was overridden using the -Xss Java launcher parameter in the application description source.
You may need to increase the stack limit if your program employs highly recursive algorithms, or 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 Stack Heap 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 on the right of the field until you correct the value appropriately.
For the sake of reliability, the JET compiler always has all optimizations 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 reduce scalability, and inline method expansion, which improves performance but also increases code size. You therefore have an option to disable stack allocation and adjust the criteria for inlining.
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 destroyed 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.
Enabling this optimization may however negatively affect your program’s scalability. If you are compiling a server-side Java application that may need to run thousands of threads simulatenously, disable this optimization by unchecking the Allocate objects on the stack box.
The JET compiler is capable of replacing calls of methods with their bodies when the method to be called at run time may be exactly determined at compile time. This optimization is called inline method expansion; small methods, such as get/set methods, especially benefit from it. The other side of the coin is that inline expansion increases code size and may in fact worsen performance if the resulting methods are too large.
To control the aggresiveness of this optimization or turn it off completely, select the desired level from the Inline expansion list, or select OFF to disable inlining.
Excelsior JET supports Mixed Compilation Model, which allows your JET-compiled application to load and use classes that were unknown at compile time.
This feature is implemented through provision of a Caching JIT compiler that you may redistribute with your application.
Please read Chapter Mixed compilation model that contains detailed information about the Mixed Model before using it.
The Mixed Compilation Model is disabled by default. To enable it, do the following:
Note: In general, using an absolute pathname for the cache directory is not recommended as it may cause problems on deployment. If you want to rename the cache directory or change its location on the enduser system, specify the jet.jit.cache.dir property when packaging your application for deployment (see Editing Java properties for details.)
Note: The optimizing JIT compiler and the JIT Caching Technology are available in the Professional Edition only.
On this step, you specify settings for the executable to be produced by the compiler, and Java system properties required by your application, if any.
To specify the target executable settings, do the following:
Note: JET will save the project file into this directory and store compiler output files in subdirectories of that directory, automatically created during compilation.
Note: This will also be the name of the project file.
Professional Edition only:
In the Runtime pane, you may select a particular version of the JET runtime system that will serve the compiled executable. Different runtimes are available, optimized for certain hardware and application types. You may freely use any of them for development, however, production and redistribution uses of some runtimes requires payment of a runtime license fee. See Runtime Selection for a detailed description of Excelsior JET runtime flavors.
To specify Java system properties required by your application (those passed to the Java launcher using “-D” options), type them in the entry field from the Java System Properties pane, one on a line.
For instance, if you run your application on a JVM as
java -Dmyapp.debug -Dmyapp.log=/var/log/myapp MyApp
type the following in the field:
myapp.debug
myapp.log=/var/log/myapp
Note: If you opted for a description source other than Manual Settings, JET should have retrieved the properties automatically.
On this step, JET compiles your application to native code and produces a conventional Linuxexecutable. You can invoke the compiler right from the JET Control Panel, to receive assistance in correcting possible project misconfigurations, or create a build script for use with the jc command-line compiler.
To initiate the executable build process, click Build. JET shall first check the project for consistency (see Remedying project consistency flaws). If there are no consistency flaws, the Control Panel shall invoke the jc compiler. The status area and the progress indicator at the top shall start updating, informing you about the build progress, and compiler’s output shall be displayed under the Full Log tab.
If everything goes well, a message box shall inform you that the build process is over and you may now run your compiled application to test how it works. You may do that by clicking Run or by launching the run_target-name script created by JET in the target directory you specified on Step 6. Later, if you make any changes to your application’s class files, you may rebuild the executable from the command-line by launching the build_target-name script from the same directory.
See also Remedying project consistency flaws and Correcting build errors.
If you want to run jc outside the JET Control Panel (e.g. to make more memory available for compilation or to use jc from a makefile or a build script), click Create Control Files. JET shall create shell scripts build_target-name and run_target-name in the target directory you specified on Step 6. Use them to build and run your application’s executable respectively.
See also Remedying project consistency flaws.
When you click Build or Create Control Files, JET first checks the project for consistency. If it encounters a problem, one of the following messages shall display:
Reason: Compiler heap setting exceeds the amount of available memory. It may lead to excess memory paging and significant slowdown of the compilation.
Resolution:
Reason: You did not save a newly created project and did not specify the project directory.
Resolution: Do one of the following:
Reason: There are no entries in the classpath, so there are no classes to compile.
Resolution: Return to the Classes page, and add some entries to the classpath as described in Working with classpath entries.
Reason: You chose to build an executable, but did not specify the main class.
Resolution: If you indeed want to build an executable, return to the Classes page and specify the main class as described in Specifying the main class. Otherwise, select shared library from the Application menu.
Reason: The classpath is not empty but there are no classes in the compilation set.
Resolution: Go to the Classes page and force one or more classes into the compilation set as described in Working with classes and packages.
Reason: Not all class files located in the classpath are included in the compilation set. The class files that are not included may be implicitly used by the application through dynamic loading.
Resolution: If you are sure that the current compilation set is complete, click Yes. Otherwise click No, return to the Classes page, and review the compilation set, possibly adding classes to it as described in Working with classes and packages.
Reason: Classes with unresolved import dependencies detected. referencing
Resolution: If your application uses an inconsistent third-party library, click on Ignore to enable ignoring class absence. Note that any attempt to use an absent class in the compiled code shall throw an exception. Otherwise, click on Cancel, return to the Classes page, and add the entries containing absent classes to the classpath as described in Working with classpath entries and Project inconsistencies.
If an imported class is not present at compile time but becomes available at run time, click on Handle to enable the reflective shield facility.
Reason: Classes coinciding with Java 2 API classes detected.
Resolution: If your application uses an inconsistent third-party library, click on Ok to enable ignoring class conflicts. The Java 2 platform classes precompiled during JET installation shall be used by your application. Otherwise, click on Cancel, return to the Classes page, and remove conflicting classes from the compilation set as described in Working with classpath entries and Working with classes and packages.
Errors detected during build, if any, are displayed in the Filtered Log area in red color. JET may assist you in fixing some typical errors caused by misconfiguration or bytecode inconsistencies.
To automatically fix such an error, highlight it in the Filtered Log area, and click the Fix it! button. If the Fix it! button does not appear when you highlight an error, that mean that JET is not able to fix it. If this is the case, the error message shall contain some tips on finding out what caused the error and how to fix it.
This is actually the final step, on which you package your compiled application, along with any files it may need for proper execution, into a self-installing archive, to be used for distribution to other systems.
This functionality is not integrated into the Control Panel. When you click on Package, the Control Panel closes and invokes JetPackII deployment automation tool, automatically adding the compiled executable to the list of package files.