Java Runtime Slim-Down

Note: information in this Chapter is not applicable to the Standard Edition of Excelsior JET.

New in JET 5.0:

Introduction
Java SE components
Deployment
Execution
Configuration issues

Introduction

Since version 5.0, Excelsior JET features Java Runtime Slim-Down, a new deployment model aimed at significant reduction of the download size and disk footprint of Java SE applications.

The key idea is to select a few components of the Java SE API, which are not used by the application, and exclude them from the installation. Such components are called detached. For example, if your application does not use any of Swing, AWT, CORBA or, say, JNDI, Excelsior JET enables you to easily exclude (detach) the associated files from the installation.

The detached components should be placed on a Web server so that the JET Runtime could download them if the deployed application attempts to use any of the components.

The necessary support for Java Runtime Slim-Down is also added to the JET Installation Toolkit: using JetPackII, you may select the detached components and assign the URL of the web server where the detached components will be located. When building an installation that has detached components, JetPackII compresses them into a single file called detached package, and creates it alongside of the main installation package.

Note that using Java Runtime Slim-Down is possible only if the executable(s) added to the installation have been compiled with the Global Optimizer enabled. Without that, the detaching of unused Java SE components cannot be implemented in the JET Runtime.

To summarize, using the Java Runtime Slim-Down model includes the following steps:

build the executable with the Global Optimizer enabled from within the JET Control Panel (see Step 3: Selecting a compilation mode)
select detached Java SE components and assign the URL of the web server using JetPackII (see Selecting detached components)
build the main and detached packages (see Step 9: Creating The Installation Package)
make the detached package available for download from the URL assigned on step 2
ship the main installation package to end users

This chapter contains a detailed description of what is Java Runtime Slim-Down, how it works and how to use it for your Java applications.

What is a detachable Java SE component

A detachable component is an API which is a part of the Java SE platform. Excelsior JET allows you to detach the following components: AWT/Java2D, CORBA, JDBC, JNDI, JSound, Management, RMI, Swing, and XML.

A component may comprise:

public API classes
implementing classes (one or more packages)
native method libraries and associated resource files, such as fonts

Using JetPackII, you may inspect what items are included in each component. For that, open the Detached component configuration dialog that displays a tree of all detachable components and expand the respective tree nodes.

Note that contents of the detachable components are pre-defined and may not be changed. When configuring a detached package, you simply select items from the list but you may not add a new detachable component. Excelsior JET imposes the restriction to guarantee flawless execution of Java applications deployed in this mode.

Used and unused Java SE components

JetPackII helps you identify the Java SE components that are not used by your application. When you open the Detached component configuration dialog, each component’s name is displayed with a color tag. The legend of the tags is as follows:

	component is unused, that is, the application does not reference any items from this component
	component is (partially) used, that is, some items from this component are referenced

In order to detect referenced items, Excelsior JET uses:

whole-program static analysis performed by the Global Optimizer
results of application profiling during Test Run

If you see that a component is marked as used but you are not sure that your application really uses it, click the red tag on the right to the component’s name. JetPackII will open an information dialog that shows all referenced classes from this component. Check your application code including the code of the third-party libraries listed in the application’s classpath, if any, to find the places from where the classes are referenced.

How to identify unused components

The Java SE components marked with the green tag are not used by your application and can be detached without a doubt.

Under certain circumstances, you may also detach a component marked with the red tag. When you try to exclude such a component, JetPackII will open a warning dialog. Click Details to see the list of component’s classes that your Java application references and, if applicable, the native method libraries that it loads at run time. As JetPackII always places the referenced items into the main installation package, only the remaining part is actually detached when excluding such a component. Therefore, if only a few classes from a Java SE component are referenced, in most cases, it can be detached just like an unused component.

However, care must be taken. If the application references lots of classes from a component, the remaining (unreferenced) classes may also be used implicitly, e.g. via the Reflection API. Moving such components to the detached package may result in its downloading at run time.

If you encounter an issue with unexpected downloading of the detached package, refer to section Configuration issues that describes possible reasons and resolutions.

Deployment

Before starting distribution of an application that uses Java Runtime Slim-Down, you should make the detached package available for download from the assigned web server.

When creating an installation, you should specify the URL where the detached package will be located. In JetPackII, you set the base URL using the Detached component configuration dialog and choose the exact name of the detached package on the Final page.

For example, if the base URL is

http://www.companyname.com/downloads

and the name of the package is

detached.pak

the file should be available from

http://www.companyname.com/downloads/detached.pak

Note also that target systems should have a network connection for possible download of the detached package.

Execution

Of course, if the deployed application does not attempt to use a component from the detached package, it works as if the entire Java SE Runtime was installed. Otherwise, if the application loads a class or native method library located in the detached package, the JET Runtime performs the following actions:

The detached package is downloaded from the URL you specified when creating the installation; if the downloading fails due to an unstable connection or absence of the requested file on the server, the JET Runtime throws one of the following VM exceptions:
NoClassDefFoundError: <class name>, if the thread attempts to load a class
UnstatisfiedLinkError: <library name>, if the thread attempts to load a native method library
Upon successful download, the file is placed into the system temporary directory, the SHA digest of the file is computed and checked against the digest hard-wired into the application executable by JetPackII when building the installation; If the check fails, the JET Runtime throws a VM exception as described above.
The downloaded file is unpacked into a subdirectory of the system temporary directory and then deleted
The requested item (class or native method library) is loaded into the application process. Note that the detached package contains the classes in the bytecode form (.class files) so they are loaded and compiled by the JIT compiler that comes with the JET Runtime (see Chapter Mixed Compilation Model for details.)

By default, the unpacked files are not removed at application exit. As a result, they will be reused on next application launch without the downloading of the detached package. If however, the cached files are deleted or corrupted, and the application accesses the detached package, the JET Runtime repeats steps 1 through 4 described above.

If you do not want the application to cache the unpacked files, clear the Cache downloaded files checkbox in the Detached component configuration dialog dialog or set the system property jet.remote.cleanup. In such case, the Runtime will remove the unpacked files (if any) upon application exit.

Configuration issues

This section covers some issues related to using Java Runtime Slim-Down.

Despite I only excluded the components which JetPackII marked as unused, the JET Runtime downloads the detached package at run time

Reason 1: The components you have excluded were unused at the time the JetPackII project was initially created. Then, you have added new classes or third-party libraries to the application and some of the components may have become used. JetPackII and the xpack utility issue a warning in such case but you may have missed it.

Resolution: Open the project with JetPackII, go to the Runtime page, click Configure in the Detached components pane and check if a detached component is marked as used with the red tag. If this is the case, clear the component’s checkbox to place it to the main installation package.

Reason 2: The deployed application loads a plug-in that makes use some of the detached components.

Resolution: Open the project with JetPackII, go to page Trial Run, run your application and follow the scenario that causes downloading of the detached package. Upon application exit, JetPackII will issue a warning listing the detached Java SE components that were accessed at run time. Cancel exclusion of the components from the installation as described above.

Note that you can assist JetPackII in automatic detection of such components by performing a thorough test run before compiling the application.

How do I figure out what particular items from the detached components are accessed by the application at run time?

Set the system property jet.remote.loud to enable logging of the access trials to the console. Run the application and follow the scenario that causes downloading of the detached package. The names of accessed classes and/or native method libraries will be logged.

Target system has a network connection configured with a proxy-server. How to set up the deployed application so that the JET Runtime could access the detached package?

Excelsior JET Runtime uses the standard Java networking API for downloading the detached package. To configure proxies for the installed Java application, set the following Java system properties:

http.proxyHost, http.proxyPort, or

ftp.proxyHost, ftp.proxyPort

For more details, refer to the Java SE platform documentation available at

http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html

I already use Java Runtime Slim-Down. Is it possible to further reduce the download size of my Java application?

Option 1: Tune the compiler options that control the size of the resulting executable.The major effect can be achieved by setting the "Low" or "Tiny methods only" policy for the inlining optimization (see Method inlining for details.) Then, re-compile your application and create the installation.

Option 2: If your application uses Swing or AWT/Java2D, consider replacing them with an alternative GUI toolkit such as LWJGL or SWT. Having it done, you will be able to detach the components from the main installation package that will result in a substantial saving in the download size.