We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • option and property files
  • INI files
  • XML files
  • Windows registry entries.

IzPack conditions can be used to allow certain configuration actionsConfigurationListener 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.

...

Using the ConfigurationInstallerListener requires the following definitions in the install descriptor:

Define the following jar files o be explicitely included in the installation:

...

  • There might be a couple of additional libraries bound to the installer depending on the needs:
    • In order to use XML merge/patch actions in common you need to add jdom:jdom2 artifact to the installer.
      JDom 2.0.5 is the current minimum requirement IzPack has been tested against. 
    • In order to use XPath queries you need also to add the jaxen:jaxen artifact to the installer.
      JDom 2.0.5 currently optionally depends on Jaxen 1.1.4.
    • In order to use the "dtd" XML merge action you need to add com.wutka:dtdparser artifact to the installer.
      DTD Parser 1.21 is the current minimum requirement IzPack has been tested against. 
Code Block
titleExample of adding all optional libraries
languagehtml/xml
<jar src="dtdparser-1.21.jar" stage="install"/>
<jar src="jaxen-1.1.

...

4.jar" stage="install"/>
<jar src="jdom-

...

2.

...

0.

...

5.jar" stage="install"/>

...

 

  • Define the configuration action descriptor as resource "ConfigurationActionsSpec.xml"

...

Code Block
xml
xml
<resources>
    <res id="ConfigurationActionsSpec.xml" src="resources/config-actions-spec.xml"/>
</resources>

 

  • Include the ConfigurationsInstallerListener as custom action

...

Code Block

...

<listeners>

...

    <listener 

...

classname="ConfigurationInstallerListener" stage="install"/>
</listeners>

Configuration Actions Example

...

A configuration action is added using the element <configurable>.

Attributes

 

  

Attribute

Description

Required

Allowed Values
(Default)

type

The file type to handle.

yes

"options" | "ini" | "xml" | "registry"
("options")

toFile

The target file to write the patch result to. This is equal to the file a patch should be apllied against, if the attribute originalFile is not set.

yes
(if type != "registry")

absolute or relative (against $INSTALL_PATH) path denoting a file

toKey

The registry root key to patch to, provided that type = "registry".

yes
(if type = "registry")

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
(if the nested fileset tag or simply the nested entry tag is used)

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
(if type = "registry")

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"
("false")

create

Whether to create the target file when it doesn't already exist

no

"true" | "false"
("true")

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"
("true")

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"
("true")

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:

  • \\ (escape character),
  • \t (tab),
  • \n (new line),
  • \f (form feed for printers),
  • \b (backspace),
  • \r (line feed).
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 newlineno"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.
This attribute has only effect if the patchFile attribute is set.

no

"true" | "false"
("false")

overwrite

Whether to allow overwriting an existing target file.

no

"true" | "false"
("false")

condition

An Izpack condition, which must be fulfilled to start the according configuration action.

no

string referring to a condition id

Nested Elements
<entry>

The nested <entry> element is used to override the handling of a certain configuration key and its value against the default behavior defined using the action-global attributes above or their defaults. This means, <entry> overrides modifications of the target file after patching, and can be also used without the patchFile attribute simply to modify the target configuration file with explicit values.

Limitations: The nested entry element works currently only for type = "option", "ini" or "registry".

Attribute

Description

Required

Allowed Values
(Default)

section

The entry INI section to lookup a key within.

no
(required if configurable attribute type = "ini"

 

key

The entry key to deal with.
In case the key ends with a dot ('.'), the key is automatically assumed as a autonumbered value. Example key = "key." would match all keys "key.0", "key.1", ...). The operation below applies on each of those keys unless a limitation by lookup by value isn't done (attribute lookupType).

yes

 

value

configurable/type="option": The entry value to set or to lookup for.
configurable/type="ini": The entry value to set.
configurable/type="registry" - The registry value (not data, but for looking up the right data, in terms of Microsoft)

no
(required if attribute lookupType is set)

 

dataconfigurable/type="registry": The registry data.
This attribute is allowed just for registry entries.
no
(required if configurable/type is "registry" and a value should be set)
 

lookupType

The lookup type used if the entry should be looked up by value. Setting this attributes automatically activates lookup by value in the original file (the file to patch to). The "value" attribute must be set with the plain or regular expression to lookup by value.
"plain" means looking up the plain value according to value, "regexp" means treating value as a Java regular expression.

This applies currently just for values of configurable/type="options".

no

"plain" | "regexp"
("plain")

operation

The operation to apply on the entry value: "+" or "=" (default) for all datatypes; "-" for date and int only), "keep" to keep the single value from the patch file for the according key, or "delete" for deleting the matching key-value pair completely.

no

"+" | "=" | "-" | "keep" | "delete"
("=")

dataType

The data type the entry value should be treated as for certain operations.

no

"int" | "date" | "string"
("string")

unit

The unit of the value to be applied to "date" +/- operations.

no

"millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
("day")

default

Initial value to set for a property if it is not already defined in the property file. For type "date", an additional keyword is allowed: "now"

no

 

pattern

For "int" and "date" type only. If present, the value will be parsed and formatted accordingly.

no

 

<xpathproperty>

The nested <xpathproperty> element is used to override the default XML merging handling of a certain XML content.

...

Limitations: The nested entry element works only for type ="xml".

Copies the if it existsCopies the patch element if it exist in the original if no corresponding patch element exists.Copies the if it does not exist in the original document. 

Attribute

Description

Required

Allowed Value
(Default)

key

The XPath property key to deal with.

yes

"matcher.default" |
"action.default" |
"mapper.default" |
"xpath.path.<number>_ |
"matcher.path.<number>" |
"action.path.<number>" |
"mapper.path.<number>"

value

The XPath property value to set the above key value to.

yes

  • Key begins on "matcher.":
    Defines how to gather a matching pair of elements from the original and the patch document. Possible values:
    • "TAG"
      Match the element names. 
    • "ATTRIBUTE"
      Match element name and attributes (names and values)
    • "ID_ATTRIBUTE"
      Match element name and the value of the attribute with the name "ID".
    • "NAME_ATTRIBUTE"
      Match element name and the value of the attribute with the name "NAME".
    • "SKIP"
      Never match neither element names nor attributes. 

Default: "ATTRIBUTE"

 

  • Key begins on "action.":
    • "FULLMERGE"
      Merge implementation traversing element contents undependend of their order.
      Note: This does completely merge all matching elements and attributes regardless of there order. This is more time-consuming than ORDEREDMERGE, but it is not necessary to rely on a well-ordered XML. 
    • "ORDEREDMERGE"
      Merge implementation traversing parallelly both element contents. Works when contents are in the same order in both elements.
      Note: This does completely merge all matching elements and attributes, assuming they appear in the same order comparing the patched file with the patch file. This action executes faster than FULLMERGE, but can lead to bad results if the order of both sides is different.
    • "REPLACE"
    • Add or replace - if there is a matching patch element
    • , add it or replace an existing matching original element by it, otherwise keep the original matching element.
    • "OVERRIDE"
    • Just replace an existing matching original element by a matching patch element, but don't add anything if the original element does not exist. If there is no matching patch element, keep the original
    • matching element
    • "KEEP"
      Copies the patch element if it exists also in original, otherwise nothing is added. The original element won't be added in any case. 
    • "COMPLETE"
    • Just add a matching patch element, but only
    • in case there is no matching original element. Leave an original matching element otherwise, don't overwrite it.
    • "DELETE"
      Keeps the original element only if it does not appear in the patch document. 
    • "PRESERVE"
      Copies the original regardless of the existence of patch element. 
    • "INSERT"
      Copies the patch element into the output by inserting it after already existing elements of the same name. Usually applied with the matcher option "SKIP".
    • "DTD"
      Copy the patch element in the output parent with the correct position according to the DTD defined in the document. 

Default: ("FULLMERGE")

  • Key begins on "mapper.":
    How the matching element should be further transformed during applying the action.
    There might be more transformations supported in future, filtering out elements and attributes with a specified namespace 
    • "IDENTITY"
      Does not transform the element. 

Default: "IDENTITY"

  • Key begins on "xpath.path.":
    The path to the particular XML elements which should be handled by the so numbered action, matcher and mapper (or their defaults). The XPath is a quite complex language, for more information see XML Path Language (XPath) Version 1.0, WikiPedia and many more documents and tutorials.

<configurableset> Configuration Action - Patch a Set of Files

...