Generated launchers in install4j have some features that you can interact with from your own code. The corresponding API is contained in the com.install4j.api.launcher package. This chapter gives an overview of the most important use case, the detailed documentation is contained in the Javadoc.

install4j's launcher API is automatically available to an application deployed with install4j. For compiling your application, you have to add the runtime classes to your class path. You can learn how to set up a dependency in build systems in the API overview.

Receiving Startup Events in Single Instance Mode

If you have enabled the single instance mode for your executable, the application can only be started once. For a GUI application, the existing application window is brought to front when a user executes the launcher another time.

The scope of the single instance check can be per-user or globally across all users. For the per-user scope, the "Per session on Windows" setting controls whether multiple RDP sessions for the same user on Windows can support one instance per session or only one instance across all sessions.

In single instance mode, you may want to receive notifications about multiple startups together with the command line parameters. If you have associated your executable with a file extension, you will likely want to handle multiple invocations in the same instance of your application. Alternatively, you might want to perform some action when another startup occurs.

To do that, create a class that implements the com.install4j.api.launcher.StartupNotification.Listener interface and register it with com.install4j.api.launcher.StartupNotification.registerStartupListener(listener). Your listener will then be notified when another startup occurs. See the Javadoc for more information.

Startup notifications only work when the same user starts the executable again. With the global scope, a startup of a different user will not produce a startup notification. On macOS, this setting only applies to console launchers, for GUI launchers, the macOS operating system enforces single instance mode if the user starts and application bundle from the Finder. With the /usr/bin/open command line tool and the -n option, the user can circumvent single instance mode.

Controlling the Splash Screen from your Application

If you have enabled a splash screen for a launcher, you will want to hide it once the application startup is finished. The splash screen will be hidden automatically as soon as your application opens the first AWT, JavaFX or SWT window. See the Javadoc for more information.

However, you might want to hide the splash screen programmatically by calling com.install4j.api.launcher.SplashScreen.hide() or update the contents of the status text line on the splash screen with com.install4j.api.launcher.SplashScreen.writeMessage(...) during the startup phase to provide more extensive feedback to your users. Also, if the UI subsystem is not loaded by the system class loader, install4j cannot automatically detect displayed windows and you have to hide the splash screen automatically. For example, this is the case for eclipse RCP applications.

Reading compiler and installer variables from response files

All installer variables that are registered for response files will be saved to the file .install4j/response.varfile just before the installer exits. This includes all variables that are bound to form components and variables for which you have called context.registerResponseFileVariable(variableName).

Some of these variables will contain user input that you need at runtime. You can use the com.install4j.api.launcher.Variables class to access the variable values. The variable values from the response file are fixed, and its backing file is usually not writable by the user. If you want to update the variable values at runtime, you can save variables to the preference store with a "Save installer variables to the preference store" action. The com.install4j.api.launcher.Variables class has methods for reading and saving these variables from the preference store.

In addition, all compiler variable values can be retrieved at runtime. See the Javadoc for detailed information.

Starting installer applications from your launchers

Installer applications like update downloaders are separate executables and can be started manually by the user. Most often, however, they will be launched by one of the generated launchers. install4j offers a configurable launcher integration mechanism that automatically executes an installer application when a launcher is started. For greater flexibility, you may want to execute the installer application from your code programmatically. On the "Installer->Screens & Actions" step, when an installer application is selected, the integration wizard on the "Launcher integration" tab produces code that uses the com.install4j.api.launcher.ApplicationLauncher class.

There are two ways to start installer applications: In-process and out-of-process. For an in-process invocation, the installer application will use the look and feel of your JVM. The AWT subsystem will be initialized which may be undesirable if you use a different UI toolkit like JavaFX. For greater isolation, out-of-process invocations are recommended. The ApplicationLauncher API offers both options. In both cases you can supply a callback that is notified when the installer application exits or if a "Shutdown calling launcher" action in the installer application request a shutdown of the launcher.

In addition, the ApplicationLauncher class provides a mechanism to run an installer application the first time a launcher from an archive installation is started. Archives do not have an installer, but you may still want to run some install4j actions, for example, to configure a file association. With the ApplicationLauncher.isNewArchiveInstallation() method you can check at startup if this is the first time that the launcher is being executed.