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

Configuration Specification

The specification for configuration actions during installation is provided to ConfigurationInstallerListener in the XML file format. The root element is <configurationactions>. It should be added to the <resources> section of install.xml with the id "ConfigurationActionsSpec.xml".

Nested pack Element

All configuration actions are grouped by pack using the standard <pack> element.

AttributeDescriptionRequired
name

The name of the pack, for which the nested configuration actions should be executed. The nested configuration actions will not apply in case the pack defined by name is omitted by the user or automatically during the installation. Only one <pack> element should be specified per installation pack.

Yes

Nested configurationaction Element

A configuration action groups together a set of related configuration executions and optional dynamic variables. It may be executed at any of the pack-level installation phases.

AttributeDescriptionRequired
orderThe installation phase for executing the nested set of configuration executions.Yes. Valid values are beforepack, afterpackbeforepacks, afterpacks.

Nested Configuration Elements 

Every <configurationaction> element may contain at most one nested <variables> element, and one nested <configurables> element. An unlimited number of <configurationaction> elements may be nested in each <pack> element. They will be executed sequentially.

variables 

The nested <variables> element may contain an unlimited number of dynamic variable definitions for use within the configuration action. See Dynamic Variables for a complete guide. Variable placeholders may be used in any of the <configurables> specifications in the spec XML itself, including the definition of configuration entries.

configurables 

The <configurables> element may contain an unlimited number of configurable executions. Configurable types all have their own attributes/nested elements, but the following general rules apply.

  • Generally, a configurable permits automatic patching and manual definition.
    • Automatic patching involves a source ("from") and a destination ("to"). Attributes will generally exist to fine-tune the patching behaviour, e.g. to allow old entries and/or values to be preserved or discarded.
    • Manual definition involves a destination ("to") and explicit settings declared in the XML spec file as nested elements.
  • Configurable types should allow the specification of a target destination, where the new configuration will ultimately be written. This allows the original configuration files and artifacts to be backed up and thus preserved unmodified, e.g. for automating rollback. Note that ConfigurationInstallerListener does not currently have built-in support for automated rollback or uninstallation.
  • Manual definitions a configurable type should include support for deleting named config entries.
  • Where possible, configurable types allow entry values to be treated as numbers, dates, etc, to allow addition and subtraction operations for manual definitions.
  • A configurable type may support bulk operations, e.g. patching all config files in a directory from a fileset, as well as single-operation "to"-"from"-"target" actions.
  • All configurable types should be capable of conditional execution using the condition attribute (see IzPack Conditions).

Built-in configurable types are:

Custom configuration types are not currently supported, though the API may be used in custom extensions (see com.izforge.izpack.util.config).

Examples 

An outline of a configuration spec file for a pack named MyPack. There is a single configuration action that will be processed immediately after MyPack is installed.

  • No labels