Category: Migration

Migrating to install4j 7

In nearly all cases, migrating to install4j 7 just means opening and saving your project with the install4j 7 IDE. Nevertheless, there are some considerations with respect to backwards compatibility and a couple of behavioral changes.

  • The minimum supported Java version is now Java 7 up from Java 6 for install4j 6. This also means that the old Java 6 Apple JRE is no longer available as a separate type on the Bundled “JRE” step of the macOS media wizard. The launcher runtime still supports Java 6 and you can set the compiler variable sys.ext.forceMinJavaVersion to true in order to allow “1.6” as a minimum version. Note that no classes in the API can be called from Java 6.
  • The “native splash screen” feature for Windows has been removed. This went back to the pre-Java 6 days when Java did not offer splash screen functionality and was missing several important features. If you had this feature selected for one of your launchers, it now uses the regular Java splash screen
  • When a rollback terminates at a rollback barrier, the exit code of an installer application is now 0. To restore the old exit code of 1, you can set the “Exit code” child property of the “Rollback barrier” property to 1
  • In the “Key validation expression” script property of text components, the “keyCode” parameter has been removed. It was always 0 before and did not serve a useful purpose.
  • If you develop your own screens with the API, the methods isShowIndex, hasTitlePanel, hasDefaultInsets and hasDefaultButtons have been removed from the interface com.install4j.api.screens.Screen and so your existing implementation of these methods will no longer be called by install4j. This functionality is now covered by styles which are much more flexible than the previous limited styling capabilities.
  • In the API, methods with Object[] arguments for variable parameter lists have been converted to varargs. This should not cause source or binary incompatibilities but may show warnings in your code if you call such methods.
  • The “Create a quick launch icon” action has been removed with no replacement. The last OS where it had any effect was Windows Vista.
  • If you have not set a maximum Java version, and do not use a bundled JRE, any installed Java 9 JRE will be used. Java 9 has backward compatibility issues that may prevent your application from working unless you explicitly support it. Consider limiting the maximum Java version to “1.8” in that case.
  • If the “Request privileges” action fails, an installation directory in the user home directory is set. To restore the old behavior of keeping the default installation directory deselect the “Fall back to user specific installation directory” property on the “Request privileges” action.
  • With install4j 7, you cannot use the deprecated in the macOS EAWT API anymore, you have to use the new API methods, for example

    Application.getApplication().setQuitHandler((quitEvent, quitResponse) -> {
    // TODO add your code

    for the quit handler.

If you notice anything else, please let us know!

Migrating to install4j 6

In nearly all cases, migrating to install4j 6 just means opening and saving your project with the install4j 6 IDE. Nevertheless, there are some considerations with respect to backwards compatibility and a couple of behavioral changes.

  • The minimum Java version for launchers is now Java 6. If your launchers must run with Java 1.4 or Java 5, you have to stick with install4j 5.
  • The minimum Java version for the install4j IDE and the compiler is now Java 7. If your build machine only has Java 6 installed, you have to install a Java 7 JRE. On Windows and Mac OS X, Java 7 JREs are bundled in the install4j downloads.
  • The install4j API has been generified and old-style enums have been converted to language enums. Theses changes are binary and source compatible. The only exception is that enums do no longer extend com.install4j.api.SerializableEnum. In the unlikely case that you use this class in your custom code, you will have to replace it with the actual enum class.
  • Installer variables loaded by the “Load response file” action or the -varfile command line parameter are now automatically registered as response file variables. The eliminates problems with fast-path upgrade installations where response file variables would be lost if their form components were not be shown. If this change impacts on your logic, the “Load response file” action now has a “Register variables for response file” property that you can deselect to revert to the old behavior.
  • By default, the “Load response file” action will no longer overwrite installer variables that have been set explicitly on the command line with the -Vvariable=value option. This is the intuitive behavior and makes installer variables more flexible. If this change impacts on your logic, the new “Overwrite strategy” property of the “Load response file” action can be set to “Do not overwrite existing”.
  • Mac OS X archives are now generated in DMG format. This means that the generated media file name will change between install4j 5 and install4j 6 and you have to adjust download links on your web site. If you would like to keep the .tgz format, you can change the corresponding option on the “Installer options” step of the media wizard.
  • Invisible form components are no longer validated. A validation error would leave the user with no clue what to do, so this was really a mistake in previous versions. However, bound installer variables are set during the validation phase and that will no longer happen for invisible components. If you rely on the installer variables to be defined, you should predefine them in the “Installer variables” section of the installer or custom installer application.
  • Several installer variables that were previously only defined on Windows are now defined on multiple platforms. New cross-platform installer variables are “sys.desktopDir” and “sys.docsDir”. The installer variables “sys.appDataDir”, “sys.localAppdataDir”, “sys.docsDir”, “sys.fontsDir” and “sys.programsDir” are now also defined on Mac OS X. If your code checks if any of these installer variables is null, it may no longer work correctly.
  • The “Reboot computer” action and Context#triggerReboot now work on Mac OS X as well. If you rely on the previous behavior of not doing anything on Mac OS X, this may not be what you want. In that case, you have to add platform-specific checks in your project.
  • The ICNS icon for Mac OS X launchers is now generated from cross-platform images. If you previously had no ICNS icon defined but the “Add icon to launcher” check box was selected, the maximum resolution of your icon files might be too low. You need at least a 128×128 image for the icon to look good on Mac OS X. The old default ICNS icon is still available under resource/macos/app.icns, so you can specify it explicitly to restore the old behavior.
  • The name of the uninstaller on Mac OS X has changed if your project is localized. Previously the file name of the uninstaller application bundle was set to the localized name. In install4j 6, the file name is always set in the principle language and the localization is provided by the application bundle. You will see the localized name in the Finder, but not in the terminal.

If you notice anything else, please let us know!

    Migrating to install4j 5.1

    The following new features in the install4j 5.1 require consideration when migrating from 5.0:

    New architecture for elevated privileges

    install4j 5.1 introduces a new architecture for elevated privileges. Under some circumstances this can create backwards compatibility problems with your existing projects that are discussed below.

    Prior to install4j 5.1, the the “Request privileges” action could restart the entire installer process and run the installer GUI and all the actions with elevated privileges. This was the default setting on Windows and also available on Mac OS X. The unelevated process was kept around only for starting launchers and other executables without privileges. On Mac OS X, the default mode for the “Request privileges” action was to start an elevated helper process that was used internally by some actions – such as the service actions. The strategy of running the GUI without elevated privileges is a lot better, but our helper process had very limited capabilities and so it could not be made the default on Windows.

    Enter install4j 5.1: We have now removed the “restart” and beefed up the elevated helper process considerably. Single actions can now be executed in the elevated helper process. To this end, we have added an “Action elevation type” property to all actions in the install4j IDE. Unless the action declares a different default value, it is set to “Inherit from parent”. The “Action elevation type” is also configurable on screens, installer applications, screen groups and action groups, and determines the default value for the contained actions.

    If an action is set to be executed with maximum available privileges and an elevated helper process has been started by the “Request privileges” action, the action is serialized to the elevated helper process, executed there and then serialized back to the unelevated process. In the elevated helper process, it has access to all installer variables and it can interact with the GUI through the methods in the com.install4j.api.Util class. Elevated actions in console installers can use all methods in the provided com.install4j.api.screens.Console object to interact with the user.

    If you are just using standard actions, migrating to install4j 5.1 should not break anything. If you use custom code, the two-process architecture and the changed default privileges might impact your installer. Here are the points that you should look at:

    • Using static state in elevated actions may have unintended consequences, since static state is not synchronized between the two processes. Only use installer variables for saving state.
    • Elevated actions must be serializable. The base interface for actions now extends, but all contained objects must be serializable as well, otherwise a fatal error will occur.
    • Installer variable values should be serializable. If you place a non-serializable value into an installer variable, you will not be able to use it in elevated actions.
    • If your action previously assumed that it would have full privileges, you have to set its “Action elevation type” to “Elevate to maximum available privileges” manually. For example, a “Run script” action that modifies a file with your own code may not work on a file in the installation directory unless you elevate the action. For custom actions, you can call setFullPrivilegesRequired or setDefaultActionElevationType in your action bean info in order to automatically set the correct elevation type in the install4j IDE when the action is inserted.
    • Some methods in the API do not work in the elevated helper process. They have been marked to throw NotSupportedInElevationException in the API javadoc. Mainly this concerns methods in the context that change the control flow (i.e. jump to another screen) or methods that modify the GUI. If your action needs to use these methods while at the same time requiring elevation, you can always use context.runElevated(...) to push a piece of code to the elevated helper process.

     The key advantages of the new architecture are:

    • Unified privileges architecture for Windows and Mac OS X
    • No more problems due to user change on authentication
    • Privileges can reasonably be requested at any point in the installer, not only at the beginning
    • Better desktop integration of the installer GUI, for example for drag and drop

    Support for OpenJDK on Mac OS X 

    OpenJDK is the way forward for Java applications on Mac OS X. However, the following points need your attention:

    • It is not possible to deliver an installer or a single bundle archive that support both the old Apple JRE as well as OpenJDK. The stubs are different and you choose either option in the media wizard. Old projects will keep the Apple JRE option, so nothing will change by default
    • JRE bundling on Mac OS X is only supported for Open JDK
    • The minimum Java version for OpenJDK is Java 7 and the minimum Mac OS X version is 10.7.3. So you can currently target only newer systems and only if your application supports Java 7.

    Code signing for Windows and Mac OS X

    Code signing on Windows and Mac OS X is now implemented in pure Java code which works on any supported platform. Previously, install4j only offered a hook for inserting an external code signing tool for Windows which would be executed for each launcher and installer application. This functionality is still available for Windows media files and is now called “Executable processing”. So your existing solution for code signing will still work and there is no immediate need for action.

    However, if you have .pvk and .spc files for your code signing certificate, you can enter them on the General Settings->Code Signing tab and enable Windows code signing there. You then have to remove the external code signing command on the “Executable processing” step of the media wizard.

      Migrating to install4j 5

      Those who made the move from install4j 3 to install4j 4 will remember that it was a lot of work to migrate custom code, because most core concepts had been changed.
      Not so with install4j 5: Your old project file will be transformed to the new format and most projects will work right away, without the need for any manual work. If you are interested in the changes in the project file structure, please see the file config/transforms/transform_3.xsl in your install4j installation directory.

      However, there are a number of cases where old functionality has been replaced, behavior has been changed or the API has been fixed. In those cases backwards incompatibilities can arise. This post intends to present an exhaustive list of them:

      • We have removed support for Java 1.3. This allows us to use the standard XML beans decoder and XML parser in the JRE. Java 1.4 is still supported.
      • The “Require admin user” action and the “Request admin privileges on Windows Vista” option on the “Installer options” step of the Windows media wizard have been removed. They have been replaced with a much more capable “Request privileges” action. The “Request privileges” action is now added to all projects by default and will be inserted into the “Startup” sequence of old projects as well. If you had a “Require admin user” action in your project, the “failure” properties will all be selected (they are otherwise not selected by default). If you had a condition expression on the “Require admin user” action, it will be lost. Especially platform-dependent configuration is now possible directly in the “Request privileges” action.
      • On the Installer->Custom Code tab, the old “Use installed JAR files if possible” option has been removed. Previously, the installer performed a two-phase initialization of screens and actions, before and after the “Install Files” action, so you could use custom code from installed JAR files. The main reason for that option was to prevent double packaging of JAR files, once for the installer and once for the launcher. In install4j 5, if entries in the custom code are also present in the distribution tree, they will be moved to the final destination by the “Install Files” action, and the custom code will automatically include the installed files in custom installer applications and the uninstaller. This change significantly improves custom code handling, because double packaging is always prevented and you can use such custom code before the “Install Files” action is executed.
        However, if your code depends on the location of the JAR file, this can be a breaking change and you have to change your custom code. In that case, the new Screen#isCreatedLazily() method and the optional Context#initializeLazilyCreatedScreens() method will help you to move the initialization of the custom screen after the “Install Files” action while the Context#addToClassPath(File) method allows you to add installed JAR files to the custom code for dependencies that only work in the installed location.
      • The compiler variable “sys.platform” now resolves to “windows-x64” for 64 bit media files. Previously, it always resolved to “windows”. This variable is used in the standard media file name pattern on the General Settings->Media File Options tab, so your 64-bit Windows media files will now be named differently if you have not changed or overridden the media file name.
      • There was a typo in the system message key name “LocateBrowerExecutable”. In the unlikely event that you used that key explicitly in your project before, it will lead to a runtime exception.
      • A few installer variable names have changed to make naming more consistent. The old names will be replaced automatically with the new names when you open your old project file for the first time. However, if you use them outside of the install4j IDE, for example in custom code, you will have to change them. The replacements are:
        • sys.mediaDirectory -> sys.mediaDir
        • sys.installerDirectory -> sys.installerDir
        • -> sys.programGroupName
        • sys.programGroup.linkDir -> sys.symlinkDir
        • sys.programGroup.allUsers -> sys.programGroupAllUsers

      • (Updated on 2010-07-15) The “Services” screen has been removed. The reason is that since the service actions now support arbitrary service executables (not only those generated by install4j), it would be difficult for us to present a list like in 4.x. Also, we feel that this is really a technical question that users should not have to answer. If needed, you can create a question with a configurable form. The “Hello world” project has such a screen.

      Other breaking changes only concern the API:

      • The method ApplicationRegistry.ApplicationInfo#getProgramGroup() has been removed from the API. It has been obsolete since 4.2, when the “Load reponse file” action was added. In the GUI, the “Suggest previous program group” option on the Installer->Update Options tab has been removed as well.
      • Several typos in method names have been fixed. Fortunately, typos were only discovered for the rarely used methods Context#isErrorOccurred(), Context#setErrorOccurred(boolean) and
        FormComponent#initialize(). If you are affected by the first two changes, the build will fail. If you derive a form component from AbstractFormComponent, the third change concerns a method that is overridden and would not cause a compilation error, so we have added a method for backwards compatibility in that case.
      • Several methods in the Install4jBeanInfo and Install4JPropertyDescriptor classes had their return values changed from void to the class itself in order to facilitate usages in builder patterns. You just have to recompile your code against the new runtime library, no source code changes are required.
      • The Context#getWizardContext() does not return null in unattended or console mode anymore. Instead, a dummy wizard context is returned that does nothing when its methods are invoked. If you use Context#getWizardContext() to check for those installer modes, you have to change your code and use Context#isUnattended()and Context#isConsole()instead.
      • The “installerAndUninstaller” argument from ActionBeanInfo#setAssociatedStartupAction(String) was removed because the new ActionBeanInfo#setComplementaryStartupLink(boolean) makes more sense.

      That’s it! Most of these changes are only breaking changes for corner cases and even then it should be easy to fix them. If you notice any other breaking changes, please let us know, so we can add them to this list.