The introductory chapter on the auto-update functionality discussed update downloaders that check for update installers, download them and execute them directly on demand.

Another way to organize auto-updates is to download the update installer in the background and schedule the update for execution the next time a launcher is executed. This mode requires the least involvement of the user during the update process. Depending on how much information you choose to provide to the user in your application, the only thing the user may notice is an update dialog when the application is started. No download will take place at that time, because the update installer was already downloaded during a previous session. The update will be installed without user interaction and no further user input is necessary.

The "Schedule update installation" action

install4j offers a custom application template that handles such background updates. On the "Installer->Screens & Actions" step, click on the add button, choose Add application from the popup menu and select the "Background update downloader" template.

Just like the standalone and blocking update downloader templates, the background update downloader template uses the "Check for update" action to check if an update is available and then downloads the update installer with a "Download file" action. There are two differences with respect to the other update downloader templates: First, a background update downloader has no UI and automatically downloads an update installer if available. Second, it will not execute the downloaded update installer directly, because that would disrupt the work of the user. Instead, it executes a "Schedule update installation" action to register the downloaded update installer for later execution.

In addition to the "Installer file" property that tells the action where the downloaded installer is located, the "Schedule update installation" action has a "Version" property. This is necessary so that if multiple installers have been downloaded and not yet been executed, only the most recent version is actually installed.

To avoid a situation where an installer that terminates with an error or is cancelled by the user is executed again each time when the launcher is started, the "Maximum retries on error" and "Maximum retries on cancel" properties limit the number of times that these conditions are repeated, before the installer is finally ignored and the background update downloader waits for the next version.

To mitigate external issues, such as interrupted internet connectivity, there is a minimum time between retries of a failed installation. By default, the "Retry inhibition in minutes" property is set to one day. If you would like to retry more quickly, you can reduce this value. This may be necessary during development when you want to try out the feature multiple times in succession. With the default setting, you can only try it once per day.

Executing scheduled installers

There are two options to execute an update installer that is scheduled for execution:

• Programmatic invocation

  By calling

  com.install4j.api.update.UpdateChecker.executeScheduledUpdate(...);

  you can execute the downloaded update installer programatically, usually after checking the result of

  com.install4j.api.update.UpdateChecker.isUpdateScheduled()

  to determine whether such a download has been completed. You can do that while the launcher is running or at startup. Notifying the user about this event or letting the user defer the installation is handled by your own code. For console and service launchers, this is the only option.

  The "HelloGui" class the in the "hello" sample contains a complete demonstration of how to use the API to check for updates programatically and uses a background update downloader to download and install updates.

• Automatic invocation

  For GUI launchers, you can edit the launcher, go to the "Executable info->Auto-update integration" step and select the Execute downloaded update installers at startup check box. When the GUI installer is started and a downloaded update installer has been scheduled for installation, the update installer will be executed. See the help topic on launchers for more information.

Restarting the launcher

In the standalone and blocking update downloader templates, the installer is responsible for starting a launcher after the installation with an "Execute launcher" action and you can choose whether to do that or not.

Installers that have been scheduled by the "Schedule update installation" action are always executed from a running launcher, so install4j knows which launcher to restart and does so automatically if you use the automatic auto-update integration for GUI launchers. For programmatic invocations with the

com.install4j.api.update.UpdateChecker.executeScheduledUpdate(...)

API calls, the restartLauncher argument controls whether the current launcher is restarted. If you pass false, you should start a launcher at the end of the update installer yourself.

Trouble-shooting background auto-updates

A complete background auto-update involves 5 processes that are created in chronological succession. First, code in the launcher (1) or the automatic launcher integration for an update downloader detects a new update. Then, the update downloader (2) is started which downloads the update installer and schedules it for execution. At a later point in time, the user starts the launcher again (3) and install4j detects that a scheduled update installer is available. It then executes that update installer (4) and terminates itself. At the end of the update installer, the original launcher is restarted (5).

If an error occurs at any point in this chain of processes, the auto update will fail. When setting up your project, this may be due to a misconfiguration, like a wrong URL for the updates.xml file or a failed download of the update installer. Because the log files of the update downloader and the update installer are not readily available and API calls that you use the in the launcher to check for updates or execute scheduled installers do not log at all, it is difficult to find out where the problem is located.

To debug issues during background auto-updates, you can set the system property install4j.updateLog=true for the launcher that starts the update process. If you pass it on the command line, remember to prefix it with-J, otherwise it is passed as an argument to the main class:

-J-Dinstall4j.updateLog=true

If this system property is set, install4j will create a file named update.log in the updater cache directory. The updater cache directory can be found in the following platform-dependent locations:

• Windows

  %LOCALAPPDATA%/install4j/update

• macOS

  $HOME/Library/Caches/install4j/update

• Linux/Unix

  $XDG_CACHE_HOME/install4j/update or $HOME/.cache/install4j/update if XDG_CACHE_HOME is undefined

The updater cache directory contains directories whose names are hashes of the application ID and subsequently directories with hashes of the installation path. You can look for the most recently modified directories to quickly find the application that you are testing. Inside those directories is the actual content, including the file update.log, that contains logging output that will help you determine the location as well as the cause of a failure. Other artifacts in this directory include the downloaded installers as well as lock files for the update process.

To completely start over with an auto-update process during testing, you can simply delete this directory and install4j will re-create it as necessary.