JavaFX applications can be deployed inside a web page and in the context of a browser, as long as the browser supports Java. When a web page is displayed, the browser starts the Java Runtime, which downloads the JavaFX application and displays it as part of the web page. This article shows how to package JavaFX applications and deploy them in web pages.

Java and JavaFX applications must first be packaged into the proper files before they can be deployed. A typical package contains the following files:

• A JAR file, which is a compressed file containing the application code
• A JNLP file, which contains much of the deployment configuration
• An HTML file, which contains a script that can be copied into any web page to call the application

In this article, the term deployment is used to mean placing the web page and packaged files into the appropriate location on a web server. As a result, the application runs when the web page is accessed in a browser.

This article contains procedures for packaging, configuring, and deploying a basic application. It also includes more advanced options and a troubleshooting section.

1 Deploying a JavaFX Application for the First Time?

Use this quick-start procedure if you have developed a simple JavaFX application and want to deploy it to a web server:

1. Package the application using either the NetBeans IDE or the JavaFX Packager utility, which is part of the JavaFX SDK. See Section 2, Packaging the Application. Packaging produces the files that you need to configure and deploy. See Section 3, Identifying the Files Required for Browser Deployment.
   
   
2. In the appropriate JNLP file, which was generated when you packaged the application, remove the attributes from the JNLP tag. See Section 4, Configuring the JNLP File.
   
   
3. Copy the application script from the HTML file that was generated when you packaged the application, and paste it into your web page wherever you want the application to appear. See Section 5, Moving the Application Scripts to Your Web Page. Your files will share the same directory, so you do not need to configure directory location.
   
   
4. Move your web page, the JAR file, and the JNLP file to your web server. Put them all in the same directory, at least at first. See Section 6, Deploying the Application.
   
   
5. Test the deployed application in your browser. See Section 9, Testing the Deployed Application. Any problems? See Section 10, Troubleshooting.

After you have the basic deployment techniques accomplished, you can try some of the other options described in this article:

• Section 8.1, Signing the Application - Use if your applications require a digital signature.
  
  
• Section 8.2, Compressing the JAR File - Improve startup time by compressing large applications.
  
  
• Section 8.3, Improving Startup Time by Avoiding Application Update Checks - Improve the startup time of most applications by configuring the update check to be performed in the background.
  
  
• Section 8.4, Customizing the Loading Experience - Customize the phases of the application startup to improve user experience.
  
  
• Section 8.5, Changing the Location of Deployment Files - Change the standard configuration if you want to put your deployment files in a different directory from your web page.
  
  
• Section 8.6, Making Browser Applications Draggable - Drag applications out of the browser window onto the desktop on Windows platforms by using versions of Java 6 Update 10 and later versions.

2 Packaging the Application

Use either of the following procedures to package your application by using the NetBeans IDE or the JavaFX Packager utility from the command line. Either procedure packages the application into a JAR file and creates the supporting files needed for deployment.

Prerequisite: The procedures in Section 2.1 and Section 2.2 assume that the application is ready to compile without errors.

2.1 Packaging Applications Using the NetBeans IDE

The NetBeans IDE provides a user interface to specify packaging preferences as part of the project's properties and to package the application. The following procedure assumes that you have created a NetBeans IDE project for your application, and that the project is open and displayed in the Projects window:

1. In the NetBeans Projects window, right-click the project's root node and select Properties, or select File, then Project Properties.
   
   
2. If you plan to test how your application runs in the browser from within the NetBeans IDE, in the Categories pane, select the Run category, then for the Application Execution Model, select Run in Browser. This step does not affect how applications are packaged and is most useful for testing your application during development.
   
   
3. In the Categories pane, select the Application category.
   
   
4. In the Vendor field, enter the name of the institution or individual that owns the deployed application. The vendor name is displayed in the list of applications cached in the Java Control Panel and appears in the security warning that is displayed when the application is digitally signed.
   
   
5. In the Applet Specific Properties section, set the desired width and height to use for your application. Use the width or height of the Scene object instance in your application. If the scene size is dependent on a variable in your application, set the width and height to the maximum size that you want to allow on the browser page. These values appear as parameters in the application script in the web page, which is generated when the application is packaged.
   
   For information about additional packaging options on this screen, see the following sections of this article:
   
   
   • Section 8.1, Signing the Application
   • Section 8.2, Compressing the JAR File
   • Section 8.3, Improving Startup Time by Avoiding Application Update Checks
     
     
   The Additional JavaFX Packager Options field enables you to add options from the javafxpackager command that are not supported by the NetBeans IDE user interface. For more information about these options, see Section 2.2, Packaging Browser Applications from the Command Line.
   
   
6. Click OK to close the Project Properties dialog box.
   
   
7. In the Projects window, right-click the project's root node and select Clean and Build Project. This action removes the packaged files and directories that were generated from any previous builds and then builds the application package.
   
   
8. To test the application within the NetBeans IDE, right-click the project's root node and select Run Project. To see what files were generated, go to the dist subfolder of your project directory and skip to Section 3, Identifying the Files Required for Browser Deployment.

2.2 Packaging Browser Applications from the Command Line

The JavaFX Packager utility, included in the JavaFX SDK, generates the files required for deployment. In addition to values that are generated automatically, the tool lets you set some configuration values by adding command-line options. To get the JavaFX Packager utility, download the JavaFX SDK as a standalone platform or access the JavaFX SDK installation within the NetBeans IDE in the following locations:

• Windows: Navigate to C:\Program Files\NetBeans version\javafx\javafx-sdk. The javafxpackager command is in the bin folder, and the JavaFX Packager documentation is in the docs folder.
  
  
• Mac: In the Applications/NetBeans folder, control-click the NetBeans IDE application icon and select Show Package Contents, then go to the Contents/Resources/NetBeans/javafx/javafx-sdk. The javafxpackager command is in the bin folder, and the JavaFX Packager documentation is in the docs folder.

The following example shows a javafxpackager command for a simple application:

javafxpackager -src src -appName MyApp -appClass myapp.Main
-appWidth 527 -appHeight 602 -appVendor "Example Corporation"

The following list describes the arguments used in the previous command:

• -src (required)
  The root directory of the source tree in the application.

  In the previous example, the application files have a file structure similar to the following:

  MyApp/
      src/
          myapppackagename/
              Main.fx

  
  
  
• -appName
  The name of the application, which becomes the name of the files that are created. The default value is the name of the entry class of the application. In this example, not specifying the -appName option results in the file names Main.jar, Main.jnlp, and so on.
  
  
• -appClass (required)
  The path to the main class for the application. For example, if the package name is myapp, and the Main.fx file in that package contains the main class, then the -appClass value would be myapp.Main.
  
  
• -appWidth
  The width of the application. The default width is 200 pixels. This option is used to create the setting for the width attribute in the script that is embedded in the HTML file that is created when the application is packaged.
  
  
• -appHeight
  The height of the application. The default height is 200 pixels. This option is used to create the setting for the height attribute in the script that is embedded in the web page.
  
  
• -appVendor
  The vendor name is displayed in the list of applications cached in the Java Control Panel and in the security warning that is displayed if the application is digitally signed. If the vendor name is more than one word, put the value inside double quotation marks. If the -appVendor option is unspecified, the default value is the user.name Java system property.

The default destination is ./dist, which means the /dist folder is packaged as a child of the MyApp directory in the previous example. To set a custom destination directory, use the command option -destination or -d.

The javafxpackager command has a number of additional options. You can view the documentation for these commands in either of two ways:

• Use the -help option with these commands online, as follows:
  
  javafxpackager -help
  
  
• See the javafxpackager.html documentation in the /docs directory of the JavaFX SDK.

To test the application immediately after packaging, locate the packaged files in the destination directory and open the <app_name>.html file in a browser. If the application does not run, see Section 9.2, Application Runs in the NetBeans IDE but Not Outside It.

Tip: To recompile only the JAR file without creating other supporting files, use the javafxc command, which is also included with the JavaFX SDK. Use this option only when you have modified the application under the same version of the JavaFX Runtime and merely want to replace the JAR file without changing the deployment configuration. Use the -help option to get a list of command line options.

3 Identifying the Files Required for Browser Deployment

When the application is packaged by using either the NetBeans IDE or the javafxpackager command, files are created for all deployment types. The subset of files in Table 1 is required for deployment to the browser.

If you compress the application, an additional file named <app_name>.jar.pack.gz is required. See Section 8.2, Compressing the JAR File. The <app_name>.jnlp file is used for Web Start deployment and can be ignored or deleted when running applications in the browser.

4 Configuring the JNLP File

You must edit the <app_name>_browser.jnlp. file to specify the location of the deployed JAR file or to remove the location information entirely. You can also edit the JNLP file to change options you set during packaging, or to change default values.

4.1 Mandatory Manual Configuration

For the application to run when you move the files from their test location to a web server, you must either manually remove the attributes from the <jnlp> tag or edit the codebase attribute to specify the location of the deployed JAR file. Removing the attributes is the recommended option, because they are not required for applications that run in the browser. Removing the attributes has the advantage of eliminating the need to edit the file again if you move the application to a new location.

Use the following procedure to remove the attributes from the <jnlp> tag:

1. Open <app_name>_browser.jnlp in a text editor.
   
   
2. In the <jnlp> tag, remove the spec, codebase, and href attributes. After the attributes are removed, the second line should consist of the following tag:
   <jnlp>
   
   
3. Save the file.
   
   

4.2 Optional Manual Configuration

Although most of the configuration can be generated during the packaging process, you can edit the settings in the JNLP file. The following example shows a typical JNLP file for a simple application called MyApp. Line numbers are added to assist with the description.

1   <?xml version="1.0" encoding="UTF-8"?>
2   <jnlp>
3       <information>
4           <title>MyApp</title>
5           <vendor>Oracle Corporation</vendor>
6           <homepage href=""/>
7           <description>MyApp</description>
8           <offline-allowed/>
9       </information>
10      <resources>
11          <j2se version="1.5+"/>
12          <extension name="JavaFX Runtime" href="http://dl.javafx.com/1.3/javafx-rt.jnlp"/>
13          <jar href="MyApp.jar" main="true"/>
14      </resources>
15      <applet-desc name="MyApp" main-class="com.sun.javafx.runtime.adapter.Applet" width="90" height="150">
16          <param name="MainJavaFXScript" value="myapp.Main"/>
17      </applet-desc>
18      <update check="background"/>
19  </jnlp>

Table 2 describes the content tags in the example JNLP file.

For more complete information about JNLP syntax, see the Java document JNLP File Syntax.

5 Moving the Application Scripts to Your Web Page

The HTML file that is generated during packaging contains two <script> elements, which contain additional configuration information. If you set the options correctly for packaging and keep the JAR and JNLP files in the same directory as your web page, you do not need to make any configuration changes to the scripts. To embed the application in your web page, copy the two <script> tags and paste them into your web page where you want your application displayed.

Tip: Test your application by viewing the simple HTML file in a browser before embedding the scripts in your larger web page.

The remainder of this section provides more details about the contents of the two scripts. The following example shows the two scripts as they are typically packaged in the HTML file.

<script src="http://dl.javafx.com/1.3/dtfx.js"></script>
<script>
    javafx(
        {
            archive: "MyApp.jar",
            width: 90,
            height: 150,
            code: "myapp.Main",
            name: "MyApp"
        }
    );
</script>

The URL in the first script element opens dtfx.js, a script on the dl.javafx.com web site. The dtfx.js script generates an <applet> tag and the configuration required to run the application. It also autodetects the user's copy of Java and the JavaFX Runtime, installing an update if necessary.

Note: The version of dtfx.js denoted in the URL must match the version of JavaFX that was used to write the application.

The second script element is generated by default with a javafx line, which identifies the application as being of type JavaFX, and it contains the following component attributes:

• The archive attribute shows the location of the JAR file relative to the web page. The information in the archive attribute overrides the JNLP configuration in the href attribute of the <jar> element.
  
  Note:
  
  
  • The archive attribute shows the location of the JAR file relative to the codebase, which is specified in the codebase attribute of the <jnlp> tag in the JNLP file. If the codebase is not specified in the JNLP file, as is recommended for applications that run in the browser, then the codebase is automatically calculated as being relative to the web page.
    
    
  • As long as the JNLP file is in the same directory as the JAR file, no reference to the JNLP file is required.
    
    
• The code attribute specifies the location of the main class within the package. In this case, the package name is myapp and the main class is Main.fx. The information in the code attribute overlaps the JNLP file configuration, expressed in the value attribute of the <applet-desc> element.
  
  Note: The archive and code attributes stop overriding information in the JNLP file when another attribute called jnlp_href is used in the web page script. For more information about the jnlp_href attribute and when it is used, see Section 8.5, Changing the Location of Deployment Files.
  
  
• The width and height attributes specify the size of the application in pixels as it appears in the web page. These values override the values in the <applet-desc> tag of the JNLP file.
  
  
• The name attribute contains the name of the application. During packaging, the value is generated from the -appName option in the javafxpackager command, or from the Name field on the Application tab in the NetBeans IDE project properties. The information in the name attribute overlaps the JNLP configuration, expressed in the name attribute of the <applet-desc> element.

6 Deploying the Application

Use the following procedure to place the deployment files on a server:

1. Copy your web with the embedded <script> tags to a web server.
   
   
2. Copy the JAR and JNLP files to the web server, in the directory specified in the archive attribute of the <script> tag in the web page. Ensure the directory has unrestricted access. Unless you change the default configuration, the JNLP and JAR files should be placed in the same directory as the web page.

7 Testing the Deployed Application

To test the application, open the deployed web page in a browser window. If the application does not run, go to Section 9, Troubleshooting.

8 Other Browser Deployment Options

The options discussed in this section are not required for deployment of a simple application to the browser but are frequently used for more complex applications. For more in-depth descriptions of browser deployment options, see the related links at the end of this article.

8.1 Signing the Application

Applications run in a Java sandbox, which prevents users' machines from accessing the system. However, applications must be signed when they require local operations that must go outside the sandbox, and in some other circumstances, such as when an application's JAR file resides on a different server from the web page that calls it.

Tip: Do not sign your application unless the application requires it.

If you need to sign your application, you can self-sign it for testing or demonstration purposes, but in a production environment you should use a third-party certificate so users can trust the signer. In either case, when an application is signed you must pay attention to the expiration date and sign the application again when the self-signature or certificate is expired.

To self-sign an application in the NetBeans IDE:

1. In the Project Properties dialog box, select Application in the left pane, then select the Self Signed Jar checkbox.
   
   
2. Select the Clean and Build option when you package.

To self-sign an application by using the javafxpackager command:

1. Add the -sign option to the command line, for example:
   javafxpackager -src src -appName MyApp -appClass myapp.Main
-appWidth 527 -appHeight 602 -appVendor "Example Corporation"-sign
   
   
2. If there is already a destination directory, delete it before repackaging.

The self-signing option results in the following changes to packaged files:

• The JAR file is signed.
  
  
• The following elements are nested under the <jnlp> tag in the JNLP file:
  
  <security>
<all-permissions/>
</security>

Signing an application with a certificate requires the use of the JavaFX Packager or JAR Signer tool. If you use the javafxpackager command, you can produce a signed JAR file and the appropriate settings in the JNLP file during the packaging process. The javafxpackager command uses the following options for signing with a certificate:

• -sign
  Signs the JAR file.
  
  
• -keystore
  Specifies the URL of the keystore to be used. The keystore is by default stored in a file named .keystore in the user's home directory, as determined by the user.home system property.
  
  
• -keystorePassword
  Specifies the password. This is required when signing with a specific keystore.
  
  
• -keyalias <alias>
  Specifies a unique alias. Because all keystore entities are accessed by using unique aliases, the -keyalias option is mandatory when signing with a specific keystore.
  
  
• -keyaliasPassword
  Specifies the alias password. When not specified, the keystore password is used.

The JAR Signer tool can be applied to an unsigned JAR file.The jarsigner command has more options than the javafxpackager command, but you must create the <security> element in the JNLP file manually.

For more information, see the following resources:

• Create a Secure JavaFX Application
  This article discusses security issues related to JavaFX.
  
  
• Signing JAR Files
  This Java Tutorial topic provides more information about the keystore, the keystore password, and the alias, which are required when attaching a certificate to a signed application.
  
  
• jarsigner - JAR Signing and Verification Tool
  Documentation about how to use the jarsigner command to sign JAR files.

8.2 Compressing the JAR File

When the application must be downloaded on a user's system, sometimes you can decrease application startup time by compressing the application JAR file. Applications are cached on users' systems, so downloading is necessary only the first time the application is run or after it has been updated.

Compression works particularly well for large applications that do not contain a large percentage of assets in binary format. The reduced time to download the application is offset by the extra time taken to uncompress the application after it is downloaded. There should be a significant difference in size between the compressed and uncompressed application to realize a net gain in startup time.

Tip: Try compressing your application and compare the difference in size of the two JAR files produced to determine if compression would be worthwhile.

To compress the JAR file, make the following changes in the packaging process:

1. In the NetBeans IDE, in the Project Properties dialog box, select Application in the left pane, then select the Pack200 Compression checkbox.
   
   
2. For the javafxpackager command, add the -pack200 option.
   
   
3. If there is already a destination directory, delete it before repackaging. If you are repackaging using the NetBeans IDE, instead of manually deleting the destination directory, you can select the Clean and Build option when you package.

The compression option results in the following changes to packaged files:

• Both uncompressed and compressed JAR files are created. The compressed JAR file has the file name <app_name>.jar.pack.gz. Deploy both files to the same location on the deployment server, because the uncompressed application is used if the compressed application cannot be used for any reason.
  
  
• The following two elements are added to the <resources> tag in the JNLP file:
  
  <property name="jnlp.packEnabled" value="true"/>
<property name="jnlp.versionEnabled" value="true"/>

8.3 Improving Startup Time by Avoiding Application Update Checks

Java Runtime will automatically check for the availability of updates for both JavaFX Runtime and your application and update them if necessary. By default, this check is performed before the application starts, and this could noticeably slow application startup. Automatic updates are convenient for application development, because you can be sure you are running latest version. However, after the application is deployed for public access, it does not change often, and mandatory updates before the application starts are usually not required.

Choose either one of two ways to avoid application update checks:

• Configure the JNLP to perform the update check in the background.
  
  
• If there is a chance that users will run an application in a browser on versions of Java prior to Java 6 Update 10, configure caching in the web page script that calls the application.

8.3.1 Configuring Background Checking in the JNLP File

You can configure the update check to be performed in the background, which means that if there is a cached version, the application will be started using that version while the update check is performed in the background. The updated version will be used the next time the application is started. If there is no cached version, as would occur the first time the application is run or when the Java cache is cleared, the update check occurs before the application runs.

Tip: Set the update check to Background unless your application always needs to be up-to-date and will fail otherwise (for example, if the application must correspond to a server-side application).

To set the update check to background in the NetBeans IDE:

1. In the Project Properties dialog box, select Application in the left pane.
   
   
2. In the Update Model field, select Background.
   
   

To set the update check to background when using the javafxpackager command, use the -updatecheck option, for example:

javafxpackager -src src -appName MyApp -appClass myapp.Main
-appWidth 527 -appHeight 602 -updatecheck background

To reconfigure the update setting without repackaging the application:

1. Open the <application_name>_browser.jnlp file in a text editor.
   
   
2. Search for the <update> element, nested under the <jnlp> element, and change the value of the check attribute to "background", for example:

   <?xml version="1.0" encoding="UTF-8"?> 
   <jnlp>
      ...
      <update check="background"/>
   </jnlp>
   

8.3.2 Configuring Application Caching for Earlier Versions of Java

For deployment of applications in the browser, it is good to pass cache_archive and cache_version as additional arguments to the javafx() function in the web page script to avoid update checks for users with versions of Java prior to Java 6 Update 10:

<script src="http://dl.javafx.com/1.2/dtfx.js"></script>
<script>
    javafx(
        {
            archive: "MyApp1.jar,MyApp2.jar",
            width: 480,
            height: 120,
            code: "myapp.Main",
            name: "MyApp"
        },
        {
            cache_archive: "MyApp1.jar,MyApp2.jar",
            cache_version: "1.0,2.0"
        }
    );
</script>

The cache_archive argument should have the same value as the archive argument. The cache_version argument is a comma-separated list of one version number for each of the JAR files listed in the cache_archive argument. In the previous example, there are two JAR files listed in the cache_archive argument and therefore two version numbers. The version numbers are arbitrary. One version number is assigned to each cached JAR file. Once the JAR file is loaded, there are no update checks , and the cached version is used until the version number is changed. When you update a JAR file, you must manually change its version number in the cache_version argument to force an update check.

Note: Caching the JAR file is applicable only to users of Java plug-ins prior to Java 6 Update 10.

For more information on how caching options work, see the Applet Caching article in the Java documentation.

8.4 Customizing the Loading Experience

JavaFX 1.3.1 introduced many improvements to the application startup experience, including a progress indicator, and the ability to customize all phases of application startup. See the article JavaFX Application Startup Experience.

For applications running in the browser, the JavaFX 1.3.1 application startup experience requires Java Runtime Environment (JRE) update 21 or later with Java Plug-In 2 enabled.

For earlier versions of JavaFX, or for applications running on the Mac OS X platform, you can customize the splash screen that appears during application startup. Customizing the splash screen brands your application and reduces the perceived startup time. See the article Make a Big Splash With Your Applet Startup.

8.5 Changing the Location of Deployment Files

The easiest deployment is to keep the JNLP file in the same directory with the JAR file. However, it is possible to put the JNLP and JAR files in separate directories, or even on a different server. For example, such a need could arise when business or IT policy dictates file locations.

Tip: Ensure your application is running as expected when the web page, JAR file, and JNLP file are all in one directory before moving files to other locations.

Follow these general rules to successfully change the location of your deployment files:

• Use the archive attribute in the web page script to indicate the location of the JAR file. If the JAR file is on the same server as the web page, you can use a relative link or an absolute URL. If the JNLP file is in the same directory as the JAR file, you do not need to specify the location of the JNLP file.
  
  
• When the JAR file is on a different server from the web page, you must sign the application.
  
  
• When the JNLP file is in a different location from the JAR file, add the jnlp_href parameter to the script to indicate the location of the JNLP file.

The following things happen when the jnlp_href attribute is present in the web page script:

• If you have a codebase attribute specified in your JNLP file, the jnlp_href parameter overrides it.
  
  
• For Java 6 Update 10 and later versions, the archive and code attributes in the web page script are ignored. The location of the JAR file is taken from the <jar> tag, nested under the <resources> tag in the JNLP file. The application's main class location is determined from the <param> tag, nested under the <applet-desc> tag in the JNLP.
  
  Note: The archive and code parameters are still necessary for the application to run on versions other than Java 6 Update 10 and later , such as Apple Java.

The following cases assume that the attributes have been removed from the <jnlp> tag in the JNLP file. For more information about removing these attributes, see Section 4.1, Mandatory Manual Configuration.

Case 1

Your JNLP and JAR files are both in the same directory, but they are in a different directory from your web page, and all three files are on the same server. This case is shown in Figure 1.

Figure 1: JNLP and JAR Files in a Different Directory from Web Page, But Same Server

Use the archive attribute in the script that calls the application to point to the location of the JAR file relative to the location of the web page. In this example, the JAR file is in a sibling directory relative to the web page, so the script will appear as shown in Example 1.

<script src="http://dl.javafx.com/1.3/dtfx.js"></script>
<script>
    javafx(
        {
            archive: "../applications/MyApp.jar",
            width: 90,
            height: 150,
            code: "myapp.Main",
            name: "MyApp"
        }
    );
</script>

Note:

• The location of the JNLP file is assumed to be in the same directory with the JAR file.
  
  
• In the JNLP file, a relative URL cannot contain parent directory notations, such as "../". If you specify the location of the JAR file using the codebase attribute in the <jnlp> tag in the JNLP file, it is best to use a full URL. If you are not sure if a relative URL is acceptable, use the full URL.
  
  

Case 2

Like Case 1, your JNLP file is in the same directory with the JAR file, but they are on a different server from the web page. This case is shown in Figure 2.

Figure 2: JNLP and JAR Files in a Different Directory from Web Page, on a Different Server

In this case, you must make the following changes to the standard packaging process:

1. Sign the application, because the JAR file is on a different server from the web page.
   
   
2. Add a fully qualified URL to the archive attribute of the script embedded in the web page to point to the location of the JAR file, as shown in the script in Example 2. Once again, the location of the JNLP will be assumed to be the same directory as the JAR file.
   
   
   Example 2: Script when JNLP and JAR Files Are on a Different Server

   <script src="http://dl.javafx.com/1.3/dtfx.js"></script>
   <script>
       javafx(
           {
               archive: "http://apps.example.com/applications/MyApp.jar",
               width: 90,
               height: 150,
               code: "myapp.Main",
               name: "MyApp"
           }
       );
   </script>
   

Case 3

The JNLP file is in a different location from the JAR file, but all three files are on the same server. The JNLP file does not have to be in the same location as the web page, but it is in the example shown in Figure 3.

Figure 3: JNLP in a Different Directory from JAR File, Same Server

In this case, you must make the following changes to the standard packaging process:

1. Add the jnlp_href attribute to specify the location of the JNLP file relative to the location of the web page.
   
   
2. Use the archive attribute in the application script to point to the location of the JAR file relative to the location of the web page. Because the jnlp_href attribute is present, the archive attribute is ignored by Java 6 Update 10 and later versions but is still used by other versions of Java Runtime, which do not utilize JNLP configuration when applications run in the browser.
   
   
3. Set the <jar> tag in the <app_name>_browser.jnlp file to point to the same location as the archive attribute in the script. This information will be used by Java 6 Update 10 and later versions.
   
   
4. In the same JNLP file, check the <param> tag, nested under the <applet-desc> tag, to ensure that the application's main class location is correct. The value should match the code attribute in the script.

The script in Example 3 shows the settings for this case.

<script>
    javafx(
        {
            archive: "../Applications/MyApp.jar",
            jnlp_href: "MyApp_browser.jnlp",
            width: 90,
            height: 150,
            code: "myapp.Main",
            name: "MyApp"
        } 
    ); 
</script>

The excerpt from the <app_name>_browser.jnlp file in Example 4 shows the correct settings for this case.

<resources>
    <j2se version="1.5+"/>
    <extension name="JavaFX Runtime" href="http://dl.javafx.com/1.3/javafx-rt.jnlp"/>
    <jar href="../Applications/MyApp.jar" main="true"/>
</resources>
<applet-desc name="TestApp" main-class="com.sun.javafx.runtime.adapter.Applet" width="90" height="150">
    <param name="MainJavaFXScript" value="myapp.Main"/>
</applet-desc>

Case 4

The JNLP file is in a different location from the JAR file, but all three files are on the same server, as shown in Figure 4.

Figure 4: JNLP File in a Different Directory from JAR File, Different Server

In this case, you must make the following changes to the standard packaging process:

1. Sign your application, because the JAR file is on a different server from the web page.
   
   
2. Add the jnlp_href attribute to specify the location of the JNLP file relative to the location of the web page.
   
   
3. Use a fully qualified URL in the archive attribute of the web page script to point to the location of the JAR file. Because the jnlp_href attribute is present, the archive attribute is ignored by Java 10 and later versions but is still used by other versions of Java Runtime, which do not utilize JNLP configuration when applications run in the browser.
   
   
4. Set the <jar> tag in the <app_name>_browser.jnlp file to point to the same location as the archive attribute in the script. This information will be used by Java 6 Update 10 and later versions.
   
   
5. In the same JNLP file, check the <param> tag, nested under the <applet-desc> tag, to ensure that the application's main class location is correct. The value should match the code attribute in the script.

The script in Example 5 shows the settings for this example.

<script>
    javafx(
        {
            archive: "http://apps.example.com/applications/MyApp.jar",
            jnlp_href: "MyApp_browser.jnlp",
            width: 90,
            height: 150,
            code: "myapp.Main",
            name: "MyApp"
        } 
    ); 
</script>

The excerpt from the <app_name>_browser.jnlp file in Example 6 shows the correct settings for this case.

<resources>
    <j2se version="1.5+"/>
    <extension name="JavaFX Runtime" href="http://dl.javafx.com/1.3/javafx-rt.jnlp"/>
    <jar href="http://apps.example.com/applications/MyApp.jar" main="true"/>
</resources>
<applet-desc name="TestApp" main-class="com.sun.javafx.runtime.adapter.Applet" width="90" height="150">
    <param name="MainJavaFXScript" value="myapp.Main"/>
</applet-desc>

8.6 Making Browser Applications Draggable

The draggable option enables Windows users to drag the application out of the browser by pressing the Alt key and dragging with the left mouse button. After the application is dragged and disconnected from the web page by closing the browser, it acts like a Web Start application. If you enable dragging, you can also give users the option to add a desktop shortcut for the Web Start application.

Tip: Adding a desktop shortcut option will cause a dialog box to appear during downloading, asking users if they want to create a desktop shortcut. Unless you are sure you need this option, the downloading of the Web Start application will be smoother without it.

You can enable dragging and add a desktop shortcut option at either the packaging or the configuration stage.

8.6.1 Enabling Draggability During the Packaging Process

In the NetBeans IDE:

• On the Application tab of the NetBeans IDE project properties, select the checkbox Draggable Applet.
  
  
• If you want to add a desktop shortcut, enter -shortcut in the text box labeled Additional JavaFX Packager Options.
  
  

With the javafxpackager command:

• Add the -draggable option to the command line.
  
  
• If you want to add a desktop shortcut, enter the -shortcut option as well, for example:
  
  javafxpackager -src src -appName MyApp -appClass myapp.Main -appWidth 527
-appHeight 602-appVendor "Example Corporation" -draggable -shortcut

Either of these methods results in the addition of a draggable: true attribute in the script that calls the application from the web page. See Section 8.6.2 for an example of this attribute.

8.6.2 Enabling Draggability with Manual Configuration

Draggability is enabled in the script that calls the application from the web page. If you want to give the user an option to add a shortcut to the desktop after the application is dragged and becomes a Web Start application, you must edit the JNLP file as well, as described in the following instructions:

• To enable dragging, add a draggable attribute to the application script in the web page and set it to true, as shown in the following example:

  <script>
      javafx(
          {
              archive: "MyApp.jar",
              draggable: true,
              width: 527,
              height: 27,
              code: "myapp.Main",
              name: "MyApp"
          }
      );
  </script>
  

  
  
• To enable the user to create a desktop shortcut, open <app_name>_browser.jnlp and insert a <shortcut> element, as shown in the following example.

  <jnlp>
      <information>
          <title>MyApp</title>
          <vendor>Oracle Corporation</vendor>
          <homepage href=""/>
          <description>MyApp</description>
          <offline-allowed/>
          <shortcut>
              <desktop />
          </shortcut>
      </information>
      ...
     

  
  Note: Both the <shortcut> and <offline-allowed/> elements are required if you want the user to get the option to create a desktop shortcut when the application is dragged out of the browser and becomes a Web Start application. The <offline-allowed/> element is generated automatically, and the <shortcut> element must be added manually.

9 Troubleshooting

Your code compiled properly, but your deployed application does not look right, or it is not running, or it runs in some cases but not others. Go to the section that best describes your problem.

• Section 9.1, New Version of Application Does Not Look Right
• Section 9.2, Application Runs in the NetBeans IDE but Not Outside It
• Section 9.3, Deployed Application Does Not Run
• Section 9.4, Application Fails Intermittently

9.1 New Version of Application Does Not Look Right

Problem: Your application was running in the browser. You made a small change and compiled again. The new version runs, but it doesn't look the way you expected.

Solution: Clear your Java and browser caches.

• To clear the Java cache, open a terminal window and enter the following string:
  javaws -uninstall
  
  
• To clear the browse cache, delete the temporary files in your browser. This procedure varies by browser. As an alternative, close the browser and open it again.

You can also clear the Java cache in the Java Control Panel, using the following procedure.

1. Open the Java Control Panel. On Windows systems, you can access the Java Control Panel through the Windows Control Panel.
   
   
2. In the Temporary Internet Files section click Settings.
   
   
3. In the Temporary Files dialog box, click Delete Files.

9.2 Application Runs in the NetBeans IDE but Not Outside It

Problem: You ran your application in Browser mode in the NetBeans IDE and it worked fine, but when you test the application outside the NetBeans IDE by opening the HTML file, the application does not run, even though the files have not been moved from their original location.

Solution: There might be no web server on your system to recognize the local host URL that was generated during packaging. This problem is resolved when you transfer the deployment files to a web server.

A second possible cause is that the Java and browser caches need to be cleared. Follow the instructions in Section 9.1, New Version of Application Does Not Look Right.

9.3 Deployed Application Does Not Run

Problem: Your application compiled successfully, but now that you have deployed the files to a server, the application does not run.

Solution: If you have some experience with deployment, you can look at the Java console to determine the error. To enable the Java console, use the following procedure:

1. Open the Java Control Panel from the Windows Control Panel, or open Java Preferences from the Mac Utilities folder.
   
   
2. On the advanced tab, select Show Console.

If the error message in the Java console does not make the source of the problem clear, use this basic troubleshooting sequence to check the generated application files:

1. Open the HTML file, find the two <script> tags for the application, and check the following items.
   
   
   • Does the archive attribute value indicate the location of the JAR file relative to the web page? In your browser, try entering the URL that matches the location of the JAR and JNLP file to test if you get a request to download, as in the following example:
     
     The HTML file location is http://mydomain.example.com/MyJavaFX/MyApp.html.
     The archive attribute in the web page script is: archive: "dist/MyApp.jar"
     In your browser, enter the following URL:
     http://mydomain.example.com/MyJavaFX/dist/MyApp.jar
     If you get a 404 error instead of a download dialog box, the JAR file is not in the right location.
     
     
   • Is your JNLP file in the right location? Continuing with the previous example, enter the following URL in your browser:
     http://mydomain.example.com/MyJavaFX/dist/ MyApp_browser.jnlp
     If you get a 404 error, the JNLP file is not in the right location.
     
     
   • Check the case of the application and package names. It is standard practice to name applications with camel case (such as MyApp) and to name the main package with the same name in lowercase (such as myapp), so it is easy to get the case confused during deployment. The JAR file name and the archive attribute in the script use the application name. The code attribute in the script uses the package name, for example:
     
     The MyApp application has a package named myapp. Assuming that your entry class is called Main.fx, the archive and code attribute values should be as shown in the following script:
     
     

     <script>
         javafx(
             {
                   archive: "dist/MyApp.jar",
                   width: 510,
                   height: 345,
                   code: "myapp.Main",
                   name: "MyApp"
             }
         );
     </script>
     

     In this example, the JAR and JNLP files should be MyApp.jar and MyApp_browser.jnlp.
     
     
   • Does the version of dtfx.js in the script embedded in the web page match the version of the JAR file? The first <script> tag contains a URL that accesses a specific version of the dtfx.js file. The version of the dtfx.js file accessed at runtime must match the version of JavaFX used to compile the JAR file.
     
     
2. Check the contents of the JNLP file.
   
   
   • Is the XML in the JNLP file well formed? Check to ensure that there are both open and close tags for every element, or that single tags that do not contain content have closing slashes.
     
     Tip: Use any XML well-formedness checking tool.
     
     
   • Does the <jnlp> tag have any attributes? The <jnlp> tag should stand alone, or if there are attributes, the codebase attribute should contain a full URL to the location of your JAR and JNLP files. See Section 4, Configuring the JNLP File.
     
     

9.4 Application Fails Intermittently

This category includes several scenarios:

• The application seems to work intermittently on the same machine.
• The application runs on some clients but not others.
• The application works on some servers but not others.

Problem: The application runs intermittently in the same environment.

Solution: Try the troubleshooting steps in the following sections:

• Section 9.1, New Version of Application Does Not Look Right
• Section 9.2, Application Runs in the NetBeans IDE but Not Outside It

Problem: Applications run in browsers on Mac clients but not on clients with other operating systems.

Solution: Because the Apple version of Java does not rely on the JNLP file when applications are run in the browser, success on a Mac system and failure on other clients suggests that there is a problem with the JNLP file. Try the troubleshooting steps for checking the contents of the JNLP file in Section 9.3.