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 applied 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")

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).

escapeNewLine

headerComment

emptyLines

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.

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

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)

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 "remove" for deleting the matching key-value pair completely.

no

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

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

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.

type

The global file type of all files for which this ConfigurableSet is defined. It is not allowed to mix several file types in this action.

yes

"options" | "ini"
("options")

toDir

The target directory to recursively patch from source files of the same names to.

no
(if toFile is used)

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

toFile

The target file to patch to from all source files.

no
(if toDir is used)

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

fromFile

The source file to patch from.
Nested fileset elements can be used instead to patch from a couple of files to the target.

no
(if the nested fileset tag is used)

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

cleanup

Whether to remove all source files after the operation which don't act also as target files with the same name.

no

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

keepOldKeys

Whether to generally preserve equal entries but not necessarily their values from an old 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.

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.

no

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

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

overwrite

Whether to allow overwriting existing files.

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

failOnError

Whether to abort the installation if an error occurs executing this action.
If set "false", a debug log warning is written in case of an error.

no

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

includeEmptyDirs

Whether to include empty source directories should be also recursively copied during patching of a whole fileset to a target directory specified by toDir.

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

preservelastmodified

Whether to preserve the source file timestamps on the target files during patching.

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

enablemultiplemappings

Whether to apply multiple file name mappings of one and the same file name mapper for a given  source file. If false the task will only process the first file or directory to map to, and not renaming one and the same file or directory to multiple files or directories. This attribute is only relevant if there is a nested mapper element used.
Whether the situation of a potential multiple mapping can happen depends on the type of the nested mapper element.

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