现在的位置: 首页 > 综合 > 正文

6 Self-Contained Application Packaging A self-contained application is a wrapper for your JavaFX ap

2013年10月20日 ⁄ 综合 ⁄ 共 17800字 ⁄ 字号 评论关闭

6 Self-Contained Application Packaging

转自:http://docs.oracle.com/javafx/2/deployment/self-contained-packaging.htm

A self-contained application is a wrapper(包装程序) for your JavaFX application, making it independent of what the user might have installed.

6.1 Introduction

JavaFX packaging tools provide built-in support for several formats of self-contained application packages. The basic package is simply a single folder on your hard drive that includes all application resources as well as Java Runtime.
It can be redistributed as is, or you can build an installable package (for example, EXE or DMG format).

From the standpoint of process, producing a self-contained application package is very similar to producing a basic JavaFX application package as discussed in Chapter
5, "Packaging Basics,"
with the following differences:

  • Self-contained application packages can only be built using JDK 7 Update 6 or later. (The standalone JavaFX SDK does not support self-contained applications.)

  • Self-contained application packages must be explicitly requested by passing additional arguments to the <fx:deploy> Ant task or javafxpackager tool.

  • Operating system and tool requirements must be met to be able to build a package in a specific format.

While it is easy to create a basic self-contained application package, tailoring it to achieve the best user experience for a particular distribution method usually requires some effort and a deeper understanding of the topic.

6.2 Pros and Cons of Self-Contained Application Packages

Deciding whether the uses of self-contained application packages is the best way to deploy your application depends on your requirements.

Self-contained application packages have several benefits:

  • They resemble native applications for the target platform, in that 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 Java Runtime used by the application is fully controlled by the application developer.

  • Your application is easily deployed on fresh systems with no requirement for Java Runtime to be installed.

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

On the other hand, there are a few caveats:

  • "Download and run" user experience

    Unlike web deployment, the user experience is not about "launch the application from the web." It is more one of "download, install, and run" process, in which the user might need to go through additional steps to get the application launched. For example,
    the user might have to accept a browser security dialog, or find and launch the application installer from the download folder.

  • Larger download size

    In general, the size of self-contained application packages will be noticeably larger than the size of a standalone application, because a private copy of Java Runtime is included.

  • Package per target platform

    Self-contained application packages are platform specific and can only be produced for the same system that you build on. If you want to deliver self-contained application packages on Windows, Linux and Mac you will have to build your project on all three platforms.

  • Application updates are the responsibility of developer

    Web-deployed Java applications automatically download application updates from the web as soon as they are available. The Java Autoupdate mechanism takes care of updating the Java and JavaFX Runtimes to the latest secure version several times every year. There
    is no built-in support for this in self-contained applications.

6.3 Basics

Each self-contained application package includes the following:

  • The application code, packaged into a set of JAR files, plus any other application resources (data files, native libraries)

  • A private copy of the Java and JavaFX Runtimes, to be used by this application only

  • A native launcher for the application

  • Metadata, such as icons

Multiple package formats are possible. Built-in support is provided for several types of packages, but you can assemble your own packages by post-processing a self-contained application packaged as a folder, for example if you want
to distribute your application as a ZIP file.

6.3.1 Self-Contained Application Structure

The basic form of a self-contained application is a single folder on your hard drive, such as the example in Figure
6-1
. When any of the installable packages are installed, the result is a folder with the same content.

Figure 6-1 Example of a Self-Contained Application Package

Surrounding text describes Figure 6-1 .

The internal structure of a self-contained application folder is platform-specific and may change in future. However, the following points are guaranteed:

  • The application package, as defined in Chapter 5, "Packaging Basics,", is included as a folder, preserving the application directory
    structure.

  • A copy of Java Runtime is included as another folder, and the Java Runtime directory structure is preserved.

Because directory structure is preserved, the application can load external resources using paths relative to the application JAR or java.home system property.

Note:

Only a subset of Java Runtime is included by default. Some optional and rarely used files are excluded to reduce the package size, such as all executables. If you need something that is not included by default,
then you need to copy it in as a post-processing step. For installable packages, you can do this from the config script that is executed after populating the self-contained application folder. See Section
6.3.3, "Customization Using Drop-In Resources."

6.3.2 Basic Build

The easiest way to produce a self-contained application is to modify the deployment task. To request creation of all applicable self-contained application packages simply addnativeBundles="all" to
the <fx:deploy> task, as shown in Example 6-1.

Example 6-1 Simple Deployment Task to Create All Self-contained Application Packages

<fx:deploy width="${javafx.run.width}" height="${javafx.run.height}"
           nativeBundles="all"
           outdir="${basedir}/${dist.dir}" outfile="${application.title}">
    <fx:application name="${application.title}" mainClass="${javafx.main.class}"/>
    <fx:resources>
        <fx:fileset dir="${basedir}/${dist.dir}" includes="*.jar"/>
    </fx:resources>
    <fx:info title="${application.title}" vendor="${application.vendor}"/>
</fx:deploy>

You can also specify the exact package format you want to produce. Use the value image to produce a basic package, exe to
request an EXE installer, dmg to request a DMG installer, and so on. For the full list of attribute values, see the nativeBundles attribute
in the <fx:deploy>entry in the Ant Task Reference.

If you have a JavaFX project in Netbeans 7.2, you can add the above snippet as a post-build step by overriding the "-post-jfx-deploy" target, as shown in Example
6-2
. Add the following code to the build.xml file in the main project directory.

Example 6-2 Custom build.xml Script to Create Self-contained Application Packages in NetBeans IDE

<target name="-post-jfx-deploy">
       <fx:deploy width="${javafx.run.width}" height="${javafx.run.height}" 
                  nativeBundles="all"
                  outdir="${basedir}/${dist.dir}" outfile="${application.title}">
          <fx:application name="${application.title}" 
                          mainClass="${javafx.main.class}"/>
          <fx:resources>
              <fx:fileset dir="${basedir}/${dist.dir}"
                          includes="*.jar"/>
          </fx:resources>
          <fx:info title="${application.title}" 
                   vendor="${application.vendor}"/>
        </fx:deploy>          
     </target>

You can also produce native packages using the JavaFX Packager tool. self-contained application packages are built by default if you use the -makeall command, or you
can request them explicitly using the -native option in the -deploy command. See the javafxpackagercommand
reference.

Example 6-3 shows the use of the -native option
with the -deploy command, used to generate all applicable self-contained application packages for the BrickBreaker application. The-deploy command
requires a JAR file as input, so it assumes that dist/BrickBreaker.jar has already been built:

Example 6-3 JavaFX Packager Command to Generate Self-Contained Application Packages

javafxpackager -deploy -native -outdir packages -outfile BrickBreaker 
    -srcdir dist -srcfiles BrickBreaker.jar -appclass brickbreaker.Main 
    -name "BrickBreaker" -title "BrickBreaker demo"

6.3.3 Customization Using Drop-In Resources

The packaging tools use several built-in resources to produce a package, such as the application icon or config files. One way to customize the resulting package is to substitute built-in resource with your customized version.

For this you need to:

  • Know what resources are used

  • Drop custom resources into a location where the packaging tool will look for them

The following sections explain how to do this.

6.3.3.1 Preparing Custom Resources

To get more insight into what resources are being used, enable verbose mode by adding theverbose="true" attribute to <fx:deploy>,
or pass the -v option to the javafxpackager -deploycommand.

Verbose mode does the following:

  • It prints the following items:

    • A list of config resources used for the package you are generating

    • The role of each resource

    • The expected custom resource name

  • It saves a copy of all config files to the temp folder, so you can use and customize it.

Example 6-4 shows sample output, with the important parts highlighted:

Example 6-4 Sample Output in Verbose Mode

Using base JDK at: /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk
  Using default package resource [Bundle config file] (add
    package/macosx/Info.plist to the class path to customize)
  Using default package resource [icon] (add package/macosx/DemoApp.icns
      to the class path to customize)
Creating app bundle: /tmp/test/TestPackage/bundles/DemoApp.app
Config files are saved to /var/folders/rd/vg2ywnnx3qj081sc5pn9_
    vqr0000gn/T/build7039970456896502625.fxbundler/macosx. Use them 
    to customize package.

Now you can grab a copy of the config file and tune it to your needs. For example, you can take Info.plist and add localized package names.

Note: It is recommended that you disable verbose mode once you are done with customization or add a custom cleanup action to remove sample config files.

6.3.3.2 Substituting a Built-In Resource

Packaging tools look for customized resources on the classpath before reverting to built-in resource. The Javafx Packager has "." (the current working directory) added to the classpath by default. Hence, to replace the application
icon, simply copy your custom icon to ./package/macosx/DemoApp.icns in the directory where javafxpackager is run (typically, the root project directory).

The classpath for JavaFX Ant tasks is defined when task definitions are loaded. You must add an additional path to the lookup before the path ant-javafx.jar.

Example 6-5 shows how to add "." to the classpath. For a more detailed code snippet,
seeExample 10-1).

Example 6-5 Enabling Resource Customization for JavaFX Ant Tasks

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

If you created a JavaFX project using Netbeans 7.2 or later, then the JavaFX Ant tasks are predefined, and "." is already added to the classpath by default.

Once you provide a customized resource, verbose build output will report that it is used. For example, if you added a custom icon to an application, then the verbose output would report the addition, shown in Example
6-6
.

Example 6-6 Verbose Output After Adding a Customized Icon Resource

Using base JDK at: /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk
  Using default package resource [Bundle config file] (add
      package/macosx/Info.plist to the class path to customize)
Using custom package resource [icon] (loaded from
    package/macosx/DemoApp.icns on class path)
Creating app bundle: /tmp/test/TestPackage/bundles/DemoApp.app

6.3.4 Customization Options

Many of the existing JavaFX Ant elements are used to customize self-contained application packages. Different sets or parameters are needed for different packages, and the same element might have different roles. Table
6-1
 introduces most of the customization options.

Table 6-1 Customization Options with Ant Elements and Attributes

Tag Attribute Details

<fx:application>

id

Identifier of application. Format is platform/package specific. If not specified, then a value will be generated.

 

version

Application version. Default: 1.0.

 

name

Short name of the application. Most bundlers use it to create the name of the output package. If not specified, then the name of the main class is used.

<fx:preferences>

shortcut

If set to true, then a desktop shortcut is requested.

 

menu

If set to true then an entry in the applications menu is requested.

 

install

If set to false, then a user-level installer is requested. Default behavior depends on the package format. See Table
6-2
.

<fx:fileset>

type

Defines the role of files in the process of assembling the self-contained application package. Resources of types jnlp and nativeare
not used for building self-contained application packages. Resources of typelicense are used as a source of content for a click-through license or a license embedded into the
package

<fx:info>

title

Application title.

 

vendor

Application vendor.

 

category

Application category. Category names are package-format specific.

 

license

License type (for example, GPL). As of JavaFX 2.2, this attribute is used only for Linux bundles.

 

copyright

Short copyright statement.

 

description

Application description.

<fx:jvmarg>

JVM arguments to be passed to JVM and used to run the application (for example, large heap size).

<fx:property>

Properties to be set in the JVM running the application.

6.3.5 Platform-Specific Customization for Basic Packages

Creation and customization of the basic form of self-contained application packages is a fairly straightforward process, but note the following points:

  • Different icon types are needed for different platforms.

    For example, on Windows, the .ico format is expected, and on Mac it is .icns. No icon is embedded into launcher on Linux.

  • To ensure that the icon is set in runtime, you also need to add it to the application stage. For example, add the following code to to the start() method of your application:

    stage.getIcons().add(new
        Image(this.getClass().getResourceAsStream("app.png")));
    
  • Consider signing files in output folder if you plan to redistribute them.

    For example, on Windows, the launcher executable can be signed using signtool.exe.

6.3.5.1 Mac OS X

The resulting package on Mac OS X is an "application bundle" (or .app) in the Mac OS "dialect/jargon".

Several config parameters end up in the Info.plist file in the application bundle and need to conform to the rules:

Mac OS X 10.8 introduces Gatekeeper, which prevents execution of untrusted code by default (regardless of whether this code was implemented in Objective-C or Java).

The user can manually enable the application to run, but this is not a perfect user experience. To get optimal user experience, you need to obtain a Developer ID Certificate from Apple and sign the .app folder produced by JavaFX
packaging tools, as follows:

   % codesign -s "Developer ID Application" ExampleApp.app

For more details, see the Developer ID and Gatekeeper topic at the Apple Developer site.

6.4 Installable Packages

A self-contained application can be wrapped into a platform-specific installable package to simplify redistribution. JavaFX packaging tools provide built-in support for several formats of installable packages, depending on the availability
of third-party tools.

Tuning the user experience for the installation process is specific to the particular installer technology, as described in other sections in this chapter. However, you must decide what type of installer you need. The following considerations
that might help with your decision.

  • System-wide or per-user installation?

    System-wide installation results in a package installed into a shared location and can be used by any user on the system. On the other hand it assumes admin permissions and will likely result in additional steps during the installation process, such as an OS
    prompt to approve elevating installer permissions.

    Per-user installation copies the package into a private user directory and does not require admin permissions. This enables you to show as little dialogs as possible and run the program even if user is not eligible for admin privileges.

    Note that whenever a user- or system-level installable package is requested, the build procedure itself does not require admin permissions.

  • Do you need a click-through license?

    Some installable packages support showing license text before initiating the installation. The installation process starts only after the user accepts the license.

    Think carefully if you really need this, because extra dialogs degrade the user experience.

  • What menu/desktop integration is needed?

    The user should be able to launch your application easily. Therefore, we assume that having a desktop shortcut or adding the application to the list of applications in the menu is required.

Note that the current implementation contains many simplifying assumptions.

For example, installers never ask the user to choose the location to install the package. Developers also have limited control of the installation location—they can only choose system or private user location).

If this is not sufficient for your needs you can try advanced customizations by tuning the config file templates (see Section
6.3.3, "Customization Using Drop-In Resources"
) or packaging a basic self-contained application and then wrapping it into an installable package on your own.

As of JDK 7u6, the following installable package formats are supported:

Table 6-2 Installable Package Formats

Package format Installation Location(Default mode in bold) Click-Through License Prerequisites

EXE

Per user%LOCALAPPDATA%

System: %ProgramFiles%

Yes (option)

  • Windows

  • Inno Setup 5 or later

MSI

Per user: %LOCALAPPDATA%

System%ProgramFiles%

No special support

  • Windows

  • WiX 3.0 or later

DMG

Per user: user's desktop folder

System: /Applications

Yes (option)

  • Mac OS X

RPM

Per user: unsupported

System: /opt

No special support

  • Linux

  • RPMBuild

DEB

Per user: unsupported

System: /opt

No special support

  • Linux

  • Debian packaging tools

6.4.1 EXE Package

As of JavaFX 2.2, in order to generate an EXE package, you must have Inno Setup 5 or later installed and available on the PATH. To validate that it is available, try
running iscc.exe from the command line where you launch the build or from your build script.

By default, the generated package:

  • Does not require admin privileges(特权) to install

  • Is optimized(优化) to have a minimum number of dialogs

  • Must be referenced from programs menu or have desktop shortcut (having both are fine)

  • Is configured so the application launches at the end of installation

Figure 6-2 shows a typical dialog box for a self-contained JavaFX application being
installed on Windows.

Figure 6-2 Windows Installation Dialog for a Self-Contained JavaFX Application

Customization tips:

  • If you chose system-wide installation, then the user will need to have admin permissions, and the application will not be launched at the end of installation.

  • A click-through license is supported (an .rtf file is required).

  • The image shown in the installation dialogs is different from the application icon.

    You can customize it using the "drop-in technique" described in Section 6.3.3, "Customization Using Drop-In Resources."

    The current version of Inno Setup assumes the image is a bitmap file with maximum size of 55x58 pixels.

  • To ensure the icon is set in the runtime, make sure to explicitly add it to the stage. SeeSection 6.3.5, "Platform-Specific
    Customization for Basic Packages."

  • Consider signing the resulting .exe package. If you distribute an unsigned executable, then many versions of Windows will scare the user with an "Unknown Publisher" warning dialog.

    If you sign your package, then this warning will be removed. You will need to get a certificate and then can use the signtool.exe utility to
    sign the code.

  • You can fine tune the self-contained application folder before it is wrapped into an .exe file, for example to sign the launcher executable.

    To do this, provide a Windows script file, using the technique from Section 6.3.3, "Customization Using Drop-In Resources."

抱歉!评论已关闭.