Validating Field Content

A field validator is a Java class which prevents from changing to the next panel if one or more input field content is not valid during the installation. If the chosen validator reports some field content to be false, a messagebox is popped up with a defined (translated or untranslated content) and the user will be unable to continue to the next panel.

Validators are bound to particular fields, each field can have zero, one or more validators assigned in the user panel definition.

The validation itself is triggered when the user presses the Next button to change to the nex panel. This change is prevented in case of a negative validation, the user is forced to fix the bad input field values he previously provided.

There are built-in validators available, and own, user-defined validator implementations can be used.

Dedicated validators may support configuration parameters:

<field type="..." variable="...">
   ...
   <validator class="..." ...>
      <configuration>
         <param_1>...</param_1>
         ...
         <param_n>...</param_n>
      </configuration>
   </validator>
</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.

Using Validators

Validators are bound to user input fields using the nested <validator> element;

<field type="text" variable="ora.db">
  <spec txt="SID:" id="text.oraclesettings.sid" size="3" set=""/>
  <validator class="com.izforge.izpack.panels.userinput.validator.NotEmptyValidator" txt="Invalid oracle SID!" id="text.oraclesettings.error.sid" />
</field>

Field validators can be combined with field processors. Validation takes place before the field processor applies:

<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>xxx</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"/>
   <validator class="com.izforge.izpack.panels.userinput.validator.PasswordKeystoreValidator"
              txt="Could not validate keystore with password and alias provided." id="key for the error text">
      <configuration>
         <keystoreFile>${ssl.keystore}</keystoreFile>
         <keystoreType>${ssl.keystore.type}</keystoreType>
         <keystoreAlias>${keystore.key.alias}</keystoreAlias>
         <skipValidation>${skip.keystore.validation}</skipValidation>
      </configuration>
   </validator>
</field>

Built-in Validators

AbstractValidator

HostAddressValidator

IsPortValidator

...

The NotEmptyValidator simply checks that the user entered a non-null value into each subfield, and returns false otherwise.

<field type="rule" variable="test.notempty">
  <description align="left" txt="A description for a rule input field." id="description.rule.1"/>
  <spec txt="Please enter your phone number:" layout="( N:3:3 ) N:3:3 - N:4:4 x N:5:5" resultFormat="specialSeparator" separator="."/>
  <validator class="com.izforge.izpack.panels.userinput.validator.NotEmptyValidator" txt="The phone number is mandatory!" />
</field>

PasswordEqualityValidator

This validator uses a password field specification to compare the values in each field for equality. Normally, this would be to ensure a password was typed correctly before any other validation takes place.

<field type="password" align="left" variable="the.password">
  <spec>
    <pwd txt="The Password:" size="25" set=""/>
    <pwd txt="Retype Password:" size="25" set=""/>
  </spec>
  <validator class="com.izforge.izpack.panels.utiluserinput.validator.PasswordEqualityValidator"
        txt="Both passwords must match." id="lang pack key for the error text"/>
</field>

...

<field type="password" align="left" variable="keystore.password">
  <spec>
    <pwd txt="Keystore Password:" size="25" set=""/>
    <pwd txt="Retype Password:" size="25" set=""/>
  </spec>
  <validator class="com.izforge.izpack.panels.userinput.utilvalidator.PasswordEqualityValidator"
                txt="Both keystore passwords must match." id="key for the error text"/>
  <validator class="com.izforge.izpack.utilpanels.userinput.validator.PasswordKeystoreValidator"
                txt="Could not validate keystore with password and alias provided." id="key for the error text">
    <param name="keystoreFile" value="${ssl.keystore}"/>
    <param name="keystoreType" value="${ssl.keystore.type}"/>
    <param name="keystoreAlias" value="${keystore.key.alias}"/>
    <param name="skipValidation" value="${skip.keystore.validation}"/>
  </validator>
</field>

...

<field type="rule" variable="EMAILaddress">
  <spec
      txt="Your Email address:" layout="O:12:U @ O:8:40 .
      A:4:4"
      set="0: 1:domain 2:com" resultFormat="displayFormat"   />
  <validator   class="com.izforge.izpack.panels.userinput.utilvalidator.RegularExpressionValidator"
             txt="Invalid email address!">

     <param
        name="pattern"
        value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0
        -9_-]+)*[.][a-zA-Z0-9._-]{2,4}"
    />

  </validator>
</field>

The example of using Regexp validator in text input field:

<field type="text" variable="EMAILaddress">
  <spec
      txt="Your Email address:" set="you@domain.com" size="20" id=""
  />
  <validator
  class="com.izforge.izpack.utilpanels.userinput.validator.RegularExpressionValidator"
      txt="Invalid email address!">
    <param
        name="pattern"
        value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0
        -9_-]+)*[.][a-zA-Z0-9._-]{2,4}"
    />
  </validator>
</field>

An example of using regexp validator in a password field (attribute text wrapped for readability):

<field type="password" align="left" variable="db.password">
  <spec>
    <pwd txt="DB Password:" size="25" set=""/>
    <pwd txt="Retype Password:" size="25" set=""/>
  </spec>
  <validator class="com.izforge.izpack.panels.userinput.utilvalidator.PasswordEqualityValidator"
                txt="Both DB passwords must match." id="key for the error text"/>
  <validator class="com.izforge.izpack.panels.userinput.utilvalidator.RegularExpressionValidator"
             id="key for the error text">
             txt="Service password must begin with a character and be 8-20                                  mixed-case characters, numbers, and special characters [#@!$_]."
                                 id="key for the error text">>

     <param name="pattern" value="^(?=[a-zA-Z])(?=.*[0-9])(?=.*[#@!$_])
                (?=.*[A-Z])(?=.*[a-z])(?!.*[^a-zA-Z0-9#@!$_])(?!.*\s).{8,20}$"/>
  </validator>
</field>

...

You can implement your own custom Validator implementation simply by creating a new class which implements the comthe com.izforge.izpack.panels.Validator interface.userinput.validator.Validator interface. This interface specifies a single method: validate(ProcessingClient) , which returns a boolean value. You can retrieve the value entered by the user by casting the input ProcessingClient for example in the RuleInputField and call the RuleInputField.getText() method. You can also retrieve any parameters to your custom Validator by calling theRuleInputField.getValidatorParams() which returns a java.util.Map object containing parameter names mapped to parameter values. For an example, take a look at com.izforge.izpack.util.RegularExpressionValidator.

Set values in the RuleInputField can be preprocessed. At now you can specify a processor class to pre process a value to be set at initial value of a RuleInputField. Syntax:

<spec set="0:defaultVal:classname" .../>

The class name is an optional value. The class must implement the Processor interface.