Java Platform, Standard Edition Deployment Guide
Contents    Previous    Next

7 Self-Contained Application Packaging

This topic describes how to generate the package for a self-contained application. A self-contained application contains your Java or JavaFX application and the JRE needed to run the application.

This topic includes the following sections:

7.1 Introduction

The Java packaging tools provide built-in support for several formats of self-contained application packages. The basic package is a single folder on your hard drive that includes all application resources and the JRE. The package can be redistributed as is, or you can build an installable package (for example, EXE or DMG format.)

From the standpoint of process, producing a self-contained application package is similar to producing a basic application package as discussed in Chapter 5, "Packaging Basics," with the following differences:

  • Self-contained application packages must be explicitly requested by passing additional arguments to the <fx:deploy> Ant task or javapackager tool.

  • Operating system and tool requirements must be met to be able to build a package in a specific format.

  • Self-contained application packages can only be built using JDK 7 Update 6 or later.

While it is easy to create a basic self-contained application package, tailoring it to achieve the best user experience for a particular distribution method usually requires some effort and a deeper understanding of the topic.

7.2 Benefits and Drawbacks of Self-Contained Application Packages

Deciding whether the use of self-contained application packages is the best way to deploy your application depends on your requirements.

Self-contained application packages provide the following benefits:

  • Users install the application with an installer that is familiar to them and launch it in the usual way.

  • You control the version of the JRE used by the application.

  • Applications can be deployed on fresh systems with no requirement for the JRE to be installed.

  • Deployment occurs with no need for admin permissions when using ZIP or user-level installers.

  • File associations can be registered for the application.

  • Support for secondary launchers enables a suite of applications to be bundled in a single self-contained application package.

Self-contained application packages have the following drawbacks:

  • "Download and run" user experience

    Unlike web deployment, the user experience is not about "launch the application from the web." It is more one of "download, install, and run" process, in which the user might need to go through additional steps to get the application launched. For example, the user might have to accept a browser or operating system security dialog, or find and launch the application installer from the download folder.

  • Larger download size

    In general, the size of self-contained application packages is larger than the size of a standalone application, because a private copy of the JRE is included.

  • Package per target platform

    Self-contained application packages are platform-specific and can only be produced for the same system on which you build. To deliver self-contained application packages on Windows, Linux, and OS X, you must build your project on all three platforms.

  • Application updates are the responsibility of developer

    Web-deployed Java applications automatically download application updates from the web as soon as they are available. The Java Autoupdate mechanism takes care of updating the JRE to the latest secure version several times every year. Self-contained applications do not have built-in support for automatic updates.

7.3 Basics

Each self-contained application package includes the following items:

  • Application code, packaged into a set of JAR files, plus any other application resources (data files, native libraries)

  • Copy of the JRE, to be used by this application only

  • Native launcher for the application, multiple launchers for a single package are supported

  • Metadata, such as icons

Multiple package formats are possible. Built-in support is provided for several types of packages. You can also assemble your own packages by post-processing a self-contained application packaged as a folder, for example if you want to distribute your application as a ZIP file.

7.3.1 Self-Contained Application Structure

The basic form of a self-contained application package is a single folder on your hard drive, such as the example in Figure 7-1. When any of the packages are installed, the result is a folder with the same content.

The internal structure of a self-contained application folder is platform-specific, and might change in the future. However, the following items apply to all platforms and are not likely to change:

  • The application package, as defined in Chapter 5, "Packaging Basics," is included as a folder, preserving the application directory structure.

  • A copy of the JRE is included as another folder, and the JRE directory structure is preserved.

Because directory structure is preserved, the application can load external resources using paths relative to the application JAR or java.home system property.


Only a subset of the JRE is included by default. Some optional and rarely used files are excluded to reduce the package size, such as all executables. If you need something that is not included by default, then you need to copy it in as a post-processing step. For installable packages, you can do this from the config script that is executed after populating the self-contained application folder. See Section 7.3.3, "Customizing the Package Using Drop-In Resources."

7.3.2 Basic Build

The easiest way to produce a self-contained application is to modify the deployment task. To request the creation of all types of self-contained application packages for the platform on which you are running, add nativeBundles="all" to the <fx:deploy> task, as shown in Example 7-1.

You can also specify the exact package format that you want to produce. Use the value image to produce a basic package, exe to request an EXE installer, dmg to request a DMG installer, and so on. For the full list of attribute values, see the nativeBundles attribute in the <fx:deploy> entry in the Ant Task Reference.

You can also produce native packages using the Java Packager tool. Self-contained application packages are built by default when you use the -makeall command. You can request specific formats using the -native option with the -deploy command. See the javapackager command reference for Windows or for Solaris, Linux, or OS X.

Example 7-2 shows the use of the -native option with the -deploy command, used to generate all applicable self-contained application packages for the BrickBreaker application. The -deploy command requires a JAR file as input, so it assumes that dist/BrickBreaker.jar has already been built:

7.3.3 Customizing the Package Using Drop-In Resources

The packaging tools use several built-in resources to produce a package, such as the application icon or configuration files. One way to customize the resulting package is to substitute a built-in resource with your customized version.

The following actions are needed:

  • Learn what resources are used.

  • Drop custom resources into a location where the packaging tool looks for them.

The following sections explain how to use custom resources. Preparing Custom Resources

To get more insight into what resources are being used, enable verbose mode by adding the verbose="true" attribute to <fx:deploy>, or pass the -v option to the javapackager -deploy command.

Verbose mode includes the following actions:

  • The following items are printed:

    • List of configuration resources that are used for the package that you are generating

    • Role of each resource

    • Expected custom resource name

  • A copy of the configuration files and resources used to create the self contained package are saved to a temporary folder. You can use these files as a starting point for customization

Example 7-3 shows sample output, with the important parts in bold:

Now you can grab a copy of the configuration files and tune them to your needs. For example, you can take the configuration file Info.plist and add localized package names.


It is recommended that you disable verbose mode after you are done customizing, or add a custom cleanup action to remove sample configuration files. Substituting a Built-In Resource

Packaging tools look for customized resources on the class path before reverting to built-in resources. The Java Packager has "." (the current working directory) added to the class path by default. Therefore, to replace the application icon, copy your custom icon to ./package/macosx/DemoApp.icns in the directory from which javapackager is run (typically, the root project directory).

The class path for Java Ant tasks is defined when task definitions are loaded. You must add an additional path to the lookup before the path ant-javafx.jar.

Example 7-4 shows how to add "." to the class path. For a more detailed code example, see Example 6-1.

After you provide a customized resource, verbose build output reports that the resource is used. For example, if you added a custom icon to an application, then the verbose output reports the addition, shown in Example 7-5.

7.3.4 Customization Options

Many of the existing Java Ant elements are used to customize self-contained application packages. Different sets of parameters are needed for different packages, and the same element might have different roles. Table 7-1 introduces many of the customization options.

Table 7-1 Customization Options with Ant Elements and Attributes

Element Attribute Details



Application identifier. The format is platform and package specific. If not specified, then a value is generated.


Application version. The default is 1.0.


Short name of the application. Most bundlers use this name to create the name of the output package. If not specified, then the name of the main class is used.



Desktop shortcut request. If set to true, then a desktop shortcut is requested.


Menu entry request. If set to true then an entry in the applications menu is requested.


Scope of installation. If true, a system-wide installation is requested. If false, a user-level installer is requested. Most packagers default to true. See Section 7.4, "Installable Packages" for more information



Role of files in the process of assembling the self-contained application package. Resources of types jnlp and native are not used for building self-contained application packages. Resources of type license are used as a source of content for a click-through license or a license embedded into the package.



Application title.


Application vendor.


Application category. Category names are package-format specific.


License type (for example, GPL). This attribute is used only for Linux bundles.


Short copyright statement.


Application description.


Arguments to pass to the application when it is started.


Types of files to associate with the application.


JVM arguments to be passed to JVM and used to run the application, for example, large heap size.


User-changeable JVM arguments to be passed to JVM and used to run the application. See Section, "Specifying User JVM Arguments" for more information.


Properties to be set in the JVM running the application.

7.3.5 Platform-Specific Customization for Basic Packages

Creating and customizing the basic form of self-contained application packages is a fairly straightforward process, but note the following points: OS X

The resulting package on OS X is an "application bundle".

Several configuration parameters are placed in the Info.plist file in the application bundle and must conform to the following rules:

OS X 10.8 introduces Gatekeeper, which prevents execution of untrusted code by default, regardless of whether this code is implemented in Objective-C or Java.

The user can manually enable the application to run, but this is not a perfect user experience. To get optimal user experience, obtain a Developer ID Certificate from Apple. The Mac bundler uses the certificate to sign the .app folder. If your local user information differs from the name of the certificate, you might need to set the bundle argument mac.signing-key-user-name, as shown in the following example:

For more details, see the Developer ID and Gatekeeper topic at the Apple Developer site.

7.3.7 Associating Files with a Self-Contained Application

The installer for a self-contained application can be set up to register file associations for the application. The <fx:association> element is used in an Ant task to identify the files that can be handled by the application. File associations are based on either the file extension or MIME type.

The following example associates the application with files that have the MIME type application/x-vnd.MyAppFile.

<fx:info title="Association example">
  <fx:association mimetype="application/x-vnd.MyAppFile" description="Sample Test Files">

7.3.8 Supporting Multiple Entry Points

The package for self-contained applications can be built to support a suite of products with more than one entry point. Each entry point can have its own shortcut or icon. The mainClass attribute for the <fx:application> element identifies the primary entry point. Use the <fx:secondaryLauncher> element with the <fx:deploy> task to define each secondary entry point.


Multiple entry points are supported only for Windows and Linux applications.

The following example defines entry points for the TestSuite application for Windows.

<fx:deploy outdir="test/apps" nativeBundles="image">
    <fx:application name="TestSuite Sample"

    <fx:info title="Test Suite"/>

        name="Suite Applications"/>
    <fx:secondaryLauncher name="Editor">
        <fx:bundleArgument arg="icon" value="../resources/editor.ico"/>
    <fx:secondaryLauncher name="Spreadsheet">
        <fx:bundleArgument arg="icon" value="../resources/spreadsheet.ico"/>

7.4 Installable Packages

A self-contained application can be wrapped into a platform-specific installable package to simplify distribution. Java packaging tools provide built-in support for several formats of installable packages, depending on the availability of third-party tools.

Tuning the user experience for the installation process is specific to the particular installer technology, as described in other sections in this chapter. However, you must decide what type of installer you need. The following considerations might help with your decision:

  • System-wide or per-user installation?

    System-wide installation results in a package installed into a shared location and can be used by any user on the system. Admin permissions are typically required and additional steps are likely to be needed during the installation process, such as an OS prompt to approve elevating installer permissions.

    Per-user installation copies the package into a private user directory and does not require admin permissions. This type of installation enables you to show as few dialogs as possible and run the program even if the user is not eligible for admin privileges.

    Note that whenever a user- or system-level installable package is requested, the build procedure itself does not require admin permissions.

  • Do you need a click-through license?

    Some installable packages support showing license text before initiating the installation. The installation process starts only after the user accepts the license.

  • What menu and desktop integration is needed?

    The user should be able to launch your application easily. Therefore, having a desktop shortcut or adding the application to the list of applications in the menu is required.

Note that the current implementation contains many simplifying assumptions. For example, installers never ask the user to choose the location in which to install the package. Developers also have limited control of the installation location, and can only specify system-wide or per-user installation.

If the default assumptions do not meet your needs you, advanced customizations are available by tuning the configuration file templates (see Section 7.3.3, "Customizing the Package Using Drop-In Resources") or packaging a basic self-contained application and then wrapping it into an installable package on your own.

The following installable package formats are supported:

7.4.1 EXE Package

To generate an EXE package, you must have Inno Setup 5 or later installed and available on the PATH. To validate that it is available, try running iscc.exe from the command line where you launch the build or from your build script.

By default, the generated package has the following characteristics:

  • Admin privileges not required

  • Optimized to have a minimum number of dialogs

  • Referenced from the programs menu or a desktop shortcut, or both

  • Launches the application at the end of installation

Figure 7-2 shows a typical dialog box for a self-contained JavaFX application being installed on Windows.

Customization tips:


While the resulting package is displayed in the list of installed applications, it does not use Windows Installer (MSI) technology and does not require the use of GUIDs. See the Inno Setup FAQ for details.

7.4.2 MSI Package

MSI packages are generated using the Windows Installer XML (WiX) toolset (also known as WiX). WiX 3.8 or later is required, and it must be available on the PATH. To validate, try running candle /? from the command line where you launch the build or from your build script.

By default, a generated MSI package has the following characteristics:

  • Optimized for deployment using enterprise deployment tools

  • Installs to a system-wide location

  • No click-through UI, only a progress dialog is shown

  • Referenced from the programs menu or a desktop shortcut, or both

  • Removes all files in the installation folder, even if they were created outside of the installation process. (WiX 3.5 or later is required.)

  • Tries to use the application identifier as UpgradeCode.

    If the application identifier is not a valid GUID, then a random GUID for UpgradeCode is generated.

  • Randomly generates ProductCode is randomly.

    To use a fixed Product code, customize the WiX template file using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

If you plan to distribute your MSI package on the network, sign it for the best user experience.

You can also fine tune the self-contained application folder before it is wrapped into the .msi file, for example, to sign the launcher executable. For details, see Section 7.4.1, "EXE Package."

To add a custom UI to the MSI package, customize the WiX template file used by Java Packager using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources." Consult WiX documentation for more details.

7.4.3 DMG Package

By default, a DMG package provides a simple drag-and-drop installation experience. Figure 7-3 shows an example of the default behavior during installation.

To customize the appearance of the installation window, you can provide a custom background image.

If the background image has different dimensions or you need to position the icons differently, then you must also customize the DMG setup script that is used to modify sizes and positions of elements in the install view. For information on customization, see Section 7.3.3, "Customizing the Package Using Drop-In Resources."

To fine tune the self-contained application folder before it is wrapped, provide your own bash script to be executed after the application folder is populated. You can the script for such actions as adding localization files to the package. Figure 7-4 shows an example of a "tuned" application installer.

To create a Gatekeeper-friendly package (for OS X 10.8 or later, see Section, "OS X"), the application in the DMG package must be signed. It is not necessary to sign the DMG file itself. The Mac bundler handles the signing of your application. If your local user information differs from the name of the certificate, you might need to set the bundle argument mac.signing-key-user-name, as shown in Example 7-6.

To sign the application manually, you can use a technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources" to provide a configuration script that is executed after the application bundle is populated. For the sample DemoApp, the configuration script is located at package/macosx/ and has the content shown in Example 7-7.

The DMG installer also supports a click-though license provided in text format. If use of rich text format is desired, then prepare the license.plist file externally and add it to the package using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

No third party tools are needed to create a DMG package.

7.5 Working Through a Deployment Scenario

Consider a scenario where you have a JavaFX application with the following characteristics:

  • Uses several third-party libraries

  • One of the third-party libraries uses JNI and loads a platform-specific native library using System.loadLibrary()

  • Needs a large 1Gb heap

You want to package this application as a self-contained application that does not need admin permissions to install.

It is assumed that your application works fine as a standalone application, that the main JAR file is built in the dist folder (using <fx:jar>) and that third-party libraries are copied to the dist/lib directory.

One way to assemble a self-contained application package is shown in Example 7-8, and consists of the following actions:

  • Include all application JAR files.

  • Add native libraries applicable to current platform as resources of type data.

    Ensure that the fileset base directory is set to the folder containing the library. This ensures that the libraries are copied to the top-level application folder.

  • Request a user-level installation with <fx:preferences install="false"/>

Note that the top-level application folder is added to the library search path, and therefore System.loadLibrary() can be used.

Example 7-8 shows an example <fx:deploy> task.

Contents    Previous    Next

Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved.