Introduction

On panels of type UserInputPanel, user input fields always represent and set one single variable exactly to the value the user entered. This is usually done when leaving the panel in either direction, back (by pressing "Previous") or forward (by pressing "Next").

There might be use cases, where the user value should be transformed to a different format on the fly in that moment. For instance, one might want to encrypt a password the user entered in plain format on the fly.

Field validators attached to the field or even panel validators always "see" the unprocessed value while the IzPack variable is set to the processed value. There can be optionally defined a backup variable which hold the original, unprocessed value of the field. For the example of password encryption, this can be used to use the plain password for several post-install actions like for connecting to the database over a JDBC driver and calling some SQL statements, while the encrypted pendant is saved to a configuration file.

This is what processors can be used for. Processors are Java classes implementing the Processor interface, which convert one String to another one. There are built-in processors which can be enhanced by user implementations.

Definition

Processors are defined as nested element of the <spec> section within a field, like this:

<field type="..." variable="...">
    <spec>
        ...
        <processor class="fully.qualified.ProcessorClassName" [backupVariable="..."] [toVariable="..."]>
            <configuration>
                <whatever-param-name>...</whatever-param-name>
                <another-param2-name>...</another-param2-name>
                ...
            </configuration>
        </processor>
    </spec>
    <validator class="fully.qualified.ValidatorClassName" txt="..." id="..."/>
</field>

or in an alternative notation:

<field type="..." variable="...">
    <spec>
        ...
        <processor class="fully.qualified.ProcessorClassName" [backupVariable="..."] [toVariable="..."]>
            <configuration>
                <param name="whatever-param-name" value="..."/>
                <param name="another-param2-name" value="..."/>
                ...
            </configuration>
        </processor>
    </spec>
    <validator class="fully.qualified.ValidatorClassName" txt="..." id="..."/>
</field>

The <configuration> section is optional.

For making migration easier, there can be used still <param name="..." value="..." /> entries instead or additionally to the newer <configuration> definition. This approach might be removed in one of the next major versions.

Parameter values may contain unresolved references to IzPack variables, which are resolved at installation time.

Attributes

• backupVariable (optional):
  a variable holding the original value entered by the user before processing took place
  This variable is not present before the processor action actually happens.
• toVariable (optional) (since 5.1.2):
  a variable to store the processed value and leave the original value unchanged.
  This variable is not present before the processor action actually happens.

Built-in processors

Build-in processors are available in IzPack in the package com.izforge.izpack.panels.userinput.processor.

The following processors are available by default in IzPack:

PasswordEncryptionProcessor

This processor encrypts a given password using the Java Cryptography Architecture.

Configuration parameters:

• encryptionKey (required)
  A string acting a seed for generating a secure random number generator used for encryption. This is also called a secret key.

• algorithm (required)
  The name of the encryption algorithm to be used.
  The available algorithms depend on your JRE, see this documentation for more information.

PortProcessor

This processor can be add to a simple input field (1 part) or a rule input field of the form host:port (2 parts). It takes in both cases the given value for the port and tries to check whether this port is available either locally (1-part field) or at the given host (2-part rule field).

If the port is not available it automatically increases it by 1 and tries the same again until it finds a free port, which is used as the final, processed value.

This processor takes no configuration parameters.

UnixGroupProcessor

This processor does not use the user input at all, but generates a list of available UNIX groups (scanned from the file /etc/group) as a single string with ':' as the separator character.

UnixUserProcessor

This processor does not use the user input at all, but generates a list of available UNIX users (scanned from the file /etc/passwd) as a single string with ':' as the separator character.

Example

The following example defines a simple password input panel for entering a new password, for example for a database to be created:

  <panel id="panel.password">
    <field type="title" txt="Password panel" id="panel.password.title" />
    <field type="password" align="left" variable="keystore.password">
      <spec>
        <pwd txt="Keystore Password:" size="25" set=""/>
        <pwd txt="Retype Password:" size="25" set=""/>
        <processor class="custom.processor.Md5Processor" toVariable="keystore.password.md5" />
        <processor class="com.izforge.izpack.panels.userinput.processor.PasswordEncryptionProcessor" backupVariable="keystore.password.plain">
          <configuration>
            <encryptionKey>MySecretKey</encryptionKey>
            <algorithm>AES</algorithm>
          </configuration>
        </processor>
      </spec>
      <validator class="com.izforge.izpack.panels.userinput.validator.PasswordEqualityValidator"
                 txt="Both keystore passwords must match." id="key for the error text"/>
    </field>
  </panel>

The above panel shows two user input fields for passwords. Both passwords entered must match, which is ensured by the PasswordEqualityValidator when leaving the panel. After the validation has passed, the plain password the user entered is encrypted with the encryption key and algorithm defined as processor parameters. The encrypted result of this operation is stored in the field variable keystore.password, the variable keystore.password.md5 holds a md5 hash of the value . To not loose the plain password the user entered we defined additionally the (optional) backup variable keystore.password.plain, which holds the original user value and can be used for further post-processing during the installation.