Migrating to install4j 11.0

In most cases, migrating to install4j 11 involves simply opening and saving your project with the install4j 11 IDE. Nevertheless, there are some considerations with respect to backwards compatibility and a couple of behavioral changes.

• Notarization now uses the App Store Connect API. Previously, install4j could only perform notarization when building on macOS using the notarytool command line tool for which an Apple ID was required in the configuration. That mode is no longer supported in install4j 11. For the App Store Connect API, you need to specify issuer ID, key ID and the downloaded private key file.
• The install4j IDE and command line compiler now require Java 21. The runtime requirement for the generated installers and launchers remains Java 8. The install4j downloads for Windows, macOS and Linux x64 contain a suitable JRE. If you download the Unix media files, you have to make sure to install Java 21 on your build server first.
• The list of releases from JDK providers is now requested from URLs below https://www.ej-technologies.com/jreprovider/. This allows us to respond to API changes without breaking older versions of install4j and to introduce fixups for erroneous releases from JDK providers. The actual downloads are still performed from the URLs that are published by the JDK providers. If you have added exceptions to your firewalls, you need to take this into account.

• As announced in the 10.x series, the macOS single bundle installer has been removed. The macOS single bundle archive should be used as a replacement. However, the macOS single bundle installer media files are not migrated automatically because it may take some consideration as to which actions you would like to run when the launcher is started for the first time.

  On the "Launcher" tab of the media file wizard, you can select a "setup application" from the list of custom installer applications that are defined in the "Installer->Screens & Actions" step. In that custom installer application you can link to screens and actions, or screen groups and action groups to avoid duplicating configuration.

  This removal was necessary due to signature and notarization requirements, which made the bundle directory unmodifiable at runtime. This installer type has been non-functional in recent macOS releases.

• The "Sign all launchers" option for macOS media files has been removed as launchers are now always signed to comply with notarization requirements.
• For the "Add VM options" and the "Modify classpath" actions, the property "Target file on macOS" was removed. It offered an option to write the .vmoptions file into the application bundle, which is no longer possible due to current notarization requirements. These files are now always created next to the application bundle.

• install4j 11 has removed support for dynamic JRE downloads and shared JRE installations. Modern JREs that are linked to a minimum required module set do not match with these features and lead to various problems at runtime. Also, the concept of pre-installed JREs that could be found is no longer a mainstream concept.

  Instead, we have expanded support for the use case where the initial download contains the JRE and updates should not include a JRE for small downloads and fast installations:

  1. The new "Previous installations" search sequence entry type on the "General Settings->JRE Bundles->Search Sequence" step helps you to reuse the installed JRE in update installers. Only installations with the same application ID are considered for the search sequence entry type.
  2. The "Install files" action now copies a JDK from a different installation directory if it was found by the "Previous installations" search sequence entry. This prevents issues that would arise if the other installation is uninstalled.
  3. Update downloaders can now make decisions based on the JRE version of the update installer by inspecting com.install4j.api.update.UpdateDescriptorEntry#getJreMinVersion and #getJreMaxVersion. If the JRE version matches the currently used JRE, you can download a media file without a bundled JRE, otherwise a media file with a JRE should be downloaded.
• The "Open PDF viewer" action and the "PDF display" form component now require at least Java 11.
• Custom names of screens, actions and form components are no longer written to the runtime configuration, and only bean IDs are annotated into stack traces. These names were not usable programmatically and could expose unintended text. When inspecting stack traces, use the "Search ID" feature on the "Installer->Screens & actions" step to locate the corresponding beans.
• There are breaking changes in the Gradle plugin configuration. All properties are now typed correctly and use the Gradle provider mechanism. This was necessary to enable compatibility with the configuration cache where extensions and projects cannot be accessed at execution time. Also, the deprecated variableFile property was removed.
• Keyboard shortcut changes in generated installers on macOS: To move to the previous or next installer screen, use Ctrl+Option+Left Arrow and Ctrl+Option+Right Arrow. The previous keyboard shortcuts did not work in text fields. On Windows and Linux, the shortcuts remain Ctrl+Left Arrow and Ctrl-Right Arrow respectively.
• The "Installation type" screen now behaves differently if the selected installation type is user-configurable and the user does not change the installation type in an upgrade installer. In this case, the selected components retain their previous installation state, and are not reset to the default set of the installation type.
• For generated GUI launchers for which the "Uses SWT or QT" option has been selected on the "Executable info" step of the launcher wizard, installer applications - such as the update downloader - can only be started in a new process. This is necessary to avoid deadlocks. For automatic launcher integrations this is enforced automatically regardless of the settings on the "Launcher Integrations" tab of the custom installer application. Programmatic invocation through ApplicationLauncher.launchApplicationInProcess will throw a IllegalStateException in this case. Use ApplicationLauncher.launchApplication instead.