Many applications have a component that has to run in the background without user interaction. On Windows, this is called a "service", on Unix a "daemon", in install4j the term "service" is used exclusively. install4j can generate service launchers for your application on all supported platforms. On Windows, managing services is a particularly demanding area and so other service executables that have not been generated by install4j are supported as well.

Generated service launchers

A service launcher will be generated if the selected executable type in the "Executable" step of the launcher wizard is set to "Service".

There are no special requirements and interfaces that have to be used by your code. When the service is started, the main method of the configured main class will be called just like for GUI or console launchers. Also, there is no special "shutdown" interface that is notified when the service is stopped. To perform cleanup, use the Runtime.addShutdownHook() method to register a thread that will be executed just before the JVM is terminated.

If you define a service launcher, it will not run automatically after the installation. A generated service launcher has to be installed and started explicitly. To do that, you have to add the following actions to the installer:

• Install a service

  This action registers a service with the system, so that it can be executed automatically when the computer is started. By default, the name of the installed service is the launcher name that is configured in the launcher section of the install4j IDE. In order to change the service name you have to rename the launcher.

  On Windows, if you require a user-configurable service name or if you wish to install the service multiple times, use the method for external service launchers as described below.

• Start a service

  Installing a service does not start it immediately and you have to add this separate action to actually run the service.

When the "Install Files" action runs and a previous installation is being updated, any running services that are associated with the same executables are stopped.

Windows user accounts

On Windows, you can configure the user account that is used for running the service. There are a few well-known user accounts, like "Local System" (the default) or "Local Service" that you can choose directly in the configuration of this action.

In some cases, you might want to create a separate user to run a service. install4j offers API support for creating new user accounts with the com.install4j.api.windows.WinUser class. If you would like to query the user for details on the user account, it is possible to do that without using the API. On a configurable form, add a "Windows user selector" component and select the "Show 'Create User' button" property.

The SID of the created or selected user is saved to the configured variable, say "serviceUser".

You also have to query the user for the password of the account. For that purpose, add a "Password field" form component, set its variable to "servicePassword" and choose that form component in the "Password form component" property of the user selector form component.

In the "Install a service" action, you can then choose Other in the "Account" property and enter ${installer:serviceUser} in the nested "Account name or SID" property as well as ${installer:servicePassword} in the nested "Password" property.

Command line options of generated service launchers

Under some circumstances, services must be able to be installed and started manually from the command line. While this is required functionality on Unix, service executables on Windows usually offer no command line functionality. Instead, it is expected that there is a special program that installs and uninstalls the service.

This task is handled by the "Install a service" and "Uninstall a service" actions in install4j. In addition, you can start and stop services in the Windows service manager. install4j includes the "Start a service" and "Stop a service" actions to do this programatically in the installer.

To improve usability, install4j adds Unix-like arguments to the generated service launchers on Windows as well. For Unix and Windows service executables, the usual

my_service start   | my_service.exe /start
my_service stop    | my_service.exe /stop
my_service status  | my_service.exe /status
my_service restart | my_service.exe /restart

options for daemon start scripts are supported. The stop command waits for the service to shut down. The exit code of the status command is 0 when the service was running, 3 when it was not running and and 1 when the state cannot be determined, for example when it is not installed on Windows.

For debugging purposes, you may want to run the executable on the command line without starting it as a background service. This can be done with the run parameter.

my_service run | my_service.exe /run

In that case, all output will be printed on the terminal. If you want to keep the redirection settings, use the run-redirect parameter instead.

To install or uninstall a service on Windows from the command line, call

my_service.exe /install
my_service.exe /uninstall

In this way, your service is always started when Windows is booted. To prevent the automatic startup of your service, call

my_service.exe /install-demand

instead. As a second parameter after the /install parameter, you can optionally pass a service name. In that way you can

• install a service with a different service name than the default name.
• Use the same service executable to start multiple services with different names. To distinguish several running service instances at runtime, you can query the system property exe4j.launchName for the service name. Note that you also have to pass the same service name as the second parameter if you use the /start, /restart, /status /stop and /uninstall parameters.

On Windows, all command line switches also work with a prefixed dash instead of a slash, like -uninstall or with two prefixed dashes, like --uninstall.

External service launchers on Windows

When deploying third-party software, you may want to install and start services that were not generated by install4j. Both the "Install a service" action as well as the "Start a service" action provide a way to select other service executables. If you choose [Other service executable] in the drop-down list of the "Service" property, two new nested properties are shown: In the "Executable" property you set the path of the external service executable and the "Name" property allows you to specify the name of the installed service.

Note that this action does not provide "service wrapper" functionality for regular executables. The selected executable has to be a service executable, otherwise the action will not work.