Documentation

The Java™ Tutorials
Hide TOC
Converting an Existing Application
Trail: Deployment
Lesson: Deploying Self-Contained Applications

Converting an Existing Application

Any standalone Java application or Java Web Start application can be packaged as a self-contained application. If you have a Java applet, see Re-writing a Java Applet as a Java Web Start Application for information on converting the applet to a Java Web Start application, which can then be packaged as a self-contained application.

Before converting an application, make sure that you have the required pre-requisites installed for your platform. See Pre-Requisites for Packaging Self-Contained Applications for information.

This section converts the Dynamic Tree Demo from Deploying a Java Web Start Application to a self-contained application. You can download the source files for this demo from Self-Contained Application Examples.

Setting Up the Directories

Identify and organize the files that are needed by your application. A simple application might require only a JAR file. A more complex application might also require additional libraries or resources. Custom resources such as icons or configuration files can also be used by self-contained applications.

The Dynamic Tree Demo requires only the DynamicTreeDemo.jar file, which is in the /dist directory of the project. The HTML and JNLP files that were needed for the Java Web Start version of the application are not needed and are ignored by the bundlers for self-contained applications.

To provide a custom icon for the Dynamic Tree Demo, which represents the application when it is installed on a user's desktop, an icon is provided for each platform supported. These icons are placed in the /src/package/platform directories. The icon is provided in a different format for each supported platform: .ico format for Windows, .png format for Linux, and .icns format for OS X.

The following example shows the directory structure for the Dynamic Tree Demo project before the self-contained bundles are created:

/packager_DynamicTreeDemo     <--- application project
   /dist
      DynamicTreeDemo.jar
      ...
   /src
      /package                <--- custom resources
         /linux
         /macosx
         /windows
      /webstartComponentArch  <--- application source files
      ...

Setting Up the Build File

Set up the Ant tasks for the packaging tasks that are needed. These tasks can be added to the build.xml file for the project, or placed in a separate file that is imported by the build.xml file.

For the Dynamic Tree Demo, the packager.xml file in the root directory of the project contains the Ant tasks for generating the self-contained application bundles. The source for the packager.xml file is shown in the following example:

<project name="DynamicTreePackaging" default="default" basedir="." xmlns:fx="javafx:com.sun.javafx.tools.ant">
    <echo>${java.home}/../lib/ant-javafx.jar</echo>
    <target name="package" depends="jar">
        <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
                 uri="javafx:com.sun.javafx.tools.ant"
                 classpath="${java.home}/../lib/ant-javafx.jar;src"/>

        <fx:deploy outdir="${basedir}/build/packager" 
                   outfile="DynamicTreeDemo"
                   nativeBundles="all"
                   verbose="false">

            <fx:application name="Dynamic Tree Demo"
                        mainClass="webstartComponentArch.DynamicTreeApplication"
                        version="1.0"
            />

            <fx:resources>
                <fx:fileset dir="dist" includes="DynamicTreeDemo.jar"/>
            </fx:resources>

            <fx:info title="Dynamic Tree Demo"
                     vendor="My Company"
                     description="A Demo of a Dynamic Swing Tree"
                     category="Demos"
                     copyright="(c) 2014 My Company"
                     license="3 Clause BSD"
            />

            <fx:bundleArgument arg="linux.bundleName" value="dynamic-tree-demo"/>
            <fx:bundleArgument arg="email" value="maintainer@example.com"/>
            <fx:bundleArgument arg="mac.CFBundleName" value="Java Tree Demo"/>
            <fx:bundleArgument arg="win.menuGroup" value="Java Demos"/>

        </fx:deploy>
    </target>
</project>

Use the following information to set up the Ant tasks:

Generating the Bundles

Run the packaging tasks that you created on the platform for which you want to build the bundle for your self-contained application.

For the Dynamic Tree Demo, run the following command from the root folder for the project:

     ant package

When the packaging task completes, the build/packager/bundles directory in the application project contains the native binaries that were produced.

The following example shows the directory structure for the Dynamic Tree Demo project after the self-contained bundles are generated for Windows:

/packager_DynamicTreeDemo     <--- application project
   /build
      /packager
         /bundles
            Dynamic Tree Demo         <---folder image
            Dynamic Tree Demo-1.0.exe <---EXE installer
            Dynamic Tree Demo-1.0.msi <---MSI installer
      ...   
   /dist
      DynamicTreeDemo.jar
      ...
   /src
      /package                <--- custom resources
         /linux
         /macosx
         /windows
      /webstartComponentArch  <--- application source files
      ...

Note that in addition to the self-contained bundles, the packaging tool always generates the JAR, JNLP, and HTML files for an application. These files provide other options for distributing your application.

Additional References

For more information about self-contained applications, see Self-Contained Application Packaging.

For more information about the Ant tasks for the Java packaging tools, see JavaFX Ant Tasks, which are used for Java and JavaFX applications.


Previous page: Pre-Requisites for Packaging Self-Contained Applications
Next page: Using File Associations