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 java.io.Serializable, 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.