Usage of validators

Validator play an important role during the processing of a form. They control the components to the required values needed by the application in order to commit them after submit. The validator concept of the *FormEngine ensures that a form can only be quit with valid data. So that a validation can omit for the data in back end. This advantage affect if for the acquisition of a record, depending on the current context of the application, will apply different rules or in any other form expression, only a subset of the data should be entered.

Use of validators in the XML definition

The components becomes a to use validator class allocated in the form definition. About boolean Validator several rules can be logically linked. The available default validators can be specified via elements in the XML definition, whose names match exactly to the class name of the validator implementations.

For example, over the the element <length .../> the validator class LengthValidator from the default package for validators de.imatics.forms.validator is used. The attributes of the elements are passed directly as parameters to the validator. <length min="5"/> therefore provide for a check of the component value of at least five characters – insofar as it is a text component. Some validators can validate depending on their semantic meaning, different types of data. In a multiple choice (list components) would in this example at least five elements expected in the selection.

Currently over 20 validator implementation are available can be used in this way. Their names and descriptions can be found in the API documentation in the download archive.

In the following example a length and content check is logically connected so that the entered text has at least 50 characters or the string must contain short. For an AND operation of rules the <and> tag below the <validator> element can be omitted, because by default all validators are conjugate.

<component ...>
   <validator>
      <or>
         <length min="50"/>
         <contains value="short"/>
      </or>
   </validator>
</component>

For custom validator implementations a special element is available.

<custom class="my.own.ValidatorClass"/>

Dynamic parameters for validators

The parameters for the validator must not be specified as fixed values, but can also be computed at runtime by Calculator. In the simplest case the ValueCalculator returns the value of another component. The previous example can be adapted so that the required length or the sub-string to be contained is determined in another component.

In validators that require exactly one parameter, the Calculator directly specified as a child element of the validator (e.g. in contains). For validators with multiple kinds of parameters, the name of the parameter and in it the calculator will be specified over addition parameter elements.

<component ...>
   <validator>
      <or>
         <length>
            <parameter name="min">
               <value component="componentX"/>
            </parameter>
         </length>
         <contains/>
            <value component="componentY"/>
         </contains/>
      </or>
   </validator>
</component>

Execution of the validation

Whenever the value of a component should be validated, it will be passed "from below" by the framework to the validator hierarchy. As soon as a validator does not accept the value, it throws an exception with a description of the faulty value. The logical validators or and and summarize the reports of several validators on a message if necessary.

Special Treatment of empty elements

When using the validator a speciality that only entered values will be verified must be attended. The reason is that a form field is not implicitly a required field and the value should only be checked if indeed anything has been entered. For example, the format of an e-mail address will be verified, but it does not need to enter an e-mail address.

Thus, not every validator must implement the acceptance of null or it must be activated using a parameter, a validator is only called if the required value is not null.

The only exception is the <required> Validator (equivalent to <not-empty>). This may conjugated with each validator to define a field as required field.

In the first case is to have the input value of at least 3 and a maximum of 10 characters. It can also be entered no value, which indeed to a length of 0 and not always the intuition of the used validator corresponds.

<validator>
   <length min="3" max="10"/>
</validator>

To force an entry the required validator has to be included.

<validator>
   <required/>
   <length min="3" max="10"/>
</validator>

Implement Custom Validators

You can use own Validator classes o implement specific rules, not realizable with the standard validators. For this, you have to derive one of the the class de.imatics.forms.validator.Validator or de.imatics.forms.validator.ComponentValidator and implement the method validate. The method have to throw a ValidatorException if the value does not meet the requirements, and runs through without exception if the value is ok.

This exception will then issue an internationalized error message displayed to the user in the form. A Message object is passed to the constructor of the exception, that is a reference to a MessageBundle and a message key within this bundle. The message bundle should be placed in the same directory as the Validator class To prevent overlap between the same keys in different classes, the complete message key searched in the bnudle is then combined with the name of the class and the short key passed when calling the message method.

package de.imatics.example.validator;

import de.imatics.forms.validator.*;
import de.imatics.i18n.*;
import de.imatics.forms.DataContext;

public class MyValidator extends ComponentValidator {
  private static final I18n i18n = I18n.getInstance(MyValidator.class);

  protected void validate(DataContext component) throws ValidatorException {
    Object value = component.getValue();
    boolean isValid = ...;
    if (!isValid) {
      Message message = i18n.message("myMessageKey");
      throw new ValidatorException(this, component, message);
    }
  }
}

MyValidator.myMessageKey = My error message

This validator can be used over the custom element in the form definition.

<validator>
   <custom class="de.imatics.example.validator.MyValidator"/>
</validator>