We need you!

Icon

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

Skip to end of metadata
Go to start of metadata

registry

Supports patching/merging within, and explicit editing of, the Windows registry. Also supports patching, merging, and editing of Windows Registry Editor files (.reg), which are basically INI files with a custom header that use full registry key names for sections. Any attempt to access a Windows registry on a non-Windows system will lead to a runtime error, but this task can be used to modify Windows Registry Editor files on any platform.

The processing engine for the Windows registry and for Registry Editor files is an integrated version of the ini4j framework. The options for attributes and nested elements reflect the functionality of this framework. The <registry> configuration type can be used to patch or update a single registry key (and its subkeys), or to patch a fileset of Registry Editor files against a target directory containing Registry Editor files. Manual definition of key/value/data entries is supported by using the <entry> element.

Parameters 

Attributes marked ini4j expose features of the underlying ini4j framework. See the ini4j documentation for fuller details. A single <registry> task can work with either directly in the Windows registry, or with Registry Editor files.

Registry Editor (.reg) files

Specify a <registry> task to work with .reg files (instead of directly in the registry) in exactly the same way as the <inifile> task. Note that you should still use the format for the <entry> element as documented below, but that <fileset> and <mapper> nested elements can be used as documented for INI files.

Windows registry

Use these parameters with the <registry> task in order to work directly with the Windows registry. Registry keys must be specified as a full, absolute path. Abbreviations like HKLM are not permitted.

AttributeDescriptionRequired
fromkeyThe source registry key containing the original configuration.

No. Patching destinations can also be updated by manual definition using nested <entry> elements. If specified, fromkey must exist. Cannot be used with fromfile/tofile/targetfile.

tokeyThe registry key to patch to.Yes. Cannot be used with fromfile/tofile/targetfile.
createAllow destination registry keys to be created when they don't already exist.No; defaults to true.
failonerrorIf false, the listener will try to continue processing remaining actions even when errors in reading, processing, or writing files occur. Instead of immediately failing, a warning message is written to the log. Setting to true will ignore errors on non-Windows systems, but this is not recommended. Cross-platform installers should use an OS condition to completely skip execution of the task on non-Windows systems.No; defaults to true.
conditionSpecifies the name of an IzPack installer condition that must be fulfilled before the configuration is executed.No.
keepOldKeys (ini4j)Whether to generally preserve registry values with the same name (but not necessarily the same data) from the source key, if they can be found. Note that the IzPack Configuration Listener deals with a property key and its value, which in Windows registry terms translates to a registry 'value' and its 'data'. Windows registry values occur inside a registry key. Hence, fromkey is about Windows registry keys, but keepOldKeys is about Windows registry values.

If keepOldKeys="true" and a registry value occurs in the source key and also in the destination key, the value in the destination key is unmodified, and the data is set according to keepOldValues. Otherwise, if the value found in the source key is not found in the destination key, the old value/data pair is merged to the destination key. Manual <entry> definitions will override the original of a preserved registry key value.
No; defaults to true. 
keepOldValues (ini4j) Whether to preserve the value data of values that appear inside both the source key and the destination key. Note that the IzPack Configuration Listener deals with a property key and its value, which in Windows registry terms translates to a registry 'value' and its 'data'. Windows registry values occur inside a registry key. Hence, keepOldValues is about Windows registry value data.

Set false to overwrite the data of source values by default with the destination ones, regardless whether they were already set in the source key. Data from a value in the source key can only be preserved, if the same value exists in the equivalent destination key. Manual <entry> definitions will override the data of a destination value even when keepOldValues is true. 
No; defaults to true. 
resolveExpressions (ini4j) Whether ini4j expressions should be resolved when a registry key is being patched. This is not the same as substituting IzPack variables, but resolves references to subkeys and value in the same registry key. See [ini4j] - Expression handling.No; defaults to false.

Nested Elements 

entry 

The nested <entry> is used to override the definition of a certain registry value against the default behavior defined with action-global attributes or their ini4j defaults. An entry can even be used without the fromkey attribute to add values to, or modify existing values, in the destination registry key. Further, a new registry key, with values and subkeys, can be defined entirely using <entry> elements where tokey did not previously exist.

The <entry> element can be used when directly modifying the Windows registry, or when patching or modifying a single Registry Editor (.reg) file.

AttributeDescriptionRequired
keyThe registry subkey to modify or create. Interpreted relative to the registry key defined by tokey in the enclosing <registry> task.No. If omitted, this <entry> will apply to the key defined in tokey.
valueThe registry value to set.Yes, unless operation is "keep" or "remove" (these operations may be applied to a whole subkey). 
dataThe new data to apply to the specified registry value.

Yes, if operation="set" and default is not specified; optional otherwise.

Defaults to "1" for numeric data types, and to "" for the string type (i.e. the empty string), only for increment/decrement operations. 

defaultA fallback value to set the registry value data to if no other definition can be found, i.e. if parameter data is not specified, or if the value is not already defined in the registry key.

Yes, if operation="set" and value is not specified; optional otherwise. When dataType="date", the keyword "now" is allowed.

Where no previous value is defined, defaults to "now" for the date type, and to "0" for the int type,  only for increment/decrement operations. 

dataTypeInstructs that value data be treated as a certain data type during processing. Support currently exists for treating value data as a date or an integer, instead of as a plain string. Can be used with the pattern parameter to define string parsing and output formatting, and/or with the operation  parameter to perform basic calculations.No; defaults to "string". Can also be set to "int" or "date".
operation

Overrides global patching behavior for specific entries, or allows basic calculations for numeric data types (i.e. int and date). When this attribute is omitted, the value data will be set to the specified data or default

Values can be removed from the registry key by specifying operation="remove" (data/default do not have to be set in this case). The entry is removed even if keepOldValues is true. Using operation="keep" preserves the original data in a value when using fromkey, even if keepOldKeys is false. These operations are valid for all data types.

Specifying operation="+" performs an increment operation can on numeric data types, or an append operation on the string type. For numeric types, a decrement operation can also be performed, where data is deducted from the original value of a key (or the specified default, where no original value data exists). Use parameter unit to define the scope of increment/decrement on the date type.

No; defaults to "=". Valid values for all data types are "=" (set), "+" (increment/append), "remove", "keep". For numeric data types, the value "-" (decrement) is also valid.
unitDefines the date component to modify when dataType="date" and operation is "+" or "-".

No; defaults to "day". Can only be specified when dataType="date". Valid values are "millisecond", "second", "minute", "hour", "day", "week", "month""year".

patternFor numeric data types, a string formatting pattern can be specified using conventional Java formatting placeholders. This defines both the input parsing and output formatting pattern for this entry. See javadoc for DecimalFormat (applies to int) and SimpleDateFormat (applies to date).

No. The default pattern for date is "yyyy/MM/dd HH:mm".

fileset

Can be used when patching multiple Registry Editor files. See the inifile documentation for usage.

mapper  

Can be used when patching multiple Registry Editor files. See the inifile documentation for usage.

Examples 

Merge the values from an existing registry key into a new registry key. Copy all values and data from the original key. Explicitly delete the subkey legacyOps (with all its values) from the new key. Execute the task only if the IzPack condition isUpgrade is fulfilled. Note the use of IzPack variable APP_VER and user-defined variable oldAppVer.

 

Create a new uninstall key in the registry, or update the values in an existing uninstall key.

 

 

 

 

  • No labels