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
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.
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:
Upload the file
updates.xmltogether with your media files to a directory on your web server.
Go to the "Installer->Auto-Update Options" step and enter the download URL for the
updates.xmlfile. This must be the full URL for the file, like
https://www.server.com/download/updates.xmland not just for the containing directory.
- 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.
For the added update downloader application, enter the "Executable name" property, for example
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
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
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
To disable displaying information about a new version in the update downloader template, you can set the
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.
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.