5 Packaging Basics

Table 5-1 summarizes how to accomplish the build steps using the various packaging tools available. Note that javapackager also provides a -makeall macro command to create a complete application package for simple applications. For more information, see Chapter 9, "The Java Packager Tool."

• Entry points: the main application class, JavaFX preloader class, and other details

  Defined as attributes of the <fx:application> tag.

• Parameters to be passed to the application

  Defined using <fx:param> and <fx:htmlParam> tags under <fx:application>.

• The preferred application stage size

  It is crucial to reserve the display area for embedded content.

  Width and height are defined using width and height attributes in the <fx:deploy> tag for Ant tasks, the javapackager -deploy command in the javapackager tool for Windows or Solaris, Linux, and OS X, or in the Run category of NetBeans project properties.

• A description of the application to be used in dialog boxes that the user sees during application startup

  Defined using the <fx:info> tag.

• Platform requirements, including the required version of the JRE and JVM settings

  Defined using the <fx:platform> tag. For an example, see <fx:platform> Parameter to Specify JVM Options.

• Desktop integration preferences of the application, such as adding a shortcut to the desktop or a reference to the Start menu.

  Defined using the optional <fx:preferences> tag. See <fx:preferences> Usage Examples.

• Permissions needed to run the application.

  By default, web applications run in the sandbox. To request elevated permissions, use the <fx:permissions> tag.

Every resource has additional metadata associated with it, such as operating system and architecture for which this resource is applicable, plus a priority preference defining the point in the application life cycle at which this resource is needed. Careful use of metadata can have a significant impact on the application startup experience. For a list of supported values, see Table 10-10.

All files in the resource set are copied to the build output folder. However, not all of the files are used in all execution modes, as described in the following paragraphs.

Regardless of execution mode, all regular JAR files from the resource set are added to the application class path.

Native JAR files and JNLP files are used only for web deployment. Additional JNLP files are typically used to refer to external JNLP extensions, or if the application itself is packaged as a set of components. See Using <fx:resources> for Extension Descriptorsin the JavaFX Ant Task Reference.

Native JAR files are used to deploy native libraries used by application. Each native JAR file can contain a set of native dynamic libraries and is inherently platform-specific. For more details, see Example 5-11 and Section 5.8.3, "Packaging Complex Applications."

License files are currently applicable to self-contained applications only, and are used to add a click-through license to installable packages. See Section 7.4, "Installable Packages."

Data files do not have special semantics, and applications are free to use them for anything. For example, if your application needs to bundle a movie file, then you can mark it as "data," and it is included in the application package.

For further details, see Table 10-10.

Chapter 19, "Deployment in the Browser" describes in detail what hooks are available and how to use them in the code. However, to ensure that the hooks are correctly installed, they also must be specified at packaging time.

To specify callbacks, list them in the <fx:callbacks> tag under <fx:deploy>. Add an <fx:callback> entry for every callback that you want to install, and specify the name of the hook in the name attribute. The content of the <fx:callback> tag is the JavaScript function to be used. You can use a full function definition, or refer to a function defined elsewhere.

The following methods are available for packaging custom JavaScript actions:

• Ant task: See <fx:jar> Usage Examples.

• Java Packager tool: See the -deploy command in the javapackager reference for Windows or Solaris, Linux, and OS X.

• NetBeans IDE: Add callbacks in the Deployment category of Project Properties. Click the Edit button to the right of Custom JavaScript Actions.

An input template is an HTML file containing markers to be replaced with JavaScript or HTML code needed to deploy the application on the web page. Example 5-2 shows an example of an input template for a JavaFX application.

<html>
    <head>
        <title>Host page for JavaFX Application</title>
        #DT.SCRIPT.CODE#
        #DT.EMBED.CODE.ONLOAD#
    </head>
    <body>
        <h1>Embed JavaFX application into existing page</h1>
        <!-- application will be inserted here -->
        <div id="ZZZ"></div>
    </body>
</html>  

#DT.SCRIPT.CODE# and #DT.EMBED.CODE.ONLOAD# are markers that are substituted with JavaScript and HTML code when the template is processed. Markers have the form of #MARKERNAME# or #MARKERNAME(id)#, where id is the identifier of an application (specified using the id attribute of the <fx:deploy> tag if you are using Ant), and MARKERNAME is the type of the marker. If id is not specified, then MARKER matches any application. For a list of supported markers, see <fx:template> in the Ant task reference.

Templates can be used to deploy multiple applications in the same page. Use the full form of the marker including application ID (an alphanumeric string without spaces), and pass the partially processed template file when packaging each application to insert.

Example 5-3 shows an example of a template that is used to deploy multiple applications.

<html>
    <head>
        <title>Page with two application</title>
        <script src="#DT.SCRIPT.URL#"></script>
 
        <!-- code to load first app with id 'firstApp'
             (specified as attribute to fx:application) -->
        <!-- #DT.EMBED.CODE.ONLOAD(firstApp)# -->
 
        <!-- code to load first app with id 'secondApp' -->
        <!-- #DT.EMBED.CODE.ONLOAD(secondApp)# --> 
    </head>
    <body>
        <h1>Multiple applications in the same page</h1>
 
        JavaFX app: <br>
        <!-- First app. Ant task need to use "ZZZ_1 as placeholderId -->
        <div id="ZZZ_1"></div>
 
        Another app: <br>
        <!-- Second app. Ant task need to use "ZZZ_2 as placeholderId -->
        <div id="ZZZ_2"></div>
    </body>
  </html>

Example 5-3 demonstrate one useful feature of the template processor, which is that the markers can be placed in the HTML comments. If the comment does not contain anything other than marker code, then the comment tags are removed from the content in the resulting HTML. This feature keeps the HTML in the template page well formed.

The following methods are available for using templates:

• Ant task: Add a template tag. See <fx:jar> Usage Examples.

• Java Packager tool: See the -deploy command in the javapackager reference for Windows or Solaris, Linux, and OS X.

• NetBeans IDE: Specify the input HTML template file in the Run category of Project Properties.

Java and JavaFX applications support two types of application parameters: named and unnamed (see the API for Application.Parameters).

Static named parameters can be added to the application package using <fx:param> and unnamed parameters can be added using <fx:argument>. They are applicable to all execution modes, including standalone applications.

Parameters can also be passed to Java and JavaFX applications from the web page that hosts the application using <fx:htmlParam>. <fx:htmlParam> is applicable to both embedded applications and Java Web Start applications.

Passing parameters from the HTML page is most useful if the parameters are dynamic. To use this technique, the following approach is recommended:

• Use a web page template (see Section 5.7.4, "Web Page Templates") to provide JavaScript code to prepare dynamic parameters.

• Pass JavaScript code as a value for <fx:htmlParam>, and specify escape="false". The code is evaluated at runtime

Example 5-4 shows the use of various parameter types:

<fx:application name="Test" mainClass="tests.Params">
<!-- unnamed parameters -->
    <fx:argument>Arg1</fx:argument>
    <fx:argument>Arg2 with spaces </fx:argument>
 
    <!-- name parameters -->
    <param name="sampleParam" value="Built with ${java.version}"/>
    <param name="noValueParam"/>
 
    <!-- parameters passed from HTML page -->
    <htmlParam name="staticParamFromWebPage"
               value="(new Date()).getTime()"/>
    <htmlParam name="dynamicParamFromWebPage" escape="false"
               value="(new Date()).getTime()"/>
</fx:application> 

If you use any non-secure JVM options or system properties, the application must have elevated permissions. A set of secure JVM command-line arguments and system properties is defined in the resources Element subsection in the "JNLP File Syntax" section of the Java Web Start Guide.

In Example 5-5, the Ant task packages the application so that when the application is run, the JVM is launched with the following arguments:

-Xmx400 -verbose:jni -Dpurpose=sample

Neither -verbose:jni nor purpose are secure, so elevated permissions are required for Java Web Start and embedded execution modes.

<fx:platform javafx="2.1+">
    <fx:jvmarg value="-Xmx400m"/>
    <fx:jvmarg value="-verbose:jni"/>
    <fx:property name="purpose" value="sample"/>
</fx:platform> 

            <fx:platform>
              <fx:jvmuserarg name="-Xmx" value="768m" />
              <fx:jvmuserarg name="-Xms" value="128m" />
            </fx:platform>

     -BuserJvmOptions=-Xmx=768m
     -BuserJvmOptions=-Xms=128m

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>JVMUserOptions</key>
             <dict>
                          <key>-Xmx</key>
                          <string>400m</string>
            </dict>
</dict>
</plist>

Computer\HKEY_CURRENT_USER\Software\JavaSoft\Prefs\com\companyx\appy\/J/V/M/Options
   name: -Xmx
   type: REG_SZ
   data: 400m

~/.java/.userPrefs/com/companyx/appy/JVMOptions/prefs.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE map SYSTEM "http://java.sun.com/dtd/preferences.dtd">
<map MAP_XML_VERSION="1.0">
  <entry key="-Xmx" value="400m"/>
</map>

<fx:platform>
  <fx:jvmarg value="-Djava.policy.file=$APPDIR/app/whatever.policy"/>
  <fx:jvmuserarg name="-Xmx" value="768m" />
</fx:platform>

• Mark platform-specific resources accordingly.

• For JAR file that a user can double-click, consider packaging everything into a single JAR file and loading native libraries and data files from inside that JAR file.

  Alternatively, if you prefer to have multiple files:

  • Ensure that all dependent JAR files are listed in the <fx:resources> tag in the <fx:jar> task that creates the main JAR file.

  • List all data files and libraries in filesets with type="data" to copy them into the output folder.

  • Load native libraries and resources from locations relative to the main JAR file.

  • See the example <fx:jar> Ant Task for a Simple Application in the Ant Task Reference chapter.

• The following guidelines are for self-contained applications:

  • Avoid packaging anything but the main JAR file using <fx:jar>.

  • List all dependent JAR files in the <fx:resources> section of <fx:deploy> and <fx:jar> for the main application JAR file.

  • Either use an explicit location relative to the application JAR file to load native libraries, or copy native libraries into the root application folder. Use type="data" to copy native library files.

  • See Example 7-4.

• The following guidelines are for Java Web Start and embedded applications:

  • List all dependent JAR files in the <fx:resources> section of <fx:deploy>.

  • Wrap native libraries into the JAR files for distribution.

    Use one JAR file per platform. Ensure that the JAR files contain only native libraries and that the libraries are all in the top-level folder of the JAR file.

  • See Example 5-11.

<jar destfile="${basedir}/build/native-libs-win-x86.jar"
        basedir="native/windows/x86" includes="*"/>
<jar destfile="${basedir}/build/native-libs-win-x86_64.jar"
        basedir="native/windows/x86_64" includes="*"/>
        ....
 
<!-- sign all jar files --->
<signjar keystore="test.keystore" alias="TestAlias" storepass="xyz123">
    <fx:fileset dir="dist" includes="**/*.jar"/>
</signjar>
 
<!-- assemble package -->
<fx:deploy width="600" height="400"
           outdir="${basedir}/${bundle.outdir}"
           outfile="Demo">
    <fx:info title="Demo app"/>
    <fx:application name="${bundle.name}"
                    mainClass="${javafx.main.class}"/>
    <fx:permissions elevated="true"/>
    <fx:resources>
        <!-- jar files with classes and shared data -->
        <fx:fileset dir="dist" includes="*.jar"/>
        <fx:fileset dir="dist" includes="lib/*.jar"/>
       
        <!-- add native libs for deployment descriptor -->
        <fx:fileset dir="build" type="native"
                os="windows" arch="x86">
                includes="native-libs-win-x86.jar"/>
        </fx:fileset>
        <fx:fileset dir="build" type="native"
                    os="windows" arch="x64"
                    includes="native-libs-win-x86_64.jar"/>
        </fx:fileset>
                    ...
    </fx:resources>
</fx:deploy> 

• Specify embeddedWidth="100%" and embeddedHeight="100%" in the <fx:deploy> task. (See Example 5-12.)

• Add a custom web page template. (See Example 5-13 and Section 5.7.4, "Web Page Templates.")

• Reset the style of used HTML elements to ensure that the application is the only element in the view area.

<fx:deploy width="100" height="100"
           embeddedWidth="100%" embeddedHeight="100%"
           outdir="${basedir}/${dist.dir}" outfile="${application.title}">
    <fx:application name="${application.title}"
                    mainClass="${javafx.main.class}"/>
    <fx:template file="${basedir}/web/index_template.html"
                 tofile="${dist.dir}/TestApp.html"/>
    <fx:resources>
        <fx:fileset dir="${basedir}/${dist.dir}" includes="*.jar"/>
    </fx:resources>
    <fx:info title="${application.title}"
             vendor="${application.vendor}"/>
</fx:deploy> 

<html>
    <head>
    <!-- This will be replaced with javascript code to embed the application -->
    <!--        #DT.SCRIPT.CODE#-->
    <!--        #DT.EMBED.CODE.ONLOAD#-->
 
    <!-- Reset html styles to ensure these elements do not waste space -->
        <style>
            html, body {
                margin: 0;
            }
        </style>
    </head>
    <body>
    <!-- Application will be added to the div below -->
        <div id='javafx-app-placeholder'></div>
    </body>
</html> 

• Ant task: See the updatemode attribute of the <fx:deploy> task.

• Java Packager tool: See the -updatemode option of the javapackager -deploy command in the javapackager tool for Windows or Solaris, Linux, and OS X.

• NetBeans IDE: Select Check for Application Updates in Background, In the Deployment category of Project Properties.

You can embed the content of the deployment descriptor into the HTML page, which helps to reduce the number of network connections needed to launch the application, as shown in Figure 5-3.

Figure 5-3 Embedding JNLP Content Reduces Network Connections

Description of "Figure 5-3 Embedding JNLP Content Reduces Network Connections"

The original JNLP file is loaded in the background to perform application update checks.

The following methods are available for embedding the content of the deployment descriptor:

• Ant task: See the embedjnlp attribute of the <fx:deploy> task.

• Java Packager tool: See the -embedjnlp option of the javapackager -deploy command in the javapackager tool for Windows or Solaris, Linux, and OS X.

• NetBeans IDE: The content is embedded by default.

If the application is signed, then this option embeds into the JNLP file a copy of the details of the certificate used to sign the JAR files. If the user needs to approve permissions, this certificate, followed by a security prompt, is shown while the application JAR files are being loaded, as shown in Figure 5-4.

Figure 5-4 Advantage of Embedding the Certificate in the Deployment Descriptor

Description of "Figure 5-4 Advantage of Embedding the Certificate in the Deployment Descriptor"

The following methods are available for embedding the signing certificate into the deployment descriptor:

• Ant task: See the cachecertificates attribute of the <fx:permissions> task.

• Java Packager tool: See the -embedCertificates option of the javapackager -deploy command in the javapackager tool for Windows or Solaris, Linux, and OS X.

Reducing the JAR file size helps to reduce download time and improve startup time. See Section 5.6, "Sign the JAR Files."