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="..."]>
            <configuration>
                <whatever-param-name>MySecretKey</whatever-param-name>
                <another-param2-name>AES</another-param2-name>
            </configuration>
        </processor>
    </spec>
    <validator class="fully.qualified.ValidatorClassName" txt="..." id="..."/>
</field>

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:

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="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 result of this operation is stored in the field variable keystore.password. 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.