Configuration Install Actions - ConfigurationInstallerListener
...
- option and property files
- INI files
- XML files
- Windows registry entries.
ConfigurationListener is useful for software updates and merges option (properties), INI and XML files from a previous installation to those files with the same path coming with a new version of your software. It does a three-way merge - patching an original file against a new file resulting in a target file. For using in-place patches you must ensure the previously installed files are automatically renamed when installing the new files coming with an update installer, before ConfigurationListener starts. This can be achieved by using the overrideRenameTo attribute for installed files or file sets, see Packs.
Configuration actions are defined in an IzPack resource ConfigurationActionsSpec.xml, which has to be necessarily defined when the ConfigurationInstallerListener is used.
Configuration actions can be only used during installation, not for reverting configurations when uninstalling.
...
Attribute | Description | Required | Allowed Values |
|---|---|---|---|
type | The file type to handle. | yes | "options" | "ini" | "xml" | "registry" |
toFile | The target file to write the patch result to. This is equal to the file a patch should be apllied applied against, if the attribute originalFile is not set. | yes | absolute or relative (against $INSTALL_PATH) path denoting a file |
toKey | The registry root key to patch to, provided that type = "registry". | yes | registry path |
patchFile | The file to patch from. This is the source file with the full original contents, which might be preserved, overridden etc. according to the patch rules defined in other attributes. Nested fileset elements can be used instead to patch from a couple of files to the target. | no | absolute or relative (against $INSTALL_PATH) path denoting a file |
originalFile | The file to patch against, if it should be different than the final target file. This might be useful on updates, if the previous file is at a different place than the resulting one; in this case the patch can be applied against the old one and the result written to the file defined by the toFile attribute (thus to the new location). This attribute has only effect if the patchFile attribute is set. | no | absolute or relative (against $INSTALL_PATH) path denoting a file |
fromKey | The registry root key to patch to, provided that type = "registry". | yes | registry path |
cleanup | Whether to remove the patch file after the operation which don't act also as target file with the same name. This attribute has only effect if the patchFile attribute is set. | no | "true" | "false" |
create | Whether to create the target file when it doesn't already exist | no | "true" | "false" |
keepOldKeys | Whether to generally preserve equal entries but not necessarily their values from the patch configuration file, if they can be found. This means if keepOldKeys="true" and the entry occurs in the old configuration and also in the new configuration, the new configuration entry is left and the value is set according to the keepOldValues setting, otherwise if the configuration entry found in an old configuration is not found in a new configuration, the old configuration entry and value is merged into the new configuration. This attribute has only effect if the patchFile attribute is set. | no | "true" | "false" |
keepOldValues | Whether to preserve the values of equal entries from an old configuration, if they can be found. Set false to overwrite old configuration values by default with the new ones, regardless whether they have been already set in an old configuration. Values from an old configuration can only be preserved, if the appropriate entries exist in an old configuration. This attribute has only effect if the patchFile attribute is set. | no | "true" | "false" |
| escape | Whether to parse the following sequences as escape characters and write them as those while saving as they appear in the parsed configuration file:
| no | "true" | "false" ("true") |
escapeNewLine | When this option is true, lines are concatenated as far as the last char before the line break is a backslash ('\'). In this case the trailing line break is omitted, interpreting several lines ending on '\' as a single "long" line. | no | "true" | "false" ("true") |
headerComment | Whether to allow header comments in the file. If this option is set true, the comment before the first entry is treated as the global header comment for the whole file, not logically assigning this comment to the first option itself. The header comment might be overwritten internally separately and is separated using a newline | no | "true" | "false" ("false") |
emptyLines | Whether to preserve empty lines. If set false, empty lines in configuration files get lost when saving the file. | no | "true" | "false" ("true") |
| operator | Set this option to override the default operator for option and INI files completely. Currently, when a configuration files is parsed, there can be used '=' or ':' as operator between keys and values, but the file is always saved using '=' with a leading and trailing space character, which works fine for Java property and Windows INI files. The operator might be overload for saving non-standard formats, for instance for leaving the ':' as operator. Another use case is saving Java Service Wrapper configuration files, which isn't correctly parsed if there are leading and trailing whitespace characters on the operator - for that case, the operator can be set to the string "=" preventing usage of leading and trailing whitespaces for saving. | no | string of 1 or more characters |
resolveExpression | Whether expressions should be resolved during patching of configurations. This is not similar to substituting IzPack variables, but by means of resolving references to configuration entries in the same configuration file, see [ini4j] - Expression handling. | no | "true" | "false" |
overwrite | Whether to allow overwriting an existing target file. | no | "true" | "false" |
condition | An Izpack condition, which must be fulfilled to start the according configuration action. | no | string referring to a condition id |
...