API For Generated Launchers
Generated launchers in install4j have some features that you can interact with from your own code.
The corresponding API is contained in the
This chapter gives an overview of the most important use case, the detailed documentation is contained in the
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
interface and register it with
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
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
or update the contents of the status text line on the splash screen with
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
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 by 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
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
ApplicationLauncher.isNewArchiveInstallation() method you can check at startup if this is
the first time that the launcher is being executed.