Documentation Contents
Java Platform, Standard Edition Deployment Guide
Contents Previous Next

# 2 Getting Started

This topic describes the basics of deploying your Java and JavaFX applications.

This topic contains the following sections:

- Section 2.1, "Basic Steps"

- Section 2.2, "Choose the Execution Environment"

- Section 2.3, "Create the Package"

- Section 2.4, "Create the Web Page"

- Section 2.5, "Distribute Your Application"

- Section 2.6, "Beyond the Basics"

## 2.1 Basic Steps

Have an application ready to publish? Follow these steps for basic deployment:

1. Decide how you want users to access and run your application.

   Applications can be deployed on a user's desktop, embedded in a web page, or launched from a browser.

2. Create the application package.

   The application package consists of the JAR files needed to run your application, and the deployment descriptor or JNLP file for applications that are embedded in a web page or are launched from a browser. If your application is embedded in a web page or is launched from a browser, the JAR files must be signed with a valid signing certificate. A self-contained application package also includes the JRE needed.

3. Set up the web page, if your application is embedded in a web page or is launched from a browser.

   The web page needs either HTML elements or JavaScript code to run an application embedded in the page. JavaScript code is needed to launch an application from the browser. The Java packaging tools generate JavaScript code for both types of execution, which you can copy into your web page.

4. Copy the package to the location from which you want users to access it.

   A web server is typically used for applications embedded in a web page or launched from a browser. Desktop applications can be delivered directly to users or made available through an app store.

## 2.2 Choose the Execution Environment

Java and JavaFX applications can be run in multiple execution environments. How you want users to access your application determines how you deploy it. The following options are available:

- Launch as a desktop application

  Users can start the application from the command line using the Java launcher, or by double-clicking the JAR file for the application.

- Launch from a browser

  Users can download and start the application by clicking a link in the browser.

- View in a web page

  The application starts when the web page is loaded.

Each environment has advantages and disadvantages. See Section 3.1, "Execution Modes" for more information.

## 2.3 Create the Package

By default, the Java packaging tools generate the following collection of files needed to run the application:

- An application JAR file (or multiple JAR files for large applications)

  Applications that are embedded in a web page or launched from a browser must be signed with a valid signing certificate. The packaging tools or the `jar` command can be used to sign the JAR file.

- A JNLP file with a deployment descriptor

  A deployment descriptor is an XML file that describes application components, platform requirements, and launch rules.

- An HTML file containing JavaScript code to embed or launch applications from the web page

Applications can also be packaged as a platform-specific, self-contained application. Self-contained applications include all application resources, the JRE, and a launcher. These applications provide the same install and launch experience as native applications for the operating system.

Self-contained applications can be distributed as zip files or as installable packages: EXE or MSI for Windows; DMG, PKG, or mac.appStore for OS X, or RPM or DEB for Linux.

Self-contained applications provide the following benefits:

- They resemble native applications for the target platform.

  Users install the application with an installer that is familiar to them, and launch it in the usual way.

- They offer no-hassle compatibility.

  The version of JRE that is used by the application is controlled by the application developer.

- They are easily deployed on fresh systems with no requirement for the JRE to be installed.

- Deployment occurs with no need for admin permissions when using ZIP or user-level installers.

For more information, see Chapter 7, "Self-Contained Application Packaging."

### 2.3.1 Packaging Tools

Three different tools are available for packaging your application:

- Section 2.3.1.1, "NetBeans IDE"

- Section 2.3.1.2, "Ant Tasks"

- Section 2.3.1.3, "Java Packager Command-Line Tool"

For more information about Java packaging, see Chapter 6, "Packaging Basics."

#### 2.3.1.1 NetBeans IDE

If you use Netbeans IDE, then much of the work is done for you. Open Project Properties to specify preferred dimensions for your JavaFX application scene. Build the project with Clean and Build. The application package is generated in the `dist` folder. To test your application, open this folder in Windows Explorer and double-click the HTML, JNLP, or JAR file, depending on your execution environment.

To package a self-contained application, customize the `build.xml` script in the NetBeans IDE. For more information, see Section 7.3.2, "Basic Build."

#### 2.3.1.2 Ant Tasks

If you are using another IDE, then you can add Java packaging as a post-build step, using Ant tasks that are included in the JDK. Example 2-1 shows an Ant package task for the JavaFX example Colorful Circles. Download the ColorfulCircles.zip file for the complete Colorful Circles example.

When you add the `nativeBundles="all"` attribute into the `<fx:deploy>` Ant task, all possible packages are created: a standalone application package, one or more self-contained application packages for the platform on which you are running, and a web deployment package. Installable packages are created based on the third-party software that is available at packaging time. For example, if you have both Inno Setup and WiX on Windows, then you get three packages: a folder with the application, an .exe installer file, and an .msi installer file. For more information, see Chapter 5, "Packaging Basics." A simple Ant task with the `nativeBundles` attribute is shown in Example 2-1.

Example 2-1 Ant Task to Produce All Packages for the ColorfulCircles Application

    <taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
            uri="javafx:com.sun.javafx.tools.ant"
            classpath="${javafx.sdk.path}/lib/ant-javafx.jar"/>

    <fx:jar destfile="dist-web/ColorfulCircles.jar">
        <fx:application mainClass="colorfulcircles.ColorfulCircles"/>
        <fileset dir="build/classes/">
            <include name="**"/>
        </fileset>
    </fx:jar>

    <fx:deploy width="800" height="600" outdir="dist-web"
            outfile="ColorfulCircles" nativeBundles="all">
        <fx:info title="Colorful Circles"/>
        <fx:application name="Colorful Circles example"
                mainClass="colorfulcircles.ColorfulCircles"/>
        <fx:resources>
            <fx:fileset dir="dist-web" includes="ColorfulCircles.jar"/>
        </fx:resources>
    </fx:deploy>

If your application will be embedded in a web page or launched from a browser, include the required JAR mainfest attributes in the `<fx:jar>` task and include an `<fx:signjar>` task.

#### 2.3.1.3 Java Packager Command-Line Tool

If you cannot use Ant and prefer command-line tools, use the Java Packager tool that comes with the JDK. The Java Packager tool has several commands for packaging applications, described in Chapter 9, "The Java Packager Tool." For a quick test build, you can use the `javapackager -makeall` command, such as the one in Example 2-2. This command compiles source code and combines the `javapackager -createjar` and `javapackager -deploy` commands, with simplified options.

Example 2-2 javapackager -makeall Command to Build an Application

    javapackager -makeall -appclass colorfulcircles.ColorfulCircles
        -name "Colorful Circles" -width 800 -height 600

As a command intended only to help to build simple projects quickly, the `-makeall` command supports a limited set of options to customize the command behavior. The `-makeall` command makes the following assumptions about input and output files:

- Source and other resource files must be in a directory named `src` under the main project directory.

- The resulting package is always generated to a directory named `dist`, and file names all start with the dist prefix.

- By default, the `-makeall` command tries to build a self-contained application package. If this is not possible, the JAR, HTML, and JNLP files are generated so you can deploy to other execution modes.

Note: For JavaFX applications that are embedded in a web page, stage width and height must always be specified.

When your application is ready to go live, use the `-createjar` and `-deploy` commands instead of the `-makeall` command. The `-createjar` and `-deploy` commands have considerably more options. Also use the `-signjar` command if your application is embedded in a web page or launched from a browser. You can create a self-contained application package with the `-deploy` command plus the `-native` option, for example:

    javapackager -deploy -native -outdir packages -outfile ColorfulCircles
        -srcdir dist -srcfiles ColorfulCircles.jar
        -appclass colorfulcircles.ColorfulCircles

For more information, see Section Section 5.3.1, "Java Packaging Tools."

Tip: For even more flexibility of options, use an Ant task instead of the Java Packager tool.

## 2.4 Create the Web Page

If your application is embedded in a web page or launched from a browser, you need to set up the web page that provides users with access to your application. The Java Plug-in is used to run an application embedded in the web page. Java Web Start is used to run an application that is launched from the browser.

You can use an `<applet>` or `<object>` element or JavaScript code for applications that are embedded in a web page and use the Java Plug-In to run. Use JavaScript code to create the link or button that calls Java Web Start to launch an application from the browser. The Java packaging tools generate JavaScript code for both types of execution, which you can copy into your web page.

The HTML page generated by the packaging tools is a simple test page for your application. It includes sample JavaScript code to launch and embed your application, which you can copy to your own web page. To avoid manual copying, consider using HTML templates for application packaging to insert the JavaScript code into an existing web page. For more information, see Section 5.7.4, "Web Page Templates."

## 2.5 Distribute Your Application

When you have your application package and any web pages that you are using, copy them to the appropriate location to make your application available to users.

- If your application is embedded in a web page or launched from a browser, copy your package and the web page to the web server from which they will be loaded.

- If your application is a desktop application, copy the application to the location from which users will download it. Self-contained applications provide installable packages and the required JRE, which makes it easier for users to install and run your application.

## 2.6 Beyond the Basics

This topic provides the minimum information needed to deploy a simple application, which makes use of the default processing that is provided by the packaging tools. More advanced applications could have additional requirements, for example:

- Include a custom splash screen that is shown when your application is loaded.

- Include a custom progress bar that is shown while your application is loading.

- Use JavaScript code to communicate between your application and the web page in which it is embedded.

- Deploy Swing and SWT Applications with Embedded JavaFX Content

- Minimize the number of security dialogs and the warnings contained within the dialogs to help ensure users that it is safe to run your application.

The Deployment trail in the Java Tutorials also provides information to help you deploy applications embedded in a web page or launched from a browser.

Contents Previous Next

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.
Contact Us