Deploying JavaFX Applications

Previous
Next

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:application>

Description

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

Parent Elements

Parameters

Table 12-5 Attributes of the <fx:application> Element

Attribute Description Type Required?

name

--

String

--

fallbackClass

AWT-based applet to be used if application fails to launch due to missing FX runtime and installation of JavaFX is not possible.

String

No

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

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.


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

Parameters Accepted as Nested Elements

<fx:application> Usage Examples

See Example 12-2.


<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

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:callback>

Description

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

Parent Elements

Parameters

Table 12-6 Attributes of the <fx:callback> Element

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

Parameters

Table 12-7 Attributes of the <fx:callbacks> Element

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: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 on 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. See Section 5.7.2, "Application Resources" for details.

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

Table 12-8 Attributes of the <fx:fileset> Element

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.

excludes

--

String

--

includes

--

String

--

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

Parameters

Table 12-9 Attributes of the <fx:htmlParam> Element

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


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 
         to embedded [nd 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.

Note that in JavaFX 2.2, <fx:icon> is not used for self-contained applications. For details on how to customize icon for self-contained application, see Section 6.3.3, "Customization Using Drop-In Resources."

Parent Elements

Parameters

Table 12-10 Attributes of the <fx:info> Element

Attribute Description Type Required?

depth

Image depth

String

No

href

Location of image

String

Yes

height

Image height

String

No

kind

Icon type. Supported values are:

  • default

  • disabled

  • rollover

  • selected

  • shortcut

String

No

Default value is default.

width

Image width

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

Parameters

Table 12-11 Attributes of the <fx:info> Element

Attribute Description Type Required?

category

Application 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.

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 aditionally escape values if they contain space characters.

Parent Elements

Parameters

Table 12-12 Attributes of the <fx:jvmarg> Element

Attribute Description Type Required?

value

Value of JVM argument.

String

Yes


Parameters Accepted as Nested Elements

None.

<fx:jvmarg> Usage Examples

See <fx:platform> Parameter to Specify JVM Options.


<fx:param>

Description

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

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

Parent Elements

Parameters

Table 12-13 Attributes of the <fx:param> Element

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

Table 12-14 Attributes of the <fx:permissions> Element

Attribute Description Type Required?

cachecertificates

If set to true, then the certificate used to sign the JAR files are cached in the deployment descriptor. Caching enables the user to accept elevated permissions earlier in the startup process, which improves startup time.

This setting has no effect if the application is run in the sandbox.

Boolean

No

Default is false.

elevated

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

Boolean

No

Default is false.


Parameters Accepted as Nested Elements

None.

<fx:permissions> Usage Examples

Example 1   Embed Signing Certificate into Deployment Descriptor

See Section 5.9.3, "Embed Signing Certificate into Deployment Descriptor."

<fx:permissions elevated="true" cacheCertificates="true"/>

<fx:platform>

Description

Defines application platform requirements.

Parent Elements

Parameters

Table 12-15 Attributes of the <fx:platform> Element

Attribute Description Type Required?

refid*

--

Reference

No

javafx

Minimum version of JavaFX required by the application.

String

No

Default value matches the release of the JavaFX SDK; for example, if you use the JavaFX 2.2 SDK, the default value is '2.2'.

j2se

Minimum version of JRE required by the application.

String

No

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 JavaFX Runtime version 2.1 or later and JRE version 7.0 or later.

<fx:platform javafx="2.1+" j2se="7.0"/>
Example 2   <fx:platform> Parameter to Specify JVM Options

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

<fx:platform javafx="2.1+">
    <fx:jvmarg value="-Xmx400m"/>
    <fx:jvmarg value="-verbose:jni"/>
    <property name="purpose" value="sample value"/>
</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.

  • Java Runtime 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

Parameters

Table 12-16 Attributes of the <fx:preferences> Element

Attribute Description Type Required?

install

If true, then application requests to be installed.

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 embeddedapplications, default is false.

For self-contained applications, default value is different for various package formats.

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 <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

Parameters

Table 12-17 Attributes of the <fx:property> Element

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

Table 12-18 Attributes of the <fx:resources> Element

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:resources> Usage Examples

See also examples in Chapter 5, "Packaging Basics" and Chapter 6, "Self-Contained Application Packaging."

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>

<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

Parameters

Table 12-19 Attributes of the <fx:splash> Element

Attribute Description Type Required?

href

Location of image

String

Yes

mode

Deployment mode. Supported values are:

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

  • webstart

String

No

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

    http://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

Parameters

Table 12-20 Attributes of the <fx:template> Element

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.


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>
Previous
Next