Creating a Custom Validator

If the standard validators don't perform the validation checking you need, you can easily create a custom validator to validate user input. As explained in Validation Model, there are two ways to implement validation code:

Implement a backing bean method that performs the validation.

Provide an implementation of the Validator interface to perform the validation.

Writing a Method to Perform Validation explains how to implement a backing bean to perform validation. The rest of this section explains how to implement the Validator interface.

If you choose to implement the Validator interface and you want to allow the page author to configure the validator's attributes from the page, you also must create a custom tag for registering the validator on a component.

If you prefer to configure the attributes in the implementation, you can forgo creating a custom tag and instead let the page author register the validator on a component using a validator tag. This tag simply refers to the Validator implementation, which handles the configuration of the validator's attributes.

Usually, you will want to display an error message when data fails validation. You need to store these error messages in a ResourceBundle. For more information on creating a ResourceBundle, see

When validation fails, you can queue the error messages onto the FacesContext programmatically. Alternatively, you can have the application architect register the error messages using the application configuration resource file. Registering Messages explains how to register error messages with the application.

The Duke's Bookstore application uses a general-purpose custom validator (called bookstore6/src/validators/FormatValidator) that validates input data against a format pattern that is specified in the custom validator tag. This validator is used with the Credit Card Number field on the bookcashier.jsp page. Here is the custom validator tag:

A 16-digit number with no spaces

A 16-digit number with a space between every four digits

A 16-digit number with hyphens between every four digits

The rest of this section describes how this validator is implemented and how to create a custom tag so that the page author can register the validator on a component.

Implement the Validator Interface

This Validator implementation must contain a constructor, a set of accessor methods for any attributes on the tag, and a validate method, which overrides the validate method of the Validator interface.

The FormatValidator class also defines accessor methods for setting the attribute formatPatterns, which specifies the acceptable format patterns for input into the fields. In addition, the class overrides validate method of the Validator interface. This method validates the input and also accesses the custom error messages to be displayed when the String is invalid.

The validate method performs the actual validation of the data. It takes the FacesContext, the component whose data needs to be validated, and the value that needs to be validated. A validator can validate only data of a UIInput component or a component that extends UIInput.

public void validate(FacesContext context, UIComponent 
component, 
  Object toValidate) {
  boolean valid = false;
  String value = null;
  if ((context == null) || (component == null)) {
    throw new NullPointerException();
  }
  if (!(component instanceof UIInput)) {
    return;
  }
  if ( null == formatPatternsList || null == toValidate) {
    return;
  }
  value = toValidate.toString();
  //validate the value against the list of valid patterns.
  Iterator patternIt = formatPatternsList.iterator();
  while (patternIt.hasNext()) {
    valid = isFormatValid(
      ((String)patternIt.next()), value);
    if (valid) {
      break;
    }
  }
  if ( !valid ) {
    FacesMessage errMsg =
      MessageFactory.getMessage(context,
        FORMAT_INVALID_MESSAGE_ID, 
          (new Object[] {formatPatterns}));
      throw new ValidatorException(errMsg);
  }
}

This method gets the local value of the component and converts it to a String. It then iterates over the formatPatternsList list, which is the list of acceptable patterns as specified in the formatPatterns attribute of the custom validator tag.

While iterating over the list, this method checks the pattern of the local value against the patterns in the list. If the pattern of the local value does not match any pattern in the list, this method generates an error message. It then passes the message to the constructor of ValidatorException. Eventually the message is queued onto the FacesContext so that the message is displayed on the page during the render response phase.

The error messages are retrieved from the Application instance by MessageFactory. An application that creates its own custom messages must provide a class, such as MessageFactory, that retrieves the messages from the Application instance. When creating your own application, you can simply copy the MessageFactory class from the Duke's Bookstore application to your application.

The getMessage(FacesContext, String, Object) method of MessageFactory takes a FacesContext, a static String that represents the key into the Properties file, and the format pattern as an Object. The key corresponds to the static message ID in the FormatValidator class:

When the error message is displayed, the format pattern will be substituted for the {0} in the error message, which, in English, is

Creating a Custom Tag

If you implemented a Validator interface rather than implementing a backing bean that performs the validation, you need to do one of the following:

Allow the page author to specify the Validator implementation to use with the validator tag. In this case, the Validator implementation must define its own properties. Using a Custom Validator explains how to use the validator tag.

Create a custom tag that provides attributes for configuring the properties of the validator from the page. Because the Validator implementation from the preceding section does not define its attributes, the application developer must create a custom tag so that the page author can define the format patterns in the tag.

Write a tag handler to create and register the Validator implementation on the component.

Write a TLD to define the tag and its attributes.

Writing the Tag Handler

The tag handler associated with a custom validator tag must extend the ValidatorTag class. This class is the base class for all custom tag handlers that create Validator instances and register them on UI components. The bookstore6/src/taglib/FormatValidatorTag is the class that registers the FormatValidator instance.

Sets the ID of the Validator by calling super.setValidatorId("FormatValidator").

Provides a set of accessor methods for each attribute defined on the tag.

Implements the createValidator method of the ValidatorTag class. This method creates an instance of the Validator and sets the range of values accepted by the validator.

protected Validator createValidator() throws JspException {
  FormatValidator result = null;
  result = (FormatValidator) super.createValidator();
  result.setFormatPatterns(formatPatterns);
  return result;
}

This method first calls super.createValidator to get a new Validator and casts it to FormatValidator.

Next, the tag handler sets the Validator instance's attribute values to those supplied as the values of the formatPatterns tag attribute. The handler gets the attribute values from the page via the accessor methods that correspond to the attributes.

Writing the Tag Library Descriptor

To define a tag, you declare it in a tag library descriptor (TLD), which is an XML document that describes a tag library. A TLD contains information about a library and each tag contained in it. See Tag Library Descriptors for more information about TLDs.

The custom validator tag is defined in the bookstore.tld, located in <INSTALL>/j2eetutorial14/examples/web/bookstore6/web/ directory. It contains only one tag definition, for formatValidator:

<tag>
  <name>formatValidator</name>
  ...
  <tag-class>taglib.FormatValidatorTag</tag-class>
  <attribute>
    <name>formatPatterns</name>
    <required>true</required>
    <rtexprvalue>false</rtexprvalue>
    ...
  </attribute>
</tag>

The name element defines the name of the tag as it must be used in the page. The tag-class element defines the tag handler class. The attribute elements define each of the tag's attributes.