install4j can help you to include auto-update functionality to your application. Auto-updating includes two tasks: First, there must be a way to check if there is a newer version available for download. This check can be initiated by the user in various ways or the check can be triggered automatically by your application. Secondly, there must be a way to download and execute an appropriate installer for the new version.

install4j creates a special file named updates.xml in the media output directory when you build the project. This file describes the media files of the current version. If you want to use install4j's auto-update functionality, you have to upload this file to a web server. The file is then downloaded by deployed installations and delivers information about the current version. The contents of updates.xml are explained in detail in the next chapter.

Downloading and installing the new version is done with a custom installer application. install4j offers several templates for update downloaders that correspond to the different update strategies. These strategies are explained below and in the chapter on background auto-updates.

Getting started

To get basic auto-update functionality for a GUI application, you should start with a standalone update downloader that will help you validate the associated concepts. To add a standalone update downloader to your project, you can follow these instructions:

1. Upload the file updates.xml together with your media files to a directory on your web server.
2. Go to the "Installer->Auto-Update Options" step and enter the download URL for the updates.xml file. This must be the full URL for the file, like https://www.server.com/download/updates.xml and not just for the containing directory.
3. Go to the "Installer->Screens & Actions" step, click on the add button, choose Add application from the popup menu and select the "Standalone update downloader" template.
4. For the added update downloader application, enter the "Executable name" property, for example checkForUpdate.

Users can now execute the checkForUpdate executable to check whether a new update is available. Optionally, the update can also be downloaded and installed.

For testing, you can set the "URL for updates.xml" value to a file URL like file:///c:/Users/bob/myProject/media/updates.xml. Note the triple slashes after the colon that arise from the initial slash for the required root directory of the file path in addition to the two slashes that separate the protocol from the path. With a file URL, you do not need a web server and the updates.xml file does not have to be uploaded anywhere.

Installers versus archives

Generally, auto-update functionality is available for installers only. This is because the update downloader downloads the current installer and executes it to perform the actual update.

One exception is the single bundle archive for macOS where auto-updating is fully supported by the update downloader templates. On macOS, the single bundle archive is the preferred way to distribute software unlike on other platforms that prefer installers or packages that are handled by a package manager. In the update downloader template you will notice screen and action groups that deal with the macOS single bundle archives separately.

Automatic invocation of update downloaders

Typically update checks are integrated into the application. An easy way to do so for desktop applications is to start the update downloader when a particular launcher is started. Activate the "Launcher integration" tab for the update downloader application and select the "Start automatically when launcher is executed" check box.

To control how often this update check is performed, you can adjust the "Launch schedule". By default, it uses the frequency that is set it in the "Update schedule registry". To initialize the update schedule registry you can add a "Configurable form" to your installer and add an "Update schedule selector" form component to it. In the installer, the user will then get the possibility to choose the frequency of the update checks.

There are two points in the life-cycle of the launcher when the update downloader can be started: At startup or when the first window is shown. In addition, the invocation at startup can be blocking or non-blocking. This is set with the "Launch mode" drop-down on the "Launcher integration" tab.

Of course your ideas for auto-updates might be different. Maybe you do not have a GUI application and you want to perform unattended updates, or you want to notify your users about updates directly in your application. That is why the auto-update functionality has to be extremely flexible, with the unavoidable downside that its configuration is not trivial and there are a couple of concepts that you have to understand in order to be successful. The bulk of this flexibility comes from the fact that the update downloader is not a monolithic entity, but is composed of standard form components and actions that can be adjusted according to your particular requirements.

Blocking update downloaders

Some applications need to ensure that updates are applied as soon as possible or make it a requirement that the current update is applied before the application can be started. In that case, an update check has to be made at startup. If an update is found, the update installer should be downloaded and executed. The "Standalone update downloader" template is not directly suitable for this purpose, because it informs the user if no new version is available. This behavior is only appropriate if the user explicitly requested an update check.

The "Blocking update downloader" application template is what is required in this case and is intended for automatic update checks. It looks for an update in the startup sequence and terminates the update downloader if no new version is available. This means that if there is no new version available, your users will not see that a check has taken place. Only if a new version is available will the update downloader display its window and inform the user of the possibility to download the update installer.

For such an automatic check you may want to invoke the update downloader in a blocking fashion before the application is actually started. As explained in the chapter about update checks, you can use the ApplicationLauncher class to start update downloaders from your own code. When calling ApplicationLauncher.launchApplication(...) with the blocking argument set to true, the method will not return until the update installer has exited. If the user decides to run the installer on the "Finish" screen, your application will be terminated by the "Shut down calling launcher" action.

Also, this template does not offer the user a directory selection for the downloaded installer, but downloads to the user-specific download directory by default. You can change this default directory by passing the argument -VupdaterDownloadLocation=[directory] to the ApplicationLauncher.launchApplication(...) call.

Typically you will want to restart your launcher after an update has been downloaded in this way. This cannot be done in the update downloader because it has to terminate right after starting the installer in order to release locks on installed files. The task to start your launcher again falls to the installer where you can implement it with an "Execute launcher" action in the "Finish screen". If this should only happen during an update, you can set the "Condition expression" of the action to context.isUpdateInstallation().

To disable displaying information about a new version in the update downloader template, you can set the installer variable skipNewVersionAvailable to true or delete the screen named "New version available". This may be necessary because you already notify users about updates in your own application as explained in the next chapter.

Unattended auto-updates

If a user interaction is not desired, the update downloader can work in unattended mode. The execution mode of the update downloader is set through its "Default execution mode" property. By default it is set to "GUI mode". On Unix, access to the X-server is often not available, for example when you install in an SSH session. Also by default, the "Fall back to console mode on Unix" property allows the installer to switch to console mode in that case.

To generally disable GUI mode, the "Default execution mode" property can be set to "Unattended mode". This would be appropriate for a service or for a desktop application that executes the update downloader in the background. The "Unattended mode with progress dialog" is intended for desktop applications that need to show a progress UI while the update is being downloaded.

For programmatic invocations, it is possible to set the execution mode on the command line with the "-q" and "-splash" command line parameters. Programmatic invocations of update downloaders should be done with the ApplicationLauncher API that is explained in the next chapter.

In the default templates for the standalone and blocking update downloaders, the execution mode is passed on to the "Run executable or batch file" action that executes the downloaded installer. The "Set a variable" action named "Set installer arguments" analyzes the current execution mode and prepares the command line parameters. This is a good example for how the update downloader is actually a composition of actions, screens and scripts.