Introduction

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 and install4j service launchers for your own application. 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 for your code, when the service is started, the main method of the configured main class will be called as for GUI or console launchers. Also, there is no special "shutdown" interface for the service to be notified when the service is stopped. To do any cleanup, use the Runtime.addShutdownHook() method to register a thread that will be executed before the JVM is terminated.

A generated service launcher has to be installed and started, otherwise it will not run. These actions are not performed by default. You have to add the following actions to the installer:

• Install a service
  

  Installs a service, so that it can be started 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. You can select the launcher and rename in order to change the service name. If you require a user-configurable service name or if you wish to install the service multiple times, please use the method for external service launchers on Windows as described below. If you treat the service launcher as an external service, you can specify a service name in the install4j IDE.

  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.

  

• Start a service
  Installing a service does not start it. You need this action to actually execute your code.

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.

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, on Windows service executables usually offer no command line functionality. On Windows it is expected that there is a special program that installs an uninstalls the service. This is done by the "Install a service" and "Uninstall a service" actions in install4j. In addition, one can start and stop services in the Windows service manager. install4j offers "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 service executables, the usual start, stop and status of daemon start script arguments are available for the generated start script. The stop command waits for the service to shut down. The exit code of the status command is 0 when the service is running and 3 when it is not running.

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. 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. On Windows, the corresponding parameters are /run and /run-redirect.

To install a service on Windows from the command line, pass /install to the generated service executable. In this way, your service is always started when Windows is booted. To prevent the automatic startup of your service when the computer is booted, pass the argument /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 /uninstall, /start and /stop parameters explained below.

Generated windows services are always uninstalled by passing /uninstall to the generated service executable. To start or stop the service, the /start /stop and /restart options are available. In addition, the /status argument shows if the service is already running. The exit code of the status command is 0 when the service is running, 3 when it is not running and 1 when the state cannot be determined (for example when it is not installed on Windows). All command line switches also work with a prefixed dash instead of a slash (like -uninstall) or two prefixed dashes (like --uninstall).

External Service Launchers On Windows

As part of 3rd 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. In the drop-down list of the "Service" property, if you choose [Other service executable] two new nested properties are shown: The "Executable" property allows you to specify the external service executable. 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. The "Name" property allows you to specify the name of the installed service.