Since version 3.1, Excelsior JET offers a complete solution for deployment of applications which contain JET-compiled binary components (executables, shared libraries.) It includes JetPackII, a graphical tool that helps you create installation packages, and Excelsior Installation Toolkit. This technology enables you to create complete packages and updates to previously deployed packages, and deploy them using a third-party installation tool of your choice. Another option is to prepare your applications for running from a CD without any installation.
The JetPackII packaging wizard, designed in the spirit of the JET Control Panel, is responsible for all stages of preparation of installations and updates. Its graphical interface guides you through the process of installation package creation step by step.
When creating a new package, you define the set of JET-compiled executables and auxilary files (resources, documentation, samples, etc.) which your application needs to work. You can also list Java system properties which values should be set on target machines during installation. As a result, your end users get self-installing archives that always create clickable executables on target machines. Thus, your applications never need launching through batch scripts.
You can also create updates to previous installations. This feature allows you to update or patch your products that have been previously installed on target machines. JetPackII assists you in tracking differences between the original and the changed packages so that the update will include only added and modified files.
JetPackII helps you determine the required JET run-time components and the JRE (if it is required) and include them in your package along with application files.
Then, you may perform a trial run, a testing procedure that ensures the completeness of your package. It simulates execution of your application deployed to a target system. The package contents are copied to the trial run directory which you set just like it appears during installation on target machines. The fact that JET is installed on your computer does not affect the correctness of trial run results.
Finally, you get either a self-extracting Excelsior Installer archive or a set of files to run from a CD, or, if you opted for using a third-party setup authoring tool, a set of files to create the installation package and also detailed instructions for installation with a third-party tool.
Excelsior Installation Toolkit is not yet ported to Linux. It will be available in the future versions of Excelsior JET for Linux.
Suppose you have compiled your application with JET and the compiled version has successfully passed the QA-analysis on your system. Now you need to prepare it for distribution to end users without changing its behavior will not change.
The following questions should be answered before you start with JetPackII:
JetPackII
at the command prompt and press Enter. A splash screen with a “Loading...” progress indicator shall appear. When loading is over, three buttons are displayed:
Figure 2. Excelsior JetPackII
Just alike JET Control Panel, JetPackII user interface is built as a series of “pages”, each representing one logical step in the process of your installation package creation. As can be seen on the Figure 2. Excelsior JetPackII, most of page space is occupied by page-specific controls; but there are also some common controls: the sidebar at the left edge, the main menu at the top, and help/navigation buttons in the lower right corner.
You can navigate through the pages either sequentially, by using the Next Page / Previous Page buttons, or directly, by clicking the respective sidebar button or by selecting a page in the Page menu. Depending on the context, some pages may be unavailable, with their respective sidebar buttons and main menu items disabled.
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 a help on a particluar control, click the Context Help button. The mouse cursor then changes its shape to an arrow with a question-mark — click the control you wish to learn about, and the respective portion of the online help will be displayed.
A JetPackII project consists of a project configuration and a set of files, which together fully determine the installation. A project defines:
This information is stored in a JetPackII project file that you create as described later in this chapter. JetPackII project files have extensions “.jpn” and “.jpu”.
You can create a new JetPackII project by clicking the New button on the JetPackII splash screen or by clicking the New sidebar button or by selecting the File/New menu item. This brings up the New page. If there is already an opened project, you are prompted to save it first.
You can open a previously created project right on JetPackII startup by clicking the Open button on the JetPackII splash screen or later by selecting the File/Open menu item (if there is already an open project, you are prompted to save changes first). A conventional file dialog is displayed; use it to select the JetPackII project file to be opened.
You can save a project by selecting the File/Save item from the main menu. When you save a just created project for the first time, a conventional file dialog is displayed; use it to specify the desired pathname for your project file. The default extension “.jpn” is added to the file name automatically.
You can save the current project with a different name or in another directory by selecting the File/Save As item from the main menu. A conventional file dialog is displayed; use it to specify a new directory and/or a new name for your project file.
The left part of initial four pages contains a package files panel. The panel represents the future installation package as a tree. Leaf nodes of the tree are files included in the package. Non-leaf nodes represent the directory structure of installation. Top-level nodes represent abstract root directories. Each root directory is a destination directory for the installation (typically installations will have a single root, but you may also prefer to have multiple root directories). Actual location of root directories becomes known only at the install time. Each root has its associated name (for instance, $(Root)), so it may be referenced by its name from various places, such as command line arguments for trial runs and shortcuts, values of Java properties, etc. Some directories in the installation view, such as the JET run-time directory and the JRE directory, are system, and only a restricted set of operations can be performed on them.
To the left of a package files panel element, one of the following icons may appear:
 |
 |
“new” or “application”: files and directories just added to the package; |
 |
 |
“identical”: files or directories that are parts of the previously created package for which the current package is an update; they are not included into the current package; |
 |
 |
“updated”: directories that contain just added or modified files that replace files in the previously created package. |
An icon may be surrounded by thin red border: 
It signals that the file or folder is “system” - it is automatically added to the project by JetPackII.
There are the following types of system files: JRE files, JET RT files, , and JIT Cache files added by JetPackII.
You cannot delete most of the system files except for JIT Cache files.
Possible operations on system files are described in sections Step 4: Selecting JRE Packaging Options, Step 5: Selecting Optional JET Runtime Components and Step 7: Selecting a Back-End.
The following icon may appear to the right of an element:
 |
“absent”: marks files that do not exist or may not be used and directories that contain such files |
The following buttons appear above the tree:
 |
Create a new directory in the installation. |
 |
Remove the selected element from the installation. |
 |
Rename the selected element. |
 |
Create a new root in the installation. This button is available only if the Multiple roots option is turned on via the Options item from the main menu. An installation with multiple roots can be created only using a third-party installer as a back-end.
Note: Multiple root packages can be created only in the Professional Edition. |
The Show all files check box can be used to toggle filtering of deployment set elements unnecessary for the current step.
The Show full path check box can be used to show full paths of files included into installation.
On this page you choose the type of the installation package to compose — either a new package or an update to an already existing one.
Selecting the "New" type of package, you compose an installation package of your application to be deployed on a target machine. When creating a new package, you define the set of JET-compiled executables and auxilary files (such as resource directories) that your application needs. You can also specify system properties and their values to be set up on a target machine during installation.
JetPackII helps you to determine required subsets of JET run-time and JRE (if they are involved) and to include them in your installation package along with application files.
Next, you can perform a trial run - a testing procedure that ensures the completeness of the package that will allow to run your application properly on a target machine.
As a result, you obtain either a single self-extracting Excelsior Installer archive, or a set of files to be run from a CD, or a set of files needed to create an installation package with a third-party installation tool.
Selecting the "Update" type of installation, you can create an update to an installation package created earlier. With it, you are able to refresh or fix your products that have been already installed on target machines. To make an update, you need a project file saved as ”updateable” for the original package (it may have been built using the "New" option). Just open that project and make changes in the contents of your installation package.
JetPackII assists you in detecting differences between the original and the changed packages, for the update package to include only added and modified files. You can perform a trial run to make sure that your application will work properly on a target machine after updating.
As a result, you get either a self-extracting archive (if you use Excelsior Installer) to automatically update already installed applications, or a set of files to be passed to a third-party deployment tool on which your deployment technology relies.
On this step you can add application files to your installation package.
The page displays the package files panel on the left and a host file chooser on the right. The package files panel represents the structure of the installation on a target machine. The host file chooser allows to select files to be added to the installation. You must add at least one JET-compiled component to create an installation.
To add file(s) to the installation, do the following:
button to add it. Adding a directory results in inclusion of its entire contents with subdirectories. Respective directories are created in the package files panel. Note that adding large directories may take a while.
To create an empty directory in the installation, use button.
When you add a JET-compiled executable to the package, the following things may occur:
You may rename the JET runtime folder or move it within the tree (using drag-n-drop.)
Note: If the executable you are adding was compiled using the JetPerfect Global Optimizer (and thus already includes the necessary pieces of JET runtime) the JET runtime folder will not be created or modified.
An important example of such executable is a custom launcher created by xjava -Xcompile.
Note: This feature only allows you to automatically add the cache descriptor and respective shared libraries. You still have to ensure that the original class files are available to the JIT compiler. You can do that in one of the following ways:
You can enable or disable automatic inclusion of JIT cache for any executable later by selecting Options/JIT Cache deployment automation menu item.
The restrictions on what files can be added to the installation are:
Note that files are not actually copied — the project being created contains just links to file locations. You can check that all referenced files do actually exist on disk by selecting the File/Refresh menu item. In general, you should avoid physical deletion of files already added to the deployment set.
In the “update” mode, you can also replace already deployed files just by dropping a newer file version over the older one. In this case, the file is included to the package and the respective update action will be performed on a target machine.
On this step you can specify classpath and Java system properties for each of JET-compiled files to be deployed.
The left side of the page displays the package files panel.
The right side of the page displays the list of JET-compiled executables added to the installation. For each executable you can set the classpath (shown as sub-items of the executable) or set Java properties in the panel below the list of executables. Note that while creating an update package, you can set a classpath and properties only for files that are either “new” or “updates”. That is, files marked as “identical” cannot be edited.
With 
button you can add the selected element from the package files tree to the classpath.
The classpath is used by the application class loader (default class loader) to find resources. It includes pathnames of .zip/.jar files and directories containing resource files. Resources are seeked in the order of classpath entries, so this order may affect application execution. Setting the classpath actually means setting of the java.class.path property. Note that it applies to separate resources only so if your package does not contain resources at all or they were bound to the executable, there is no need to set the classpath on this step.
To add an item to the classpath, do the following:
The following buttons can be seen above the list of executables:
| |
Remove the selected entry from the classpath. |
 |
Move the selected classpath entry up (i.e. make it preceding the below enrties in the CLASSPATH list). |
 |
Move the selected classpath entry down (i.e. make it succeeding the above enrties in the CLASSPATH list). |
In the lower right panel you can edit Java system properties to be defined on application startup (these properties can be inquired by a call to the java.lang.System.getProperty() method).
To set a Java property for a JET-compiled executable, do the following:
property-name [ = property-value ]
Property names and values may contain references to root directories in the form $(root-name). On startup, $(MyRoot) expands to the absolute path of the root directory named MyRoot.
On this step you must decide whether JRE is to be deployed along with your package or not, and select the JRE version for deployment.
The left part of the page occupied by the package files panel, showng only package directories though. If you choose to include a JRE into the package, the special folder named "JRE" appears in the panel. You may rename or move it within the directory tree.
The main question you should answer on this page is whether your application requires the JRE, and if it does, shall it be included in your package or not. There are three options to choose from:
The lower right panel displays the JRE version used by JET-compiled components included in the installation, and also the JRE directory. The specified JRE will be included in the package (if you chose Use internal JRE) and will be used to perform trial runs.
To select a JRE directory, click the Browse button, causing a conventional file chooser to appear. Select a JRE directory and click Select. Note that redistribution of a JRE that is a part of Sun’s JDK is prohibited by its license agreement. Therefore you should install a standalone JRE version you need and use it for deployment (i.e. specify its path in the text field described above).
When you create an update package, you can not alter the JRE packaging setting.
On this page you can inspect what JET run-time components are used by your application. These components will be included in the package. You can manually add some components to the installation package.
On the left panel you see the JET runtime folder with its contents. On the right panel you see a tree of check-boxes. Each of them can be in one of the following states:
There are three groups of checkboxes:
If you do not know exactly the entire subset of Java 2 Platform API which will be used by your application or if you expect your application to use the most of it, enable the Include JET runtime in whole checkbox to ensure that your application can find every part of JET runtime (JET JIT compiler + Java 2 Platform API).
On this step you can perform a trial run of the application to be deployed.
A trial run is a testing procedure that ensures completeness of your package. It simulates execution of your application deployed to a target system. The package contents are copied to the specified trial run directory exactly if it was installation to a target machine. The fact that JET is installed on your computer does not affect the correctness of trial run results.
Trial run serves the following purposes:
Performing trial runs is optional and may be skipped. However, it is strongly recommended to perform trial runs of all JET-compiled executables.
During a trial run, all files are copied into target directories corresponding to the installation roots, the post-installation processing is performed and the selected executable is started. Note that the system environment is reduced for the running executable, simulating an installation on a “clean” target machine.
When your program is run, you should test most of its features, thus checking that all Java 2 API components that may potentially be used by your application are really loaded. E.g. if your application can potentially work with sound/networking/CORBA or other APIs, invoke the respective functionality during the trial run.
When you feel testing is over, close your program in a usual way (of course, you should do nothing special if your program stops automatically, e.g. if it is a number-crunching application).
After the program execution has finished, all JET run-time components that were involved during the trial run are automatically added to the project. You may inspect them on the JET runtime page.
The trial run directory is a directory where all files are copied into before a trial run. It can be thought of as an “installation directory” for a trial run. It may be selected by clicking the Browse button. The directory selected should be empty (and you are warned if it is not), and the respective drive must have enough free space to accomodate the installed version of your application.
If your installation package contains multiple JET-compiled executables, each of them should be run at least once. Moreover, if your application behaves essentially differently depending on command line arguments and/or user input, you may wish to run the application several times using different scenarios.
A trial run configuration is a “scenario” for a trial run. It specifies what executable is to be run, its working directory and command line arguments. By default, JetPackII creates one trial run configuration for each executable that you add to the package. You can create more configurations, e.g for running your application with different command line arguments.
Trial run configurations are enumerated in a list. The color of a configuration reflects its status. A trial run colored in red is not performed yet. A trial run colored green is already performed. Certain changes in the project (such as adding/removal of files, actions with JRE and JET runtime) throw off trial run status to “red”.
You can add/remove trial run configurations using buttons on the left of the trial runs list:
 |
Add a trial run configuration. After clicking this button, a dialog is displayed showing the list of executables suitable for trial run. Select an executable to be run and click the OK button. |
 |
Remove the selected trial run configuration. |
The selected trial run configuration can be edited using the options panel to the right of the trial run list.
The Executable text field shows the executable file name in the target form (with its name relative to the root directory). It cannot be changed after the trial run configuration is created.
The Arguments text field shows command-line parameters that will be passed to the executable to run.
The Start in text field shows the working directory of the executable. It has a target form and can be selected using the Browse button.
To select a working directory, do the following:
The selected trial run can be performed using the Run button. After you click it, a dialog proposing to save the project may appear if you haven’t saved the project yet. Also, if the trial run directory is not empty, you may be prompted to clear its contents before simulating installation. After copying files, JetPackII starts the executable. If it is a console application, its console will remain after execution is over (you may safely close it then).
This step allows you to choose the type of the installation you wish to create.
The left side of the page contains the package files panel. It can be used to review the package and to rename or move the uninstaller executable if you select Excelsior Installer as the back-end.
A back-end can be chosen on the right side of the page.
If you create an update package, you cannot change the back-end type, it is identical to the type selected for the original package.
JetPackII allows you to create installations of several types:
This option is not yet available on Linux.
This page never appears in Excelsior JET for Linux because Excelsior Installation Toolkit is not yet ported to that platform. It will be available in the future versions of Excelsior JET for Linux.
This step is only needed when deploying NT services, so it is always skipped on Linux.
This is the final step of your installation package creation.
Package location — specify the location of the installation package here. If you use the Excelsior Installer back-end, it must be a single file, while for other back-ends the installation package is created as a directory. If you have already saved the project, this field contains the default value which is made of the project name and location.
Selected back-end — a text label containing information about the back-end type selected at the Step 7.
Create! button — click it after specifying the package location. If your project is not saved yet, you are asked to save it.
Then a progress window is displayed and, in a while, your package creation is completed. If you have chosen Excelsior Installer or CD Image back-end, you now have a package ready for installation or CD burn. Otherwise (for a “third-party” back-end), instructions are displayed how to integrate the generated image into the third-party installer.
You are recommended to test your newly created package by installing it to several machines with different operation systems, hardware configurations, etc. before starting distribution.
Save as updatable button — click to create an image of your package project. This image may be reused later to create update packages (minor version updates or hot-fixes of your product).
When you decide to create an update, just open the project saved as updatable and modify its contents. JetPackII helps you to track differences between the original and modified packages, so that the resulting update package includes only added and modified files. After the successful creation of an update package, you can save the modified project as updatable, thus building a chain of updates.
To start creating an update package, go to Step 1 and click the Update button.
New in 3.7:
In some cases, you may need to create the resulting package in an environment different from where the project was created, for example, on another machine / For that, you have to install JET on the machine and create profiles with the same JRE versions./ or on the same computer with the placement of package files changed. In such scenario, it would be reasonable to reuse the existing project file rather than to create a new project from scratch. JetPackII can help you update the existing project so that all settings and properties you specified in it are retained.
Suppose that the package files were copied to (or built in) the new environment. Ideal case for packaging would be just copying the project file (.jpn) to the new location and rebuilding the package in the batch mode. The problem, however, is that placement of the package files in the file system may be changed during relocation so the existing project cannot be reused directly. However, if the package files reside in the directory to which the project file was saved (or in its subdirectories), JetPackII uses relative paths to address the package contents. As a result, the package becomes fully relocatable or at least requires only minor updates after changing the environment. The following procedure helps you easily relocate an existing JetPackII project.
), fix them as follows:
Enable the Show full path checkbox on the bottom pane to see where JetPackII expects to find the missing files. Then, either copy or move the files to the appropriate location or remove them from the project and add such files again from their present locations using the Filechooser pane on the right. Note that in the latter case file-specific settings, such as system properties (see Step 3: Setting Up Standalone Resources and Java System Properties) will be lost.
The jpiib utility is used to re-build an installation package with a third-party installer back-end in the batch mode (from the command line or build scripts). After you have created an installation package using JetPackII and saved its project file, you can build the package with the command:
jpiib JetPackII-project-file -imagedir package location
The resulting files are created in the directory specified with the -imagedir option.
The xpackage utility is not available in Excelsior JET for Linux because Excelsior Installation Toolkit is not yet ported to that platform. It will be available in the future versions of Excelsior JET for Linux.
The xbind utility is used to perform post-installation processing of JET-compiled executables. You would normally use it in installation packages created by third-party setup generators.
xbind takes two files as input: a script file and a redirection file.
JetPackII prepares an xbind script file when creating the installation image. You do not need to edit that file.
An xbind redirection file should be prepared by the installer after the destination directory for each package root is defined. A redirection file is a plain text file, with each line specifying a root directory location on the target machine, in the following format:
root-name=root-location
Note that in case of external JRE the location of the JRE on the target system must also be specified as a separate root named JRE:
JRE=JRE-location
Post-installation processing can then be performed via the command:
xbind xbind-script xbind-redirection [-unicode-redirection]
xbind recognizes redirection files in the Unicode character set. The default encoding is ANSI. Use the -unicode-redirection option to specify that the redirection file is a Unicode text file.
If you have selected the “external JRE” option on step Step 4: Selecting JRE Packaging Options and use a third-party installer, your installation program will have to search the enduser system for a particular version of the JRE and/or let the end user select the JRE directory manually.
To aid the implementation of JRE lookup procedures, the respective component of Excelsior Installer has been placed into a separate DLL and its API is exposed:
The image prepared by JetPackII for a third-party setup generator will contain an extra file jrelookup.so, which may be loaded by the installation program produced by your third-party setup generator. JetPackII modifies that shared library so that it may be used to search only for the particular version of the JRE against which the executable(s) included in the image were compiled, such as 1.3.1_06.
The C header file include/jrelookup.h in your JET installation directory contains definitions of the JRE Lookup API functions.
Retrieves the version of the JRE hard-wired in this instance of the API.
int STDCALL JRELookup_GetVersion ( char* buffer, int bufferlen );
If the function succeeds, the return value is the length of the string copied to buffer, including the terminating null character.
If bufferlen is too small to hold the version number, the return value is the size of the buffer required to hold the version string with the terminating null character.
If the function fails, the return value is -1.
Searches the system for JRE installations.
int STDCALL JRELookup_Lookup();
This function takes no parameters.
The function returns the number of found installations of the version of the JRE returned by JRELookup_GetVersion().
This function collects information about JRE installations it has found on the system and stores it in an internal buffer. Use functions JRELookup_GetPath(), JRELookup_IsInternational(), JRELookup_IsPublic(), to retrieve information about each of those installations.
This function only finds JREs of a particular version (returned by JRELookup_GetVersion()) that are properly registred in the system. Use the JRELookup_AddDirectory() function to check whether the given directory contains the required version of the JRE.
Returns the number of JREs found on the system.
int STDCALL JRELookup_GetCount ();
This function takes no parameters.
The function returns the number of installations of the version of the JRE returned by JRELookup_GetVersion() found using JRELookup_Lookup() and JRELookup_AddDirectory().
Retrieves path to one of the previously found JREs.
int STDCALL JRELookup_GetPath (int index, char* buffer, int bufferlen);
If the function succeeds, the return value is the length of the string copied to buffer, including the terminating null character.
If bufferlen is too small to contain the path, the return value is the size of the buffer required to hold the path with the terminating null character.
If the function fails, the return value is -1.
Checks whether the given JRE installation is international.
int STDCALL JRELookup_IsInternational (int index);
If the function succeeds, the return value is 1 if the JRE stored at index is international or 0 otherwise.
If the function fails, the return value is -1.
The JRE of versions from 1.3.0 to 1.4.1 is available in two variants: US English and Internaional. JRE 1.4.2 has a single download but may be installed without support for non-European characters; such installation is considered non-international by the JRE Lookup API.
int STDCALL JRELookup_IsPublic (int index);
If the function succeeds, the return value is 0 if the JRE stored at index is a part of the JDK or 1 if it is a standalone installation.
If the function fails, the return value is -1.
The Sun JDK setup program installs two instances of the JRE: one under the JDK directory and another at some default location. The latter is the public JRE (the same as installed by the standalone JRE setup). You may only redistribute the public JRE with your Java applications, so you may wish your installation program to only allow binding to a public JRE.
Scans the given directory for JRE presence.
int STDCALL JRELookup_AddDirectory (const char* dir);
If the function succeeds, the return value is the zero-based index in the JRE information store at which the information about the found JRE has been saved.
If the function fails, the return value is -1.
Use functions JRELookup_GetPath(), JRELookup_IsInternational(), JRELookup_IsPublic(), to retrieve information about the JRE found in the specified directory.
This function only identifies JREs of a particular version (returned by JRELookup_GetVersion()).