3 Support Application Requirements

The packaging tool provides support for application requirements such as default arguments, JVM options, file associations, multiple launchers, and signing.

Set Default Command-Line Arguments

If your application accepts command-line arguments, use the --arguments option to define default values. Users can override these values when they start the application.

If you package your application with default command-line arguments, these values are passed to the main class when the user starts your application without providing arguments. The [ArgOptions] section of the app-name.cfg file in the /app directory of the application image generated by jpackage shows any default arguments that are defined. You can check this file to ensure that the values are defined correctly.

The following examples show some of the ways to set up default arguments:

  • Set the default value for a single argument.

    The following command defines the value for a single argument for the MyApp application.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments arg1 
  • Set the default value for more than one argument.

    Use a space to separate arguments and enclose the entire string in quotes, or use multiple instances of the --arguments option. The following commands show alternative ways to define three default command-line arguments for the MyApp application.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments "arg1 arg2 arg3" 
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments arg1 --arguments "arg2 arg3" 
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments arg1 --arguments arg2 --arguments arg3 
  • Set a default value that contains spaces.

    If an argument contains a space, two sets of quotes are needed to ensure that jpackage treats the spaces as part of the value and not as delimiters between values. Enclose the argument in single quotes, or double quotes preceded by the escape character, then enclose the quoted string in quotes. The following commands show alternative ways to define two arguments that contain spaces.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments "\"String 1\" \"String 2\"" 
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments "\"String 1\"" --arguments "\"String 2\"" 
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --arguments "'String 1'" --arguments "'String 2'" 

Set JVM Options

If you want options passed to the JVM when your application is started, use the --java-options option when you package your application. Users can't provide JVM options to the application.

To set up the JVM as needed to run your application, define the JVM options to pass when a user starts your application. Use the $APPDIR macro to reference resources included with the application. The resource file must be in the input directory when the application is packaged.

The [JavaOptions] section of the app-name.cfg file in the /app directory of the application image generated by jpackage shows any default arguments that are defined. You can check this file to ensure that the values are defined correctly.

The following examples show some of the ways to pass JVM options to your application:

  • Set a single JVM option.

    The following command sets the initial size of the heap for the MyApp application to 2 megabytes.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options Xms2m 
  • Set more than one JVM option.

    To provide more than one JVM option, use a space to separate arguments and enclose the entire string in quotes, or use multiple instances of the --jvm-options option. The following commands show alternate ways to set the initial size and the maximum size for the heap.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options "Xms2m Xmx10m"
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options Xms2m  --java-options Xmx10m
  • Set a JVM option that contains a space.

    If a JVM option contains a space, two sets of quotes are needed to ensure that jpackage treats the spaces as part of the option and not as delimiters between options. Enclose the argument in single quotes, or double quotes preceded by the escape character, then enclose the quoted string in quotes. The following commands show alternate ways to define an option that contain spaces.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options "\"-DAppOption=text string\""
    
    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options "'-DAppOption=text string'"
  • Set a JVM option that contains quotes.

    If a JVM option contains quotes, escape characters must be used for the quotes. The following command passes the JVM option -XX:OnError="userdump.exe %p" to jpackage.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options "-XX:OnError=\"\\\"userdump.exe %p\\\"\""
  • Use the $APPDIR macro with a JVM option.

    To use the image myAppSplash.jpg from the application directory as the splash screen for your application, use the $APPDIR macro as shown in the following example. The image file must be in the input directory when the application is packaged. Note that in some shells the dollar sign needs to be escaped, for example, \$APPDIR.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --java-options "-splash:\$APPDIR/myAppSplash.jpg"

Set File Associations

If you want your application to be started when a user opens a specific type of file, use the --file-associations option when you package your application.

To have your application started when a user opens a file that your application can handle, define the file associations that you want created when the application is installed. Associations are defined in properties files that are passed to jpackage. For each association, a separate file and a separate instance of the --file-associations option is required. The following properties define an association, which must include either mime-type or extension:

  • mime-type - MIME type for files that your application can process.

  • extension - File extension for files that your application can process.

  • icon - Icon to use for the type of files that your application can process. The icon must be in the input directory when the application is packaged. If no icon is specified, the default icon is used.

  • description - Short description of the association.

To set up file associations, first create the properties files. The following two files set up an association for JavaScript files and for Groovy files.

FAjavascript.properties:

mime-type=text/javascript
extension=js
description=JavaScript Source

FAgroovy.properties:

mime-type=text/x-groovy
extension=groovy
description=Groovy Source

The following command packages the application FADemo and sets up file associations using the properties files just created. When a user opens a .js or .groovy file, FADemo is started.

jpackage --name FADemo --input FADemo \
   --main-jar ScriptRunnerApplication.jar \
   --file-associations FAjavascript.properties \
   --file-associations FAgroovy.properties

Add Launchers

If you have more than one way start your application, use the --add-launcher option to describe the additional launchers that you want created.

You might want an additional launcher if your application has different default values for arguments or can run with or without the Windows console, or if you package multiple apps together to share a runtime. The format for the option is --add-launcher launcher-name=properties-file, where launcher-name is the named used for the additional launcher. Use quotes if the name contains spaces.

The launchers are defined in properties files that are passed to jpackage. For each launcher, a separate file and a separate instance of the --add-launcher option is required. The following properties define a launcher, at least one option must be set:

  • module - Name of the module that contains the main class for the launcher. If the main module does not identify the main class, include it in the format module=main-module/class.

  • main-jar - Name of the JAR file that contains the main class for the launcher.

  • main-class - Name of the main class.

  • arguments - Default arguments, separated by spaces. If an argument contains spaces, enclose the argument in quotes, for example, arguments=arg1 "arg 2" arg3

  • app-version - Version number.

  • java-options - Options to pass to the JVM, separated by spaces. If an argument contains spaces, enclose the argument in quotes.

  • icon - Icon used for the additional launcher

  • win-console - Set to true to start the console with the application.

To define additional launchers, first create the properties files. The following examples show some of the ways to set up a launcher:

  • Add a launcher with different application arguments.

    Create the following properties files that define different default arguments to use when the application is launched. The first file defines 3 arguments to pass. The second file defines two arguments to pass.

    MLAppArgs1.properties:
    
    arguments=arg1 arg2 arg3
    
    MLAppArgs2.properties:
    
    arguments="String 1" "String 2"

    The following command packages the application MyApp with two additional launchers using the properties files just created.

    jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
       --add-launcher MyApp1=MLAppArgs1.properties \
       --add-launcher MyApp2=MLAppArgs2.properties
  • Add a launcher to start the Windows console.

    To provide the user with the option of running your application with or without the console, create the following properties file that defines a launcher that uses the Windows console.

    MLConsole.properties:
    
    win-console=true

    The following command packages the HelloWorld application with an additional launcher that runs the application with the Windows console.

    jpackage --name HelloWorld --input helloworld \
       --main-jar HelloWorld.jar \
       --add-launcher HWConsole=MLConsole.properties 
  • Add a launcher for a second entry point.

    When more than one application is included in the same package, each application can be started independently by adding additional launchers. If the FADemo and the Dynamic Tree applications are packaged together and the main launcher is for the FADemo application, create the following properties file to define an additional launcher for the Dynamic Tree application.

    MLDynamicTree.properties
    
    main-jar=DynamicTree.jar
    main-class=webstartComponentArch.DynamicTreePanel
    icon=DTDemo.ico

    The following command packages the two applications together and sets up the additional launcher using the properties file just created.

    jpackage --name MLDemo --input MLDemo \
       --main-jar ScriptRunnerApplication.jar \
       --add-launcher "Dynamic Tree"=MLDynamicTree.properties

Sign the Application Package (macOS)

For an application that runs on macOS, use the --mac-sign and supporting options when you package your application. A signed .dmg package, .pkg package, or a Zip file made from an application image can be notarized.

In addition to the --mac-sign option that requests signing, you also need to provide the signing prefix with the --mac-package-signing-prefix option and key user name with the --mac-signing-key-user-name option. If a keychain other than the standard keychain is used, you also need to provide that keychain file with the --mac-signing-keychain option.

The following command generates a signed .dmg package using the prefix xxxxxx and the "Developer ID Application: developer.example.com" certificate. Quotes are required if a string includes spaces.

jpackage --name DynamicTreeDemo --input myApps --main-jar DynamicTree.jar \
   --mac-sign --mac-package-signing-prefix xxxxxx \
   --mac-signing-key-user-name developer.example.com

When a signed .pkg package is generated, the following command uses the prefix xxxxxx and the "Developer ID Installer: developer.example.com" certificate.

jpackage --type pkg --name DynamicTreeDemo --input myApps \
   --main-jar DynamicTree.jar --mac-sign --mac-package-signing-prefix xxxxxx \
   --mac-signing-key-user-name developer.example.com