3 JavaFX Ant Tasks

This chapter shows how to use Ant to package Java and JavaFX applications.

JavaFX Ant tasks and the Java Packager tool are the recommended ways to package your applications.

This chapter contains the following topics:

See also the following two Ant Task Reference sections:

Requirements to Run JavaFX Ant Tasks

The ant-javafx.jar file is required to use these tasks. It is located in the following locations:

In JDK 7 Update 6 or later, it is located in jdk_home/lib
In a standalone JavaFX installation, it is located in javafx-sdk-home/lib

JavaFX Ant Elements

There are two categories of Ant elements: JavaFX Ant tasks and Ant helper parameters.

JavaFX Ant Tasks

JavaFX Ant tasks perform the following tasks:

Creating JAR files that can be double-clicked
Creating an HTML page and deployment descriptor for Web Start applications or applications embedded in a web page
Digitally signing an application, when necessary
Converting CSS files to binary format
Assembling self-contained application packages

Elements are described in JavaFX Ant Task Reference.

Ant Helper Parameters

Ant helper parameters are used by the JavaFX Ant tasks. The helper parameters are described in JavaFX Ant Helper Parameter Reference.

Using JavaFX Ant Tasks

To use the JavaFX Ant tasks in your Ant script, you must load their definitions. An example is shown in the build.xml file in Example 3-1.

Notes about Example 3-1:

Ensure that you declare the fx: namespace, shown in bold in Example 3-1, because short names for some of JavaFX tasks are the same as those used for some system tasks.
The current directory (".") is added to the classpath to simplify customization using drop-in resources. See Customizing the Package Using Drop-In Resources.

After JavaFX Ant task definitions are loaded, the javafx.ant.version property can be used to check the version of Ant tasks APIs. Use the following list for version numbers:

Version 1.0: shipped in the JavaFX 2.0 SDK
Version 1.1: shipped in the JavaFX 2.1 SDK
Version 1.2: shipped in the JavaFX 2.2 SDK and JDK 7 Update 6

Example 3-1 Load JavaFX Ant Task Definitions

<project name="JavaFXSample" default="default" basedir="."
         xmlns:fx="javafx:com.sun.javafx.tools.ant">
    <target name="default">
        <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"      
                uri="javafx:com.sun.javafx.tools.ant"
                classpath=".:${JAVA_HOME}/lib/ant-javafx.jar"/>    
    </target>
</project>

Ant Script Examples

This section covers the following topics:

Deploying the JavaFX Hello World Example

Follow these steps to deploy the JavaFX Hello World example as a JAR file with an Ant script:

Create a directory to contain the example application. These steps use the directory C:\example.
Save Example 3-2 as C:\example\src\HelloWorld.java.
Save Example 3-3 as C:\example\build.xml.
In the file build.xml, specify the ___location of the JDK installed in your computer by changing the value of the JAVA_HOME property. Change the highlighted text to the full path of your JDK:
```
<property name="JAVA_HOME" value="C:\\Java\\jdk-9"/>
```
At a command-line prompt, change directory to C:\example. Run the following command to compile, build, and deploy the JavaFX HelloWorld example:
```
ant
```
To run the example, at a command-line prompt, change directory to C:\example\dist and run the following command:
```
java -jar HelloWorld.jar
```

Example 3-2 HelloWorld.java

import javafx.application.Application;
import javafx.event.ActionEvent;
import javafx.event.EventHandler;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.StackPane;
import javafx.stage.Stage;
 
public class HelloWorld extends Application {
    
    @Override
    public void start(Stage primaryStage) {
        Button btn = new Button();
        btn.setText("Say 'Hello World'");
        btn.setOnAction(new EventHandler<ActionEvent>() {
 
            @Override
            public void handle(ActionEvent event) {
                System.out.println("Hello World!");
            }
        });
        
        StackPane root = new StackPane();
        root.getChildren().add(btn);
 
        Scene scene = new Scene(root, 300, 250);
 
        primaryStage.setTitle("Hello World!");
        primaryStage.setScene(scene);
        primaryStage.show();
    }
 public static void main(String[] args) {
        launch(args);
    }
}

Example 3-3 Ant Script to Deploy JavaFX Hello World Example

<?xml version="1.0" encoding="UTF-8" ?>
 
<project name="JavaFX Hello World Example" default="default" basedir="."
  xmlns:fx="javafx:com.sun.javafx.tools.ant">
 
  <property name="JAVA_HOME" value="C:\\Java\\jdk-9"/>
  <property name="build.src.dir" value="src"/>
  <property name="build.classes.dir" value="classes"/>
  <property name="build.dist.dir" value="dist"/>
 
  <target name="default" depends="clean,compile">
 
    <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
      uri="javafx:com.sun.javafx.tools.ant"
      classpath="${JAVA_HOME}/lib/ant-javafx.jar"/>
 
      <fx:application id="HelloWorldID"
        name="JavaFXHelloWorldApp"
        mainClass="HelloWorld"/>
 
      <fx:resources id="appRes">
        <fx:fileset dir="${build.dist.dir}" includes="HelloWorld.jar"/>
      </fx:resources>
 
      <fx:jar destfile="${build.dist.dir}/HelloWorld.jar">
        <fx:application refid="HelloWorldID"/>
        <fx:resources refid="appRes"/>
        <fileset dir="${build.classes.dir}"/>
      </fx:jar>
 
      <fx:deploy width="300" height="250"
        outdir="." embedJNLP="true"
        outfile="helloworld">
 
        <fx:application refId="HelloWorldID"/>
 
        <fx:resources refid="appRes"/>
 
        <fx:info title="JavaFX Hello World Application"
          vendor="Oracle Corporation"/>
 
      </fx:deploy>
 
  </target>
 
  <target name="clean">
    <mkdir dir="${build.classes.dir}"/>
    <mkdir dir="${build.dist.dir}"/>

    <delete>
      <fileset dir="${build.classes.dir}" includes="**/*"/>
      <fileset dir="${build.dist.dir}" includes="**/*"/>
    </delete>
 
  </target>
 
  <target name="compile" depends="clean">
 
    <javac includeantruntime="false"
      srcdir="${build.src.dir}"
      destdir="${build.classes.dir}"
      fork="yes"
      executable="${JAVA_HOME}/bin/javac"
      source="9"
      debug="on">
    </javac>
  </target>
 
</project>

Deploying the JavaFX Hello World Example as a Self-Contained Application

To deploy the JavaFX Hello World example as a self-contained application, add the attribute nativeBundles="all" to the element <fx:deploy> in the build.xml script:

<fx:deploy width="300" height="250"
  outdir="." embedJNLP="true"
  outfile="helloworld"
  nativeBundles="all">

Compile, build, and deploy the JavaFX Hello World example as described in the previous section. The Ant script creates all applicable self-contained application packages and stores them in the directory C:\example\bundles\JavaFXHelloWorldApp. (The name JavaFXHelloWorldApp is the value of the name attribute of the <fx:application> element.) If you are deploying the JavaFX Hello World example with Windows, for example, the Ant script creates an application named C:\example\bundles\JavaFXHelloWorldApp\JavaFXHelloWorldApp.exe that you can run by double-clicking it in a file browser.

You can customize how your Ant script creates self-contained applications. See Self-Contained Application Packaging.

Deploying a JavaFX Application with External JAR Files

The JavaFX Ensemble8 sample application requires Apache Lucene. Example 3-4 shows how to deploy Ensemble8 as a self-contained application and include the Apache Lucene JAR files in it.

The following lines in the Ant script copy resources contained in the src directory to the directory that contains the compiled Java class files. The resources are copied after the Ant script compiles the sample application:

      <copy todir="${build.classes.dir}">
        <fileset dir="src/app/resources"/>
        <fileset dir="src/generated/resources"/>
        <fileset dir="src/samples/resources"/>
      </copy>

The following lines from the Ant script include the Apache Lucerne JAR files (which are contained in the lib directory):

      <fx:resources id="appRes">
        <fx:fileset dir="${build.dist.dir}"
          includes="ensemble8.jar"/>
        <fx:fileset dir="lib"/>
        <fx:fileset dir="${build.classes.dir}"/>
      </fx:resources>
 
      <fx:jar destfile="${build.dist.dir}/ensemble8.jar">
        <fx:application refid="ensemble8"/>
        <fx:resources refid="appRes"/>
      </fx:jar>

Example 3-4 Ant Script to Deploy Ensemble8 Sample Application

<?xml version="1.0" encoding="UTF-8" ?>
 
<project name="Ensemble8 JavaFX Demo Application" default="default" basedir="."
  xmlns:fx="javafx:com.sun.javafx.tools.ant">
 
  <property name="JAVA_HOME" value="C:\\Java\\jdk-9"/>
 
  <path id="CLASSPATH">
    <pathelement ___location="lib/lucene-core-3.2.0.jar"/>
    <pathelement ___location="lib/lucene-grouping-3.2.0.jar"/>
    <pathelement path="classes"/>
  </path>
  
  <property name="build.src.dir" value="src"/>
  <property name="build.classes.dir" value="classes"/>
  <property name="build.dist.dir" value="dist"/>
 
  <target name="default" depends="clean,compile">
 
    <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
      uri="javafx:com.sun.javafx.tools.ant"
      classpath="${JAVA_HOME}/lib/ant-javafx.jar"/>
 
      <fx:application id="ensemble8"
        name="Ensemble8"
        mainClass="ensemble.EnsembleApp"/>
 
      <fx:resources id="appRes">
        <fx:fileset dir="${build.dist.dir}" includes="ensemble8.jar"/>
        <fx:fileset dir="lib"/>
        <fx:fileset dir="${build.classes.dir}"/>
      </fx:resources>
 
      <fx:jar destfile="${build.dist.dir}/ensemble8.jar">
        <fx:application refid="ensemble8"/>
        <fx:resources refid="appRes"/>
      </fx:jar>
 
      <fx:deploy outdir="." embedJNLP="true"
        outfile="ensemble8"
        nativeBundles="all">
 
        <fx:application refId="ensemble8"/>
 
        <fx:resources refid="appRes"/>
 
        <fx:info title="Ensemble8 JavaFX Demo Application"
          vendor="Oracle Corporation"/>
 
      </fx:deploy>
 
  </target>
 
  <target name="clean">
    <mkdir dir="${build.classes.dir}"/>
    <mkdir dir="${build.dist.dir}"/>
 
    <delete>
      <fileset dir="${build.classes.dir}" includes="**/*"/>
      <fileset dir="${build.dist.dir}" includes="**/*"/>
    </delete>
 
  </target>
 
  <target name="compile" depends="clean">
 
    <javac includeantruntime="false"
      srcdir="${build.src.dir}"
      destdir="${build.classes.dir}"
      fork="yes"
      executable="${JAVA_HOME}/bin/javac"
      source="9"
      debug="on"
      classpathref="CLASSPATH">
    </javac>
    
    <!-- Copy resources to build.classes.dir -->
    
      <copy todir="${build.classes.dir}">
        <fileset dir="src/app/resources"/>
        <fileset dir="src/generated/resources"/>
        <fileset dir="src/samples/resources"/>
      </copy>
    
  </target>
 
</project>

Overriding JVM Options for Self-Contained Applications

You can override JVM options in your self-contained applications by specifying them in a preferences node, then setting the name of this node in the app.preferences.id system property. The following example overrides the -Xms and -Xmx JVM options specified in <fx:jvmuserarg> elements. To verify that these options have been overridden, the application displays the initial and maximum sizes of the memory allocation pool (based on the values of the -Xms and -Xmx options).

Create a directory to contain the example application. These steps use the directory C:\memexample.
Save Example 3-5 as C:\memexample\src\MemoryExamplePreferences.java.
The following statement retrieves the java.util.prefs.Preferences node that stores the values of the options -Xms and -Xmx in your computer:
```
prefs = Preferences.userRoot().node(System.getProperty("app.preferences.id")).node("JVMUserOptions");
```
The name of this node is app.preferences.id/JVMUserOptions. The value of the app.preferences.id property is the value of the id attribute of the <fx:application> element. In this example, the value of app.preferences.id is MemoryTestAppID. When you run a self-contained application, the launcher program sets the system property automatically. However, if you run the class directly, you must specify the value of app.preferences.id as a system property. For example, if you run this class from the command line, you would specify the value of app.preferences.id as follows:
```
java -cp classes -Dapp.preferences.id=MemoryTestAppID
```
Note that in this example, the Ant build script runs the MemoryTestPreferences class for you and sets the value of the app.preferences.id property.

For example, if you are using Microsoft Windows, then this class creates a preferences node named Computer\HKEY_CURRENT_USER\Software\JavaSoft\Prefs\MemoryTestAppID\JVMUserOptions in the Windows registry.
Save Example 3-6 as C:\memexample\src\MemoryExample.java.

Save Example 3-7 as C:\memexample\build.xml.

This Ant script compiles and runs the MemoryTestPreferences class, and sets the value of the app.preferences.id property:

        <java fork="true" jvm="${env.JAVA_HOME}\bin\java"
              classname="MemoryTestPreferences" classpath="${build.classes.dir}">
            <sysproperty key="app.preferences.id" value="MemoryTestAppID"/>
        </java>

In the file build.xml, specify the ___location of the JDK installed in your computer by changing the value of the JAVA_HOME property. Change the highlighted text to the full path of your JDK:
```
<property name="JAVA_HOME" value="C:\\Java\\jdk-9"/>
```
At a command-line prompt, change directory to C:\memexample. Run the following command to compile, build, and deploy this example:
```
ant
```
To run the Memory Test application, run one of the applications contained in C:\memexample\bundles\bundles/JavaFXMemoryTestApp.
In addition to the initial and maximum sizes of the memory allocation pool, the example displays the JVM arguments that it uses:
```
-Djava.library.path=C:\memexample\bundles\JavaFXMemoryTestApp\app\
-Dapp.preferences.id=MemoryTestAppID
-Xms2048m
-Xmx2048m
```
Note that the Ant build script uses <fx:jvmuserarg> elements to specify the initial and maximum sizes of the memory allocation pool as 31m and 64m, respectively. However, the Ant script in this example runs another program that stores the preferred values of 2048m and 2048m in the Preferences node before the application is run, so those values are used instead.

Example 3-5 MemoryExamplePreferences.java

import java.util.prefs.Preferences;
 
public class MemoryTestPreferences {
  private Preferences prefs;
 
  public void setPreferences() {
 
    // This will define a node in which the preferences can be stored
    prefs = Preferences.userRoot().node(System.getProperty("app.preferences.id")).node("JVMUserOptions");
 
    // now set the values
    prefs.put("-Xmx", "2048m");
    prefs.put("-Xms", "2048m");
 
  }
 
  public static void main(String[] args) {
    MemoryTestPreferences myPrefs = new MemoryTestPreferences();
    myPrefs.setPreferences();
  }
}

Example 3-6 MemoryExample.java

import javafx.application.Application;
import javafx.collections.FXCollections;
import javafx.geometry.HPos;
import javafx.geometry.Insets;
import javafx.geometry.Pos;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.control.ListView;
import javafx.scene.control.TextField;
import javafx.scene.layout.ColumnConstraints;
import javafx.scene.layout.GridPane;
import javafx.scene.layout.Priority;
import javafx.scene.layout.Region;
import javafx.stage.Stage;
 
import java.lang.management.ManagementFactory;
import java.util.prefs.BackingStoreException;
import java.util.prefs.Preferences;
 
public class MemoryTest extends Application {
 
    @Override
    public void start(Stage primaryStage) {
        String startMemory = Long.toString(Runtime.getRuntime().totalMemory());
        String maxMemory = Long.toString(Runtime.getRuntime().maxMemory());
 
        System.out.println("Start memory: " + startMemory);
 
        System.out.println("Max memory: " + maxMemory);
 
        final Label startMemoryLabel = new Label("Start memory: ");
        TextField startMemoryTextField = new TextField(startMemory);
        startMemoryTextField.setPromptText(startMemory);
 
        Label maxMemoryLabel = new Label("Max memory: ");
        final TextField maxMemoryTextField = new TextField(maxMemory);
        maxMemoryTextField.setPromptText(maxMemory);
 
        Label jvmArgumentsLabel = new Label("JVM Arguments");
        ListView<String> jvmArguments = new ListView<>(FXCollections.observableArrayList(ManagementFactory.getRuntimeMXBean().getInputArguments()));
        jvmArguments.setPrefSize(450, 150);
 
        Button btn = new Button();
        btn.setText("Update Preferences");
        btn.setOnAction(event -> {
            Preferences prefs = Preferences.userRoot().node(System.getProperty("app.preferences.id")).node("JVMUserOptions");
            String start = startMemoryTextField.getText();
            if (start == null || start.isEmpty()) {
                prefs.remove("-Xms");
            } else {
                prefs.put("-Xms", start);
            }
 
            String max = maxMemoryTextField.getText();
            if (max == null || max.isEmpty()) {
                prefs.remove("-Xmx");
            } else {
                prefs.put("-Xmx", max);
            }
 
            try {
                prefs.flush();
            } catch (BackingStoreException e) {
                e.printStackTrace();
            }
        });
 
 
        GridPane grid = new GridPane();
        grid.setAlignment(Pos.CENTER);
        grid.setHgap(10);
        grid.setVgap(10);
        grid.setPadding(new Insets(25, 25, 25, 25));
        grid.getColumnConstraints().setAll(
                new ColumnConstraints(Region.USE_PREF_SIZE, Region.USE_COMPUTED_SIZE, Region.USE_PREF_SIZE, Priority.NEVER, HPos.RIGHT, false),
                new ColumnConstraints(Region.USE_PREF_SIZE, Region.USE_COMPUTED_SIZE, Integer.MAX_VALUE, Priority.ALWAYS, HPos.LEFT, true)
        );
 
        grid.addRow(0, startMemoryLabel, startMemoryTextField);
        grid.addRow(1, maxMemoryLabel, maxMemoryTextField);
        grid.addRow(2, jvmArgumentsLabel, jvmArguments);
        grid.add(btn, 1, 3);
        grid.setMinSize(Region.USE_PREF_SIZE, Region.USE_PREF_SIZE);
 
 
        Scene scene = new Scene(grid);
 
        primaryStage.setTitle("Memory test");
        primaryStage.sizeToScene();
        primaryStage.setScene(scene);
        primaryStage.show();
    }
 
    public static void main(String[] args) {
        launch(args);
    }
}

Example 3-7 Ant Script for Memory Test Example

<?xml version="1.0" encoding="UTF-8" ?>
 
<project name="JavaFX Hello World Example" default="default" basedir="."
         xmlns:fx="javafx:com.sun.javafx.tools.ant">
 
    <property environment="env"/>
    <property name="env.JAVA_HOME" value="C:\\Java\\jdk-9"/>
    <property name="build.src.dir" value="src"/>
    <property name="build.classes.dir" value="classes"/>
    <property name="build.dist.dir" value="dist"/>
 
    <target name="default" depends="clean,compile">
 
        <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
                 uri="javafx:com.sun.javafx.tools.ant"
                 classpath="${env.JAVA_HOME}/lib/ant-javafx.jar"/>
 
      <fx:application id="MemoryTestAppID"
                        name="JavaFXMemoryTestApp"
                        mainClass="MemoryTest"/>
 
        <fx:resources id="appRes">
            <fx:fileset dir="${build.dist.dir}" includes="MemoryTest.jar"/>
        </fx:resources>
 
        <fx:jar destfile="${build.dist.dir}/MemoryTest.jar">
        <fx:application refid="MemoryTestAppID"/>
            <fx:resources refid="appRes"/>
            <fileset dir="${build.classes.dir}"/>
        </fx:jar>
 
        <fx:deploy width="300" height="250"
                   outdir="." embedJNLP="true"
                   outfile="memorytest"
                   nativeBundles="image">
 
            <fx:platform>
                <fx:jvmuserarg name="-Xms" value="31m"/>
                <fx:jvmuserarg name="-Xmx" value="64m"/>
            </fx:platform>
 
        <fx:application refId="MemoryTestAppID"/>
 
            <fx:resources refid="appRes"/>
 
            <fx:info title="JavaFX Hello World Application"
                     vendor="Oracle Corporation"/>
 
        </fx:deploy>
 
    </target>
 
    <target name="clean">
        <mkdir dir="${build.classes.dir}"/>
        <mkdir dir="${build.dist.dir}"/>
 
        <delete>
            <fileset dir="${build.classes.dir}" includes="**/*"/>
            <fileset dir="${build.dist.dir}" includes="**/*"/>
        </delete>
 
    </target>
 
    <target name="compile" depends="clean">
 
        <javac includeantruntime="false"
               srcdir="${build.src.dir}"
               destdir="${build.classes.dir}"
               fork="yes"
               executable="${env.JAVA_HOME}/bin/javac"
               source="9"
               debug="on">
        </javac>
 
        <!-- Set preferences -->
 
        <java fork="true" jvm="${env.JAVA_HOME}\bin\java"
              classname="MemoryTestPreferences" classpath="${build.classes.dir}">
            <sysproperty key="app.preferences.id" value="MemoryTestAppID"/>
        </java>
    </target>
 
    <target name="jar" depends="compile">
        <jar destfile="dist/MemoryTest.jar"
             basedir="classes"/>
    </target>
 
</project>

The UserJvmOptionsService API offers an alternative method for setting JVM options for self-contained applications. This API can be called from the application to get the current settings and to update the settings for the next time that the application is started.

JavaFX Ant Task Reference

The following items comprise the main JavaFX Ant tasks:

<fx:csstobin>

Converts CSS files to binary format for faster processing.
<fx:deploy>

Assembles the application package for redistribution. By default, the deploy task will generate the base application package, but it can also generate self-contained application packages if requested.
<fx:jar>

Creates one or more application JAR files.
<fx:signjar>

Provides the application with a digital signature.

Note:
The <fx:signjar> task for the Java Packager tool is deprecated in JDK 9 in preparation for removal in a future release. It also does not work with multi-release JAR files. Use the standard Ant signjar task instead.

Items are in alphabetical order.

<fx:csstobin>

Description

Converts a set of CSS files into binary form (BSS).

Parent Elements

None.

Parameters

Attribute	Description	Type	Required?
`outdir`	Name of the directory in which output files are generated.	String	Yes

Parameters Accepted as Nested Elements

<fx:fileset>

<fx:csstobin> Task Usage Examples

Example 1 Convert CSS Files to Binary

This example converts all CSS files in the output tree to binary form.

<fx:csstobin outdir="build/classes">
    <fileset dir="build/classes" includes="**/*.css"/>
</fx:csstobin>

<fx:deploy>

Description

Generates a package for both web deployment and standalone applications. The package includes a set of JAR files, a JNLP file, and an HTML file.

Parent Elements

None.

Parameters

Attribute	Description	Type	Required?
`embeddedHeight`	If present, this value will be used for Javascript/HMTL code instead of width/height. Affects only embedded deployment mode. Use it if you want to specify a relative dimension for an embedded application.	String	No
`embeddedWidth`	Same description as for `embeddedHeight`.	String	No
`embedjnlp`	If true, embed the JNLP descriptor into the web page. Reduces number of network connections to be made on startup and helps to improve startup time.	Boolean	No Default is `false`.
`extension`	Treat the files named in `srcfiles` as extensions. If present, only a portion of the deployment descriptor is generated, and the HTML file is not generated.	Boolean	No Default is `false`.
`height`	Height of the application scene, for embedding applications into a web page.	String	Yes
`includeDT`	If set to `true`, files related to the Deployment Toolkit will be copied to a `web-files` subdirectory of the directory specified in `outdir`. This setting is useful for offline development but is not advised for production.	Boolean	No Default is `false`.
`nativeBundles`	Values: all deb dmg exe image installer jnlp mac.appStore msi none pkg rpm Value `all` produces all applicable self-contained application packages for the platform on which the Ant tasks are run. Value `installer` produces only installable packages, not a disk image. Value `jnlp` produces only the `.jnlp` and `.html` files for a Java Web Start application. Value `none` produces no self-contained application packages. Other values produce a specific package installer.	String	No Default is `none`.
`offlineAllowed`	If the value is `true`, the cached application can operate even if the client system is disconnected from the network.	Boolean	Default is `true`.
`outdir`	Name of the directory in which output files are generated.	String	Yes
`outfile`	Prefix of the output files, without the extension.	String	Yes
`placeholderref`	Placeholder in the web page where the application will be embedded. This is expected to be JavaScript DOM object.	String	Yes Either reference or ID of placeholder is required.
`placeholderid`	Used with callbacks. The ID of the placeholder in the web page where application will be embedded. The JavaScript function `document.getElementById()` is used to resolve it.	String	Yes Either the reference or the ID of the placeholder is required.
`signBundle`	Used for self-contained applications to request that the bundler sign the bundle that is generated. This attribute is ignored by bundlers that do not support signing. At the time of the 8u40 release of the JDK, only macOS bundlers support signing.	Boolean	Default depends on the bundler used.
`updatemode`	Indicates the preferences for when checks for application updates are performed for embedded and Web Start applications. A value of `always` means to always check for updates before launching the application. A value of `background` means to launch the application while checking for updates in the background.	String	No Default is `background`.
`width`	Width of the application scene, for embedding applications into a web page.	String	Yes

Parameters Accepted as Nested Elements

<fx:deploy> Task Usage Examples

Example 1 Minimal <fx:deploy> Task

This is a simple example of an <fx:deploy> Ant task. It generates an HTML file and JNLP file into the web-dist directory and uses Fish as the prefix for the generated files.

<fx:deploy width="600" height="400"
        outdir="web-dist" outfile="Fish" 
        offlineAllowed="false">
    <fx:info title="Sample application"/>
    <fx:application refid="myapp"/>
    <fx:resources refid="myresources"/>
</fx:deploy>

Example 2 <fx:deploy> Task for an Application with a Preloader

The following Ant task creates a distributable package for a simple application with a preloader. Details about the application and its resources are defined in the <fx:application> and <resource> elements in the task.

Note that the ___location of the output package is defined by the outdir attribute of the <fx:deploy> task. New files are generated using the name prefix specified in the outfile attribute. As a result of execution of this task, the following files are created in the web-dist folder:

preloader.jar
helloworld.jar
App.jnlp
App.html

Note:

By default, the deployment package uses auxiliary files from java.com to support web deployment. This is the preferred way, because it enables the application to always use the best way to deploy on the web. However, if you want to test your application in a closed network then you can include these files into your application package. To do this, pass includeDT="true" as an attribute in the <fx:deploy> Ant task.

<fx:deploy width="600" height="400"
        outdir="web-dist" outfile="App">
    <fx:info title="Sample application"/>
    <fx:application name="SampleApp" 
            mainClass="testapp.MainApp"
            preloaderClass="testpreloader.Preloader">
        <fx:param name="testVariable" value="10"/>
    </fx:application>
    <fx:resources>
        <fx:fileset requiredFor="preloader" dir="dist">
            <include name="preloader.jar"/>
        </fx:fileset>
        <fx:fileset dir="dist">
            <include name="helloworld.jar"/>
        </fx:fileset>
    </fx:resources>
</fx:deploy>

Example 3 <fx:deploy> Task with Secondary Launchers

This example creates a package for a self-contained application that contains a secondary launcher that can be used to start the application in a memory-constrained environment. The main launcher does not set JVM options. The secondary launcher passes an option to limit the amount of memory used.

<fx:deploy outdir="../samples/test/ant" nativeBundles="image">
    <fx:application name="Secondary Launcher Sample"
                    mainClass="hello.Test"/>

    <fx:resources>
        <fx:fileset dir="../samples/test/resources" includes="mainApp.jar"/>
    </fx:resources>

    <fx:info title="Secondary Launcher Test"/>

    <fx:secondaryLauncher
        mainClass="hello.Test"
        name="Standard Launch"/>
 
    <fx:secondaryLauncher name="Memory Constrained">
        <fx:jvmarg="-xmx64m"/>
    </fx:secondaryLauncher>
</fx:deploy>

Example 4 <fx:deploy> Task for modular application with a custom runtime

<fx:deploy outdir="${bundles.dir}"
    outfile="MinesweeperFX"
    nativeBundles="all"
    verbose="true"

  <fx:runtime strip-native-commands="false">
    <fx:add-modules value="java.base"/>
    <fx:add-modules value="jdk.packager.services,javafx.controls"/>
    <fx:limit-modules value="java.sql"/>
    <fx:limit-modules value="jdk.packager.services,javafx.controls"/>
    <fx:module-path value="${java.home}/../images/jmods"/>
    <fx:module-path value="${build.dir/modules"/>
  </fx:runtime>

  <fx:application id="MinesweeperFX"
      name="MinesweeperFX"
      module="fx.minesweeper"
      mainClass="minesweeper.Minesweeper"
      version="1.0">
  </fx:application>

  <fx:secondaryLauncher name="Test2"
      module="hello.world"
      mainClass="com.greetings.HelloWorld">
  </fx:secondaryLauncher>
</fx:deploy>

<fx:jar>

Description

Packages an application into a JAR file. The set of files to be included is defined by nested <fx:fileset> parameters. The <fx:jar> task also embeds a JAR manifest into the JAR file.

In addition to creating a JAR archive, this task also:

Embeds the JavaFX launcher for JavaFX applications, which detects the presence of JavaFX Runtime, sets up the environment, and executes the application.
Creates a manifest in the JAR file.

The resulting JAR file supports launching by double-clicking.

Parent Elements

None.

Parameters

Attribute	Description	Type	Required?
`codebase`	Base ___location for all relative URLs specified in `href` attributes in the JNLP file.	String	No
`destfile`	Path to output JAR file (___location and name)	String	Yes

Parameters Accepted as Nested Elements

<fx:jar> Usage Examples

See Example 3-3 and the following example.

Example 1 <fx:jar> Ant Task for a Simple Application

This example shows how to use the <fx:jar> Ant task to create the main application JAR file for a simple application without a custom preloader. The resulting JAR file performs the following two actions:

Starts test.MyApplication with all resources needed on the classpath when launched as java -jar application.jar or by double-clicking the JAR file.
Automatically detects the ___location of JavaFX Runtime and prompts the user to install it if it is not available, or reports if the platform is not supported.

<!-- Expect definition of JavaFX ant tasks is already imported -->
 
<fx:jar destfile="dist/application.jar">
    <!-- Details about application -->
    <fx:application name="Sample JavaFX application"
            mainClass="test.MyApplication"/>
 
    <!-- Define what auxilary resources are needed -->
    <fx:resources>
        <fx:fileset dir="dist" includes="lib/*.jar"/>
    </fx:resources>
            
    <!-- What to include into result jar file?
         Everything in the build tree -->
    <fileset dir="build/classes"/>
 
    <!-- Customize jar manifest (optional) -->
    <manifest>
        <attribute name="Implementation-Vendor" value="Samples Team"/>
        <attribute name="Implementation-Version" value="1.0"/>
    </manifest>
</fx:jar>

<fx:signjar>

Description

Note:

The <fx:signjar> task for the Java Packager tool is deprecated in JDK 9 in preparation for removal in a future release. It also does not work with multi-release JAR files. Use the standard Ant signjar task instead.

Digitally signs an application JAR file with a certificate.

Signs the JAR file as BLOB. In other words, instead of every entry being signed separately, the JAR file is signed as a single binary object.

Parent Elements

None.

Parameters

Attribute	Description	Type	Required?
`alias`	The alias for the key	String	Yes
`destdir`	Location of output file	String	Yes
`keypass`	Password for the private key	String	Yes
`keystore`	Keystore file name	File	Yes
`jar`	The JAR file to sign*	String	No Either this attribute or a nested `<fx:fileset>` element is required.
`storepass`	Password to check integrity of the keystore or unlock the keystore	String	Yes
`storetype`	Keystore type	String	No Default is `jks`.
`verbose`	Enable verbose output.	Boolean	No Default is `false`.

*Note that:

<fx:signjar jar="path/to/jar/folder/jarname" .../>

is simply a convenience syntax for the following:

<fx:signjar ...>
    <fileset dir="path/to/jar/folder" file="jarname"/> 
</fx:signjar>

Parameters Accepted as Nested Elements

<fx:fileset>

<fx:signjar> Usage Examples

Example 1 Sign JAR Files

The following snippet of Ant code shows how to sign JAR files using the new sign as BLOB technique.

<fx:signjar destdir="dist"
        keyStore="sampleKeystore.jks" storePass="****"
        alias="javafx" keyPass="****">
    <fileset dir='dist/*.jar'/>
</fx:signjar>

JavaFX Ant Helper Parameter Reference

Helper parameters are types that are used by the JavaFX tasks described in JavaFX Ant Task Reference. This reference page contains the following elements:

Items are in alphabetical order.

<fx:add-modules>

Description

List of modules to add to the runtime generated for a self-contained application. All modules can be added in a single instance of <fx:add-modules> using a comma-separated list, or an instance of <fx:add-modules> can be used for each module to add.

Parent Elements

<fx:runtime>

Parameters

Attribute	Description	Type	Required?
`value`	One or more modules to include in the runtime. For more than one, separate the modules with a comma.	String	No

Parameters Accepted as Nested Elements

None.

<fx:add-modules> Usage Examples

Example 1 Include modules from jdk.packager.services and javafx.controls in the runtime

Use a single instance of <fx:add-modules>:

<fx:runtime>
  <fx:add-modules value="jdk.packager.services,javafx.controls"/>
</fx:runtime>

Use an instance of <fx:add-modules> for each module:

<fx:runtime>
  <fx:add-modules value="jdk.packager.services"/>
  <fx:add-modules value="javafx.controls"/>
</fx:runtime>

<fx:application>

Description

Basic application descriptor. It defines the main components and default set of parameters of the application.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required?
`daemon`	Indicates if the application is installed as a daemon or a service.	Boolean	No Default value is `false`.
`id`	Application ID that can be used to get a JavaScript reference to the application in HTML. The same ID can be used to refer to an application object in the Ant task (using `refid`).	String	No
`mainClass`	Qualified name of the main application class, which should extend `javafx.application.Application`	String	Yes
`module`	Main module of a modular application. This is used as the default root module when constructing the application's initial module graph.	String	Yes, if bundling a modular application. Invalid if the application is not modular.
`name`	Short name of the application. For self-contained applications, also defines the name of the output package.	String	No Default value is derived from the main application class.
`preloaderClass`	Qualified name of the preloader class, which should extend `javafx.application.Preloader`	String	No Default is the preloader that is shipped with the JavaFX Runtime.
`refid`*	--	Reference	No
`toolkit`	Indicates your preference for the application to use a specific UI toolkit. Possible values: fx swing	String	No Default value is `fx`.
`version`	Version of the application being packaged.	String	No Default value is 1.0.

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

<fx:application> Usage Examples

Example 1 Application description for non-modular application

<fx:application id="HelloWorldID"
    name="JavaFXHelloWorldApp"
    mainClass="HelloWorld"/>

Example 2 Application description for modular application

<fx:application id="MinesweeperFX"
    name="MinesweeperFX"
    module="fx.minesweeper"
    mainClass="minesweeper.Minesweeper"/>

See Example 3-3 for an example of a complete ant script.

<fx:argument>

Description

An unnamed argument that is inserted in the <fx:argument> element in the deployment descriptor. Multiple arguments are added to the list of arguments in the same order as they are listed in the Ant script.

Parent Elements

<fx:application>

Parameters

None.

Parameters Accepted as Nested Elements

None.

<fx:argument> Usage Examples

Example 1 Passing Various Unnamed Arguments

<fx:application name="Sample app"
        mainClass="test.MyApplication">
    <!-- unnamed arguments -->
    <fx:argument>Something</fx:argument>
    <!-- value with spaces that are generated at build time -->
    <fx:argument>JRE version: ${java.version}</fx:argument>
    <!-- example of value using a special character -->
    <fx:argument>true &amp; false</fx:argument>
</fx:application>

<fx:association>

Description

Associates file extensions or MIME types with a self-contained application. Multiple instances of this element are supported.

Parent Element

<fx:info>

Parameters

Attribute	Description	Type	Required?
`description`	Description of the types of tiles that are associated with the application. If no description is provided, then application-name `File` is used.	String	No
`extension`	One or more file extensions to associate with the application. Separate values with a space, for example, `aaa bbb ccc`. Wild card symbols are not allowed.	String	Depends on the bundler^Foot 1
`mimetype`	MIME type of the files to associate with the application. Wild card symbols are not allowed. Only one value is allowed on Windows, multiple values separated by a space can be provided for Linux or macOS.	String	Depends on the bundler^Foot 2
`icon`	Name of the file that contains the icon for files associated with this application. For Windows the icon format must be `.ico`, for Linux the format must be `.png`, for macOS the format must be `.icns`. If no file name is provided, then the icon for the application is used.	String	No

^Footnote 1

Required on Windows. Either extension or mimetype must be provided on macOS.

^Footnote 2

Required on Linux. Either extension or mimetype must be provided on macOS.

Parameters Accepted as Nested Elements

None.

<fx:association> Usage Example

Example 1 Associate Files with a Self-Contained Application

This example associates a self-contained application on Windows with files that have the file extension .aaa or .bbb. and provides a description and icon.

<fx:info title="Association example">
  <fx:association extension="aaa bbb" description="MyApp Data Files"
      icon="MyApp.ico">
  </fx:association>
</fx:info>

<fx:bundleArgument>

Description

Specifies an argument for the bundler that is used to create self-contained applications. Each type of bundler has its own set of arguments.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required?
`arg`	Name of bundler argument	String	Yes
`value`	Value of bundler argument	String	Yes

Arguments for Self-Contained Application Bundlers

Each type of bundler (macOS, Linux, and Windows) has its own set of arguments.

General Bundler Arguments

dropinResourcesRoot

Directory in which to look for bundler-specific drop-in resources. For example, on macOS, to look in the current directory for the Info.plist file, use the following:

<fx:bundleArgument arg="dropinResourcesRoot" value="."/>

The file is then found in the current directory: package/macosx/Info.plist.

preferencesID

ID of a <fx:preferences> element to check for JVM options that the user can override.

macOS Application Bundler Arguments

icon: The path to the default icon to use for launchers and other assists. The file format is .icns.
mac.bundle-id-signing-prefix: Prefix that is applied to the signed binary when binaries that lack property list files (plists, which use the extension .plist) or existing signatures are found inside the bundles.
mac.category: Category for the application. The category must be in the list of categories found on the Apple Developer website.
mac.CFBundleIdentifier: Value stored in the info.plist file for CFBundleIdentifier. This value must be globally unique and contain only letters, numbers, dots, and dashes. Reverse DNS order is recommended, for example, com.example.application.my-application.
mac.CFBundleName: Name of the application as it appears on the Mac Menu Bar. A name of less than 16 characters is recommended. The default is the name attribute of the <fx:application> element.
mac.CFBundleVersion: Version number for the application, used internally. The value must be at least one integer and no more than three integers separated by periods (.) for example, 1.3 or 2.0.1. The value can be different than the value for the version attribute of the <fx:application> element. If the version attribute is specified with a valid value and the mac.CFBundleVersion argument is not specified, then the value for the version attribute is used. If neither value is specified, 100 is used as the version number.
mac.signing-key-developer-id-app: Name of the signing key used for Developer ID or Gatekeeper signing. If you imported a standard key from the Apple Developer Website, then that key is used by default. If no key can be identified, then the application is not signed.

macOS DMG (Disk Image) Bundler Arguments

licenseFile: Location of the End User License Agreement (EULA) to be presented or recorded by the bundler. The path is relative to the packaged application resources.
mac.CFBundleVersion: Version number for the application, used internally. The value must be at least one integer and no more than three integers separated by periods (.) for example, 1.3 or 2.0.1. The value can be different than the value for the version attribute of the <fx:application> element. If the version attribute is specified with a valid value and the mac.CFBundleVersion argument is not specified, then the value for the version attribute is used. If neither value is specified, 100 is used as the version number.
mac.dmg.simple: Flag that indicates if DMG customization steps that depend on executing AppleScript code are skipped. Set to true to skip the steps. When set to true, the disk window does not have a background image, and the icons are not moved into place. If the systemWide argument is also set to true, then a symbolic link to the root Applications folder is added to the DMG file. If the systemWide argument is set to false, then only the application is added to the DMG file, no link to the desktop is added.

macOS PKG Bundler Arguments

licenseFile: Location of the End User License Agreement (EULA) to be presented or recorded by the bundler. The path is relative to the packaged application resources.
mac.CFBundleVersion: Version number for the application, used internally. The value must be at least one integer and no more than three integers separated by periods (.) for example, 1.3 or 2.0.1. The value can be different than the value for the version attribute of the <fx:application> element. If the version attribute is specified with a valid value and the mac.CFBundleVersion argument is not specified, then the value for the version attribute is used. If neither value is specified, 100 is used as the version number.
mac.signing-key-developer-id-installer: Name of the signing key used for Developer ID or Gatekeeper signing. If you imported a standard key from the Apple Developer Website, then that key is used by default. If no key can be identified, then the application is not signed.

Mac App Store Bundler Arguments

mac.app-store-entitlements: Location of the file that contains the entitlements that the application operates under. The file must be in the format specified by Apple. The path to the file can be specified in absolute terms, or relative to your Ant file. If no entitlements are specified, then the application operates in a sandbox that is stricter than the typical applet sandbox, and access to network sockets and all files is prevented.
mac.CFBundleVersion: Version number for the application, used internally. The value must be at least one integer and no more than three integers separated by periods (.) for example, 1.3 or 2.0.1. The value can be different than the value for the version attribute of the <fx:application> element. If the version attribute is specified with a valid value and the mac.CFBundleVersion argument is not specified, then the value for the version attribute is used. If neither value is specified, 100 is used as the version number. If this version is an upgrade for an existing application, the value must be greater than the previous version number.
mac.signing-key-app: Name of the application signing key for the Mac App Store. If you imported a standard key from the Apple Developer Website, then that key is used by default. If no key can be identified, then the application is not signed.
mac.signing-key-pkg: Name of the installer signing key for the Mac App Store. If you imported a standard key from the Apple Developer Website, then that key is used by default. If no key can be identified, then the application is not signed.

Linux Bundler Arguments

icon: The path of the default icon to use for launchers and other assists. The file format is .png.
linux.bundleName: Name of the RPM or DEB package to create.

Windows EXE and MSI Bundler Arguments

icon: The path of the default icon to use for launchers and other assists. The file format is .ico.
licenseFile: Location of the End User License Agreement (EULA) to be presented or recorded by the bundler. The path is relative to the packaged application resources.
win.menuGroup: Menu group in which to install the application when the menu attribute of the <fx:preferences> element is true. This argument is ignored when menu is false.

<fx:bundleArgument> Usage Example

The following example specifies that the generated Windows Installer Package (MSI file) create a Start Menu shortcut in a menu group named Sample Applications. Note that you must specify that the bundler create an MSI file with the nativeBundles attribute of the <fx:deploy> element.

<fx:deploy outdir="." outfile="helloworld" nativeBundles="msi">
    <fx:platform basedir="${JAVA_HOME}"/>
    <fx:application refId="HelloWorldID"/>
    <fx:resources refid="appRes"/>
    <fx:info title="Hello World Example" vendor="Oracle Corporation"/>
    <fx:bundleArgument arg="win.menuGroup" value="Sample Applications"/>
</fx:deploy>

<fx:callback>

Description

Defines a JavaScript callback that can be used to customize user experience.

Parent Elements

<fx:callbacks>

Parameters

Attribute	Description	Type	Required?
`name`	Name of the event for callback.	String	Yes
`refid`*	--	Reference	No

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

<TEXT>

<fx:callback> Usage Examples

Example 1 A Callback Calling a JavaScript Function

In this example, a callback is used to create an HTML splash screen for an application embedded in a web page. When the event onGetSplash is triggered, the JavaScript function customGetSplash is executed.

<fx:callbacks>
    <fx:callback name="onGetSplash">customGetSplash</fx:callback>
</fx:callbacks>

Example 2 A Callback with JavaScript Inserted

In this example, the callback is defined with JavaScript code in the <fx:callback> element itself.

<fx:callbacks>
    <fx:callback name="onLoadHandler">
        function () {perfLog(0, "onLoad called");}
    </fx:callback>
</fx:callbacks>

Example 3 Multiple Callbacks

<fx:callbacks>
    <fx:callback name="onJavascriptReady">callAppFunction</fx:callback>
    <fx:callback name="onGetSplash">function(id) {}</fx:callback>
 </fx:callbacks>

<fx:callbacks>

Description

Collection of JavaScript callbacks to be used to customize the user experience.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required?
`refid`*	--	Reference	No

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

<fx:callback>

<fx:callbacks> Usage Examples

See the examples for <fx:callback>.

<fx:fileset>

Description

Extension of the standard Ant FileSet type, which provides the means to specify optional meta information about a selected set of files. This includes:

Type of resource (see the type attribute)
Operating system and architecture for which this resource is applicable
When this resource is needed, which helps to optimize loading order

Depending on type, the resource might not be used by the enclosing task.

A fileset of type "jar" is expected to contain a set of JAR files to be added to the classpath.

Resource of type "native" is expected to be a JAR file with a set of native libraries. In most of cases, it makes sense to set the operating system and architecture for this resource too.

Resources of type "jnlp" are expected to contain JNLP files defining external JNLP extensions.

Filesets of type "license" can contain arbitrary files, but additional restrictions can be applied when they are actually used (for example, on Mac it has to be a plain text file, and on Windows it needs to be RTF).

Filesets of type "data" can contain arbitrary files.

Parent Elements

Parameters

Attribute	Description	Type	Required?
`arch` (used only when `<fx:fileset>` is nested under `<fx:resources>`	Specifies the architecture for which these resources should be considered.	String	No Default is `any`.
`dir`	Specifies the root directory that contains the files used in the task.	String	Yes
`excludes`	Specifies files in the `dir` directory that are excluded from the task. Use an asterisk () as a wild card to match multiple files, for example, `test*`.	String	No
`includes`	Specifies files in the `dir` directory that are included for the task. Use an asterisk () as a wild card to match multiple files, for example, `/.jar`.	String	No
`os` (used only when `<fx:fileset>` is nested under `<fx:resources>`	Specifies the operating systems for which these resources should be considered.	String	No Default is `any`.
`requiredFor` (used only when `<fx:fileset>` is nested under `<fx:resources>`	Defines when resources are needed (affects loading priority). Supported values are: `preloader` - resources are needed to launch the preloader (first thing to be executed) `startup` - resources are needed to launch the application. `runtime` - resources are not critical to launch the application but may be needed later.	String	No Default is `startup`.
`type` (used only when `<fx:fileset>` is nested under `<fx:resources>`	Type of the resources in the set. Supported values are: `auto` for autodetect data `jar` `jnlp` license `native` for JAR files containing native libraries `icon`	String	No Default is to guess based on extension.

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

None (except standard Ant elements).

<fx:htmlParam>

Description

Parameter to be passed to the embedded or Web Start application from the HTML page. The value of the parameter can be calculated at runtime using JavaScript.

Parent Elements

<fx:application>

Parameters

Attribute Description Type Required?

Attribute	Description	Type	Required?
`escape`	Defines how to interpret the value for the values that are passed—as string literal (true) or JavaScript variable (false).	Boolean	No Default is true, meaning value is treated as string literal.
`name`	Name of the parameter to be passed to the embedded or Web Start application from the HTML page.	String	Yes
`value`	Value of the parameter. Could also be the name of a JavaScript variable whose value is expected to be passed as parameter. For JavaScript variables, ensure `escape` is set to false.	String	Yes

escape

Defines how to interpret the value for the values that are passed—as string literal (true) or JavaScript variable (false).

Boolean

Default is true, meaning value is treated as string literal.

name

Name of the parameter to be passed to the embedded or Web Start application from the HTML page.

String

Yes

value

Value of the parameter. Could also be the name of a JavaScript variable whose value is expected to be passed as parameter.

For JavaScript variables, ensure escape is set to false.

String

Yes

Parameters Accepted as Nested Elements

None

<fx:htmlParam> Task Usage Examples

Example 1 Various Parameters Passed from HTML Page

<fx:application name="Sample app"
        mainClass="test.MyApplication">
    <!-- Parameters passed from HTML page. Only applicable 
         for embeddeded and Web Start applications and unused when
         run in a standalone and self-contained context.  -->
    <!-- Parameter with name 'fixedParam', whose value is string 
        '(new Date()).getTime()' -->
    <htmlParam name="fixedParam"
           value="(new Date()).getTime()"/>
    <!-- Parameter with name 'dynamicParam', whose value will be 
         the timestamp of the moment when the application is added  
         to the web page (value will be assigned the result 
         of execution of JavaScript code) -->
    <htmlParam name="dynamicParam" escape="false"
            value="(new Date()).getTime()"/>
</fx:application>

<fx:icon>

Description

Passes an icon to the <fx:deploy> task, other than a splash screen image.

The icon specified in this element is used for Web Start and desktop applications.

Note that in JavaFX 2.2, only icons of type default are used for self-contained applications. For details on how to customize the icon for self-contained applications, see Customizing the Package Using Drop-In Resources.

Parent Elements

<fx:info>

Parameters

Attribute	Description	Type	Required?
`depth`	Color depth of the image in bits-per-pixel. Common values are 8, 16, and 24.	String	No
`href`	Location of image. For self-contained applications, the supported graphic formats depend on the operating system: macOS: `.icns` Linux: `.png` Windows: `.ico` Note that if you specify your own icon for a self-contained application, the values of the attributes `height`, `width`, and `depth` are not used. Ensure that the size and the color depth of your custom icons correspond to what your operating system expects. For Web Start applications, the supported graphic formats are `.gif`, `.jpg`, `.png`, and `.ico`.	String	Yes
`height`	Image height in pixels	String	No
`kind`	Icon type. Supported values are: `default` `disabled` `rollover` `selected` `shortcut` For Web Start applications, this attribute corresponds to the `kind` attribute in the `icon` element of a JNLP file. For desktop applications, if this attribute is not specified or set as `default`, then the icon specified is the icon of the launcher (`.exe` file for Windows, `.app` file for macOS), the icon in the taskbar or dock, and in some instances the icon for the installer package (such as a DMG package).	String	No Default value is `default`.
`width`	Image width in pixels	String	No

Parameters Accepted as Nested Elements

None.

<fx:icon> Usage Examples

Example 1 Use of <fx:icon>

<fx:info title="Sample application">
    <!-- icon to be used by default for anything but splash -->
    <fx:icon href="shortcut.ico" kind="shortcut"
            width="32" height="32" depth="8"/> 
</fx:info>

<fx:info>

Description

Application description for users. These details are shown in the system dialog boxes, if they need to be shown.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required?
`category`	Application category. Creates a link to an application in a specified category. Semantics of the value depends on the format of the package. For example: For a self-contained application on Linux, it is used to define the application menu category where the application is listed. On Mac: Creates key in `info.plist` <key>LSApplicationCategoryType</key> <string>unknown</string> On Windows creates a group, for instance, if you specify "My Music" it will create your app in `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\My Music`	String	No
`copyright`	Short copyright statement	String	No
`description`	A short statement describing the application.	String	No
`license`	License type (for example, GPL). As of JavaFX 2.2, this attribute is used only for Linux bundles.	String	No
`title`	Title of the application	String	Yes
`vendor`	Provider of the application	String	Yes

Parameters Accepted as Nested Elements

<fx:info> Usage Examples

Example 1 <fx:info> Parameter Used in <fx:deploy> Task

<fx:info vendor="Uncle Joe" description="Test program"/>

<fx:jvmarg>

Description

The JVM argument to be set in the JVM, where the application is executed. Can be used multiple times. Note that you do not need to additionally escape values if they contain space characters.

Parent Elements

<fx:platform>

Parameters

Attribute	Description	Type	Required?
`value`	Value of JVM argument.	String	Yes

Parameters Accepted as Nested Elements

None.

<fx:jvmarg> Usage Examples

See Example 2, "<fx:platform> Parameter to Specify JVM Options".

<fx:jvmuserarg>

Description

The user overridable JVM argument to be set in the JVM, where the application is executed. Can be used multiple times. Note that you do not need to additionally escape values if they contain space characters.

Parent Elements

<fx:platform>

Parameters

Attribute	Description	Type	Required?
`value`	Value of JVM argument.	String	Yes

Parameters Accepted as Nested Elements

None.

<fx:jvmuserarg> Usage Examples

See Example 2, "<fx:platform> Parameter to Specify JVM Options".

<fx:limit-modules>

Description

Limit the set of observable modules to those in the transitive closure of the list provided plus the main module, if any, plus any further modules specified in the <fx:add-modules> element.

Parent Elements

<fx:runtime>

Parameters

Attribute	Description	Type	Required?
`value`	Comma-separated list of modules used to limit the universe of observable modules.	String	No

Parameters Accepted as Nested Elements

None.

<fx:limit-modules> Usage Examples

Example 1 Limit observable modules tojdk.packager.services and javafx.controls

<fx:limit-modules value="jdk.packager.services,javafx.controls"/>

<fx:module-path>

Description

Path to the application modules to include in the generated runtime.

Parent Elements

<fx:runtime>

Parameters

Attribute	Description	Type	Required?
`value`	List of module locations. On Linux and macOS, use a colon (:) to separate paths. On Windows, use a semicolon (;).	String	No

Parameters Accepted as Nested Elements

None.

<fx:module-path> Usage Examples

Example 1 On Linux, locate application modules in ${java.home}/../images/jmods and ${build.dir}/modules

<fx:runtime>
   <fx:module-path value="${java.home}/../images/jmods:${build.dir}/modules"/>
</fx:runtime>

<fx:param>

Description

Parameter to be passed to the application (embedded into application package).

This tag has no impact on standalone applications, including self-contained applications.

Parent Elements

<fx:application>

Parameters

Attribute	Description	Type	Required?
`name`	Name of parameter	String	Yes
`value`	Value of parameter	String	Yes

Parameters Accepted as Nested Elements

None.

<fx:param> Task Usage Examples

Example 1 Passing Various Types of Parameters

<fx:application name="Sample app"
        mainClass="test.MyApplication">
    <!-- parameter with name 'simpleParam' and fixed string value-->
    <param name="simpleParam" value="something"/>
    <!-- parameter with name 'complexParam' with value generated 
         at build time -->
    <param name="complexParam" value="Compiled by ${java.version}"/>
    <!-- parameter with name 'novalueParam' and no value -->
    <param name="novalueParam"/>
</fx:application>

<fx:permissions>

Description

Definition of security permissions needed by application. By default, the application runs in the sandbox. Requesting elevated permissions requires signing the application JAR files.

This option has no impact on standalone applications, including self-contained applications.

Parent Elements

Parameters

Attribute Description Type Required?

Attribute	Description	Type	Required?
`elevated`	If set to false, the application runs in the sandbox.	Boolean	No Default is false.

elevated

If set to false, the application runs in the sandbox.

Boolean

Default is false.

Parameters Accepted as Nested Elements

None.

<fx:permissions> Usage Examples

Example 1 Run application with elevated permissions

<fx:permissions elevated="true"/>

<fx:platform>

Description

Defines application platform requirements.

Parent Elements

Parameters

Attribute Description Type Required?

refid*

Reference

j2se

Minimum version of JRE required by the application.

String

Default is any JRE supporting JavaFX.

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

<fx:platform> Usage Examples

Example 1 <fx:platform> Parameter to Specify Version

In this example, the application needs JRE version 9.0 or later.

<fx:platform j2se="9.0"/>

Example 2 <fx:platform> Parameter to Specify JVM Options

In this example, the application needs JRE version 9.0 or later and needs to run in a JVM launched with "-Xmx400 -verbose:jni -Dpurpose="sample value".

<fx:platform j2se="9.0">
    <fx:jvmarg value="-Xmx400m"/>
    <fx:jvmarg value="-verbose:jni"/>
    <property name="purpose" value="sample value"/>
</fx:platform>

Example 3 <fx:platform> Parameter to Specify User Overridable JVM Options

In this example, -Xmx768m is passed as a default value for heap size. The user can override this value in a user configuration file.

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

<fx:preferences>

Description

Deployment preferences for the application. Preferences can be expressed but may not necessarily be satisfied, for example in the following cases:

The packager may ignore a preference if it is not supported for a particular execution mode.
JRE may ignore it if it is not supported.
The user may reject a request, for example if he is prompted whether a desktop shortcut can be created.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required?
`install`	Install `true` means that the application is installed for the system and `false` means the application is installed for the current user only. For self-contained applications, `true` indicates a developer preference that the application package should perform a system-wide installation. If `false,` then a package is generated for per-user installation. This value is ignored if the packager does not support different types of install packages for the requested package format.	Boolean	No For Web Start and embedded applications, default is `false`. For self-contained applications, default value is different for various package formats.
`installdirChooser`	If `true`, then a dialog is shown for the user to choose the directory in which the application is installed. If `false`, then the `install` attribute is used to determine where the application is installed.	Boolean	No Default is `false`.
`menu`	If `true`, then the application requests to add an entry to the system application menu.	Boolean	No Default is `false`.
`refid`*	--	Reference	No
`shortcut`	If `true`, then application requests a desktop shortcut to be created.	Boolean	No Default is `false`.

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

None.

<fx:preferences> Usage Examples

Example 1 <fx:preferences> Parameter to Add a Desktop Shortcut

This example shows a request to create a desktop shortcut.

<fx:preferences id="p1" shortcut="true"/>

Example 2 <fx:preferences> Parameter to Mark as Installed

This example does the following:

It requests creation of a web deployment descriptor that will add the application to the Applications Menu and mark it as installed (in other words, the application will be listed in Add/Remove programs.)
If self-contained bundles are created, then they will be installed system-wide and will create an application entry in the Applications menu.

<fx:preferences shortcut="false" install="true" menu="true"/>

Example 3 Using a refid to the <fx:preferences> Parameter

This example uses a reference to the <fx:preferences> parameter in Example 1, "<fx:preferences> Parameter to Add a Desktop Shortcut" to create the shortcut.

<fx:resource refid="p1"/>

<fx:property>

Description

Optional element and can be used multiple times. Java property to be set in the JVM where the application is executed.

Parent Elements

<fx:platform>

Parameters

Attribute	Description	Type	Required?
`name`	Name of property to be set.	String	Yes
`value`	Value of property to be set.	String	Yes

Parameters Accepted as Nested Elements

None.

<fx:resources>

Description

The collection of resources used by the application. Defined as a set of JavaFX FileSet filters. Could be reused using id or refid.

Parent Elements

Parameters

Attribute	Description	Type	Required?
`id`	ID that can be referred from another element with a refid attribute.	String	No
`refid`*	--	Reference	No

* If refid is used, then none of the other parameters can be specified.

Parameters Accepted as Nested Elements

<fx:fileset>

<fx:resources> Usage Examples

Example 1 <fx:resources> Parameters Used with id and refid Attributes

In this example, both <fx:resources> elements define the collection, consisting of s.jar in the dist directory. The first <fx:resources> element uses an id attribute, and the second <fx:resources> element refers to the first with the refid attribute.

<fx:resources id="aaa">
    <fx:fileset dir="dist" includes="s.jar"/>
</fx:resources>
<fx:resources refid="aaa"/>

Example 2 Using <fx:resources> for Extension Descriptors

If you mix signed and unsigned JAR files, use an additional <fx:deploy> Ant task to generate an extension descriptor for each JAR file, and refer to the extension descriptors by treating them as resources in the main file, as shown in this example.

<!-- Prepare extension -->
<fx:deploy extension="true"
        outdir="dist" outfile="other">
    ...
<fx:deploy>
 
<!-- Use it in the main descriptor -->
<fx:deploy outdir="web-dist" ...>
    ...
    <fx:resources>
        <fx:fileset dir="dist" includes="other.jnlp"/>
            ...
    </fx:resources>
<fx:deploy>

Additional examples are available in Self-Contained Application Packaging.

<fx:runtime>

Description

Runtime generated for your self-contained application. The jlink tool is used to generate a runtime that contains only the packages that the application needs to run, and optionally, command-line tools such as java.exe.

The Java Packager for JDK 9 generates a JDK 9 runtime image. To package a JDK 8 or JDK 7 JRE with your application, use the JDK 8 Java Packager.

Parent Elements

<fx:deploy>

Parameters

Attribute Description Type Required?

Attribute	Description	Type	Required?
`strip-native-commands`	If set to `true`, command-line tools such as `java.exe` are removed from the generated runtime. If set to `false`, command-line tools are included in the generated runtime.	Boolean	No Default is true.

strip-native-commands

If set to true, command-line tools such as java.exe are removed from the generated runtime. If set to false, command-line tools are included in the generated runtime.

Boolean

Default is true.

Parameters Accepted as Nested Elements

<fx:runtime> Usage Examples

Example 1 Generate a runtime that contains command line tools

<fx:runtime strip-native-commands="false"/>

Example 2 Include modules from jdk.packager.services and javafx.controls in the runtime

<fx:runtime>
  <fx:add-modules value="jdk.packager.services,javafx.controls"/>
</fx:runtime>

Example 3 Include modules from jdk.packager.services and provide the ___location of application modules

<fx:runtime>
  <fx:add-modules value="jdk.packager.services"/>
  <fx:module-path value="${java.home}/../images/jmods"/>
  <fx:module-path value="${build.dir}/modules"/>
</fx:runtime>

<fx:secondaryLauncher>

Description

Identifies a secondary entry point for a self-contained application and the main module for a modular application. This parameter is ignored for standalone applications, applications embedded in a web page, or applications launched from a browser.

This parameter is valid only for Windows and Linux applications.

Parent Elements

<fx:deploy>

Parameters

Attribute	Description	Type	Required
`appDescription`	Brief description of the application.	String	No
`icon`	Path to the icon file for the application.	String	No
`mainClass`	Qualified name of the main application class.	String	No
`menu`	Flag that indicates if the application is added to the Start menu. Either the `menu` attribute or `shortcut` attribute must be set to `true`. If both attributes are set to `false`, then the application is added to the Start menu.	Boolean	No Default is `true`.
`module`	Main module of a modular application. This is used as the default root module when constructing the application's initial module graph.	String	Yes, if bundling a modular application. Invalid if the application is not modular
`name`	Name of the launcher that is used to start the application.	String	Yes
`shortcut`	Flag that indicates if a shortcut to the application is added to the desktop. Either the `menu` attribute or `shortcut` attribute must be set to `true`. If both attributes are set to `false`, then the application is added to the Start menu.	Boolean	No Default is `false`.
`title`	Title of the application.	String	No
`vendor`	Name of the vendor that provided the application.	String	No
`version`	Version of the application.	String	No

Parameters Accepted as Nested Elements

<fx:argument>
<fx:bundleArgument>, only the icon argument is valid when used with <fx:secondaryLauncher>
<fx:jvmarg>
<fx:jvmuserarg>
<fx:property>

<fx:secondaryLauncher> Usage Example

Example 1 Deploy task for non-modular application with secondary launchers

See Example 3, "<fx:deploy> Task with Secondary Launchers".

Example 2 Secondary launcher for modular application

<fx:secondaryLauncher name="HelloWorldModular"
    module="hello.world"
    mainClass="com.sample.app.HelloWorld">
</fx:secondaryLauncher>

<fx:splash>

Description

Passes the ___location of the image to be used as a splash screen. Currently custom splash images can only be passed to Web Start applications, and use of this parameter has no impact on standalone applications or applications embedded into web pages.

Parent Elements

<fx:info>

Parameters

Attribute Description Type Required?

Attribute	Description	Type	Required?
`href`	Location of image. Supported graphic formats are JPEG, GIF, and PNG.	String	Yes
`mode`	Deployment mode. Supported values are: `any` (but currently only functional in Web Start mode) `webstart`	String	No Default value is `any`.

href

Location of image. Supported graphic formats are JPEG, GIF, and PNG.

String

Yes

mode

Deployment mode. Supported values are:

any (but currently only functional in Web Start mode)
webstart

String

Default value is any.

Parameters Accepted as Nested Elements

None.

<fx:splash> Usage Examples

Example 1 Use of <fx:splash>

In the following example, splash images of various types are passed.

<fx:info title="Sample application">
    <fx:splash href="http://my.site/custom.gif"/> 
</fx:info>

<fx:template>

Description

Template to preprocess. A template is an HTML file that contains markers to be replaced with the JavaScript or HTML snippets that are required for web deployment. Using templates enables you to deploy your application directly into your own web pages. This simplifies the development process, especially when the application is tightly integrated with the page, for example when the web page uses JavaScript to communicate to the application.

Template markers have one of the following forms:

#XXX#
#XXX(id)#

id is the identifier of an application and XXX is one of following:

DT.SCRIPT.___URL

Location of dtjava.js in the Deployment Toolkit. By default, the ___location is

https://java.com/js/dtjava.js.
DT.SCRIPT.CODE

Script element to include dtjava.js of the Deployment Toolkit.
DT.EMBED.CODE.DYNAMIC

Code to embed the application into a given placeholder. It is expected that the code will be wrapped in the function() method.
DT.EMBED.CODE.ONLOAD

All the code needed to embed the application into a web page using the onload hook (except inclusion of dtjava.js).
DT.LAUNCH.CODE

Code needed to launch the application. It is expected that the code will be wrapped in the function() method.

A page with different applications can be processed multiple times, one per application. To avoid confusion, markers must use application IDs with an alphanumeric string and no spaces.

If the input and output files are the same then the template is processed in place.

Parent Elements

<fx:deploy>

Parameters

Attribute Description Type Required?

Attribute	Description	Type	Required?
`file`	Input template file.	File	Yes
`tofile`	Output file (after preprocessing).	File	No Default is the same as the input file.

file

Input template file.

File

Yes

tofile

Output file (after preprocessing).

File

Default is the same as the input file.

Parameters Accepted as Nested Elements

None

<fx:template> Usage Examples

Example 1 <fx:template> Parameter Used in <fx:deploy> Task

This example shows a <fx:template> parameter in which both input and output files are specified.

<fx:template file="App_template.html" tofile="App.html"/>

Example 2 <fx:template> Parameter in Context

<fx:deploy placeholderId="ZZZ"
        width="600" height="400"
        outdir="dist-web" outfile="App1">
    <fx:application id="myApp" name="Demo"
            mainClass="fish.FishApplication"/>
    <fx:template file="src/templates/EmbedApp_template.html"
            tofile="dist-web/EmbedApp.html"/>
    <fx:resources>
        <fx:fileset requiredFor="startup" dir="dist" includes="*.jar"/>
    </fx:resources>
</fx:deploy>