AppLauncher

The AppLauncher class launch a process to start a Java jar file.

The supported arguments are:

• The location of the JavaFX libraries if they are required
• The libraries path
• The module paths (the --add-modules declarations)
• The --add-opens declarations
• The --add-exports declarations
• The required Java version
• Environment variables
• Specific additional VM arguments

Overview

The class allows to start a new process with a specified JVM (not necessarily the current JVM used to execute the AppLauncher program) with customized arguments specified in a configuration file:

Extend the AppLauncher class

Mandatory methods

To extend the AppLauncher class, you need to implement the two following methods:

• The AppLauncher.getLaunchable() method must return the name of the jar file which contains the application to start. Note that this file must be in the same directory as the jar file which contains the launcher class
• The AppLauncher.getConfigurationFile() method must return the name of the configuration file which will be used to configure the application. This file must also be in the same directory as the jar file which contains the AppLauncher class

You also need to add a static main(String[]) method to create the launcher and call the AppLauncher.start() method which will start your application in a child process.

For example, suppose that you want to start the MyApplication.jar application with the MyAppLauncher.jar launcher. The file structure must be:

The code of the MyAppLauncher.jar class should be:

   public class MyAppLauncher extends AppLauncher {
      public AppLauncher(String[] args) {
        super(args);
      }  
      
      public static void main(String[] args) {
        MyAppLauncher launcher = new MyAppLauncher(args);
        launcher.start();
      }      
          
      @Override
      protected String getLaunchable() {
        return "MyApplication.jar";
      }

      @Override
      protected String getConfigurationFile() {
        return "confFile.conf";
      }
   }

Optional methods

Several optional methods allow to:

• Specify the module paths (the --add-modules declaration)
• Specify the --add-opens declarations
• Specify the --add-exports declarations
• Specify the required Java version
• Specify the allowed custom properties
• Specify the path of the main Class

Specify the module paths

The AppLauncher.setAddModules(String) method allows to set the --add-modules declaration^[1]

See dev.java for more information

.

For example:

   launcher.setAddModules("javafx.controls,javafx.fxml,javafx.graphics,javafx.swing,javafx.web");

Specify the --add-opens declarations

The AppLauncher.setAddOpensAllUnnamed(String...) method allows to set the ---add-opens declarations with an ALL-UNNAMED value^[2]

See dev.java for more information

.

For example:

   launcher.setAddOpensAllUnnamed("javafx.web/javafx.scene.web", "javafx.web/com.sun.webkit");

Specify the --add-exports declarations

The AppLauncher.setAddExportsAllUnnamed(String...) method allows to set the ---add-exports declarations with an ALL-UNNAMED value^[3]

See dev.java for more information

.

For example:

   launcher.setAddExportsAllUnnamed("javafx.web/javafx.scene.web", "javafx.web/com.sun.webkit");

Specify the required Java version

The AppLauncher.requireJavaVersion(String) method allows to specify a required JVM major version to execute your program. There are several ways to declare the version:

• If the argument has the {number} pattern, then the associated major version is required
• If the argument has the {number}- pattern, then the major version must be greater or equal to the associated number
• If the argument has the -{number} pattern, then the major version must be smaller or equal to the associated number
• If the argument has the {number}-{number} pattern, then the major version must be between the two associated numbers

For example:

   launcher.requireJavaVersion("11"); the major version must be 11
   launcher.requireJavaVersion("11-"); the major version must be 11 or more
   launcher.requireJavaVersion("-11"); the major version must be 11 or less
   launcher.requireJavaVersion("9-11"); the major version must be between 9 and 11

Specify the allowed custom properties

The AppLauncher.getCustomProperties() method returns the allowed set of custom properties names, which will be used in the configuration properties file. By

The AppLauncher.separateCustomArguments(boolean) specifies how the custiom properties names and values are handled in the arguments:

• By default the key and the values are concatenated with a "=" sign
• If the parameter of the "separateCustomArguments method is true, then the key and value will be on two separate arguments

For example:

• By default myKey=myValue in the configuration file will create in the arguments myKey=myValue
• With the true value for the method myKey=myValue in the configuration file will create in the arguments myKey myValue

Specify the main Class

The AppLauncher.setMainClass(String) method allows to specify the path of the main Class to use when starting the application.

For example:

  launcher.setMainClass("my.main.MyApplication");

Specify the path of the configuration file as an argument

The AppLauncher.getConfigurationFile() method return the name of the configuration file which will be used to configure the application. This file must be in the same directory as the jar file which contains the launcher class.

It is also possible to allow the user to specify the path of the file by using the -appLauncher.conf=>path> argument when you start the launcher. The path can be absolute or relative to the directory of the launcher.

For example:

      java -jar AppLauncher.jar -appLauncher.conf=myConfigFile.conf

If the path is empty, a file chooser will ask the user to select the file. For example:

      java -jar AppLauncher.jar -appLauncher.conf=

Configuration file properties

The file properties has several properties which allows to:

• JAVAHOME: Specifies the location of the JVM to use for the application to launch
• JAVAFXLIB: Specifies the location of the JavaFX libraries for use to the application to launch
• MODULEPATH: Specifies the "--module-path" argument. This is an alternate way of setting the "--module-path" through the API (see Specify the module paths)
• LIBPATH: Specifies the "java.library.path" argument
• VMARGS: Specifies additional VM arguments to use
• REQUIRE_VERSION: Specifies the required JVM version. This is an alternate way of setting it through the API (see Specify the required Java version)
• ENV:<environment variable name>: environment variables that you want to set for the application process
• Custom properties: all properties with names different from the previous ones

JAVAHOME property

The JAVAHOME property specifies the location of the JVM to use for the application to launch.



For example:

   JAVAHOME=L:\WRK\Java\Tools\jdk-17.0.2

JAVAFXLIB property

The JAVAFXLIB property specifies the location of the JavaFX libraries for use to the application to launch.



For example:

   JAVAFXLIB=L:\WRK\Java\Tools\javafx17\lib

MODULEPATH property

The MODULEPATH property specifies the "--module-path" argument. This is an alternate way of setting the "--module-path" through the API (see Specify the module paths).



For example:

   MODULEPATH=javafx.controls,javafx.fxml,javafx.graphics,javafx.swing,javafx.web

LIBPATH property

The LIBPATH property specifies the java.library.path argument.

VMARGS property

The VMARGS property additional VM arguments to use. The arguments must be separated by spaces.

REQUIRE_VERSION property

The REQUIRE_VERSION property specifies the required JVM version. This is an alternate way of setting it through the API (see Specify the required Java version).

Environment variables properties

The ENV:<environment variable name> properties specify environment variables that you want to set for the application process.

For example:

   ENV:HOMEPAGE=http://my.homepage.html

Custom property

All properties with names different from the previous ones are custom properties and will be added in the arguments (for those which names are allowed).

For example:

  JAVAHOME=L:\WRK\Java\Tools\jdk-17.0.2
  myKey=myValue

Start the application

The AppLauncher.start() method creates a process to start the application.

Handle errors

By default errors will throw a AppLauncherException. The kinds of errors are:

• The AppLauncher.getLaunchable() method returns null
• The AppLauncher.getConfigurationFile() method returns null
• The launchable does not exist
• The configuration file does not exist
• The JVM is not compatible with the required version
• The executable could not be launched

It is possible to specify other ways to handle errors during the class creation:

• AppLauncher.MESSAGE_ERRORS shows an error message
• AppLauncher.POPUP_ERRORS shows an popup error window