This topic describes the basics of deploying your Java and JavaFX applications.
This topic contains the following sections:
Have an application ready to publish? Follow these steps for basic deployment:
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.
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.
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.
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.
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.
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."
Three different tools are available for packaging your application:
For more information about Java packaging, see Chapter 6, "Packaging Basics."
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."
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.
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. |
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."
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.
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.
