Mixed Installation Mode Using Variable Defaults

Introduction

Before IzPack 5.0.10, for automated installations, the only reliable way had been providing an auto-install.xml as parameter to the installer.

The main disadantage of this method has been the recommendation of regenerating this file for each new installer version and repeat the installation session manually each time, before the auto-install.xml could be considered compatible against the dedicated installer.

Especially those people having a framework on top of IzPack to build installers for similar applications, which share one and the same environment (database, application servers etc.) frequently use one the same parameters (IzPack variable names) repeatedly shared across installers based on this higher level framework.
For this use case, auto-install.xml and the legacy automated mode is sometimes hardly handleable, because there is the need of generating a new auto-install.xml for each installer version and use (test) case, which results in a big number of different auto-install.xml XML files, which must be permanently maintained.

The main intention of the installation mode described here is to provide default values for variables and automated installers from an external file, which override default variable values for all installation modes, GUI, console and automated installations. Built-in defaults should act as fallback, if there are no default values in the provided external file.

In the simplest way this can be a property file providing key-value pairs, which should override also built-in defaults. In addition to property files, this file is encoded in UTF-8 and can handle special include tags to make it possible to use cascaded files.

Before 5.0.10, this behavior has been partly implemented with the -options option, but just for the console installer mode.

One use case the new installation mode might be some kind of demo mode of an installer with prepared values for instance for the target path and a database connection, to make a presenter be able just to show mask contents without modifying them and thus avoid typos, and pressing just the Next key on each installer page. This can be good for instance to teach someone how your (complex) installer is used in a pre-tested target system and scenario.

The main advantages of such a solution are:

• dependency on a minimal set of parameters
• sharing of default input parameters between different installers based on the same set of IzPack variables
• reusability of the default input file across several versions, even if the panels have been restructured, renamed etc.
• possibility of using input parameters for all three installation modes - GUI, console and auto

Input file format

The input file used here is almost the same like a property file, thus containing key-value pairs.

The differences to properties files are:

• The default encoding is UTF-8 (instead of ISO-8859-1 in Java properties files).
• IzPack variables can be used and are automatically resolved.
• Special include tags can be used to arrange files in cascades.

Lines with comments start on the # character.

Files can be included by using the following syntax:

• <some_uri>
  The file indicated by the URI must exist, otherwise the installer aborts.
• <?some_uri>
  The file indicated by the URI is read if it exists. If it doesn't exist the installer ignores this tag.

The term some_uri must be a valid URI as recognized by the JRE. Examples of valid URIs are:

• file:/home/foo/bar.defaults
• file:${APP_NAME}.defaults
• jar:file:defaults.zip!/${APP_NAME}.defaults
  Read the defaults from within a JAR or ZIP file (including the installer jar itself).

Example:

Provided we have several applications sharing one and the same database server, application server and JRE, we can define a cascaded structure of files:

root.dir=/usr/local/BigFatCompany

#Application server
appsrv.host=localhost
appsrv.port=8080
appsrv.username=admin
appsrv.password=whoKnows?

#Database
db.family=oracle
db.host=demodb
db.port=1521
db.sid=ALL_APPS_INSTANCE
db.admin.user=system
db.admin.password=whoCares?

#Java runtime
jre.path=/usr/java/jdk1.8.0_92/jre

<file:${APP_NAME}.defaults>

Provided that ${APP_NAME} from the installer itself resolves to MyFirstApp we can optionally use an included file:

INSTALL_PATH=${root.dir}/FirstApp

db.schema=firstapp
db.user=user1
db.password=pass1

Enhancements since IzPack 5.1.0:

There is a special comment block parsed for defining value mappers directly in one and the same file.

All comments between the special comment tags BEGIN MAP and END MAP are interpreted as value mapper classes, for changing the resulting value the installer uses as effective variable override instead of the plain one from the file. The number of mappers between these two lines is unlimited, and if there are more than one, the will be applied like a filter chain - the output of the previous one is used as input for the next one.

# BEGIN MAP
# com.my_company.installer.data.InternalPasswordMapper
# END MAP
db.password=D5%3gh/p?gg

The according mappers must implement the com.izforge.izpack.api.data.VariableMapper interface.

Scope of defaults

There is a simple behavior in the scope of keys defined in the input file described before - the last definition in the sequence of reading in a set of defaults files "wins".

This means especially that you can override one and the same parameter key in an included input file in case you add the include definition at the end. This is very useful if you want to define a global defaults file for a set of installers, and want to override a certain value (for instance the target installation directory) in an imported defaults file just for a dedicated application. You can make this highly dynamical because the include definition supports variable substitution, see the above example <file:${APP_NAME}.defaults>.

Usage

For passing default overrides to the installer there is always one file path argument given to the installer. To cascade more than one file, include a set of plain files or files extracted from a ZIP/JAR (described above).

To use the new installation mode the following syntax can be used:

java -jar <installer_jar_file> -defaults-file <defaults_file> [-auto]

An alternative of passing the defaults file to the installer is naming the defaults file like the installer jar file, but replacing the suffix (for example .jar) by the suffix .defaults. If this file is in the same directory like the installer jar file and the -defaults-file parameter isn't used, it is automatically used here.

The optional parameter -auto indicates to run the installer in unattended console mode.

If used without -auto, the according interactive, either GUI or console mode is used, and panels showing user input fields use the default values found in the file, if they can be found there. An exception is in the UserInputPanel, if the set attribute is used on a user input fields, which always overrides the initial value shown in the according field.