2009/05/20 - Apache Shale has been retired.

For more information, please explore the Attic.

Commons Validator Integration

Validation Introduction

JavaServer Faces 1.x does not explicitly support client-side validation and only provides a minimal set of server-side validators. On the other hand, Apache Commons Validator supports both client- and server-side validators and comes with the following useful validators:

  • Credit Card
  • Date
  • Email
  • Generic
  • ISBN
  • URL
All of the preceding validators can be executed either on the client or the server, or both. Shale integrates JavaServer Faces and the Commons Validator.

Services Provided

Shale provides three JSP tags that let you use the Commons Validator: val:commonsValidator, val:validatorVar, and val:validatorScript. The first two lets you attach a commons validator to a JSF input component and the third generates JavaScript validation code for validating each JSF component that has one or more Commons validators in a particular form. You can attach as many Commons validators to a single JSF input component as you wish.

Using Commons Validator Integration

Here's what you need to do to use Shale validation:

  • Add an onsubmit attribute to your h:form tag that calls the JavaScript validation function generated by val:validatorScript.
  • Add Commons validators to JSF input components with val:commonsValidator and, optionally, val:validatorVar.
  • Add an val:validatorScript tag at the end of the h:form tag's body.
Here's an example:
<%@ taglib uri="http://shale.apache.org/core" prefix="val" %>
...
<h:form onsubmit="return validateForm(this);">

    <h:inputText id="creditCardNumber" 
               size="16"
              value="#{userContext.creditCardNumber}">

        <val:commonsValidator type="required"
                             arg="#{msgs.creditCardNumberPrompt}"
                          server="true"
                          client="true"/>

        <val:commonsValidator type="mask"
                             arg="#{msgs.creditCardNumberPrompt}"
                          server="true"
                          client="true">
            <val:validatorVar name="mask" value="[4-6].*"/>
        </val:commonsValidator>

        <val:commonsValidator type="creditCard" 
                             arg="#{msgs.creditCardNumberPrompt}" 
                          server="true"/>
    </h:inputText> 

    <h:message for="creditCardNumber" styleClass="errors"/> 

    <val:validatorScript functionName="validateForm"/>
</h:form>
...

In the preceding example, we've attached three Commons validators to a single JSF input component. To pass validation, the field must have a value that starts with a number between 4 and 6 inclusive and that value must be a valid credit card number as verified by the Luhn algorithm. Two of the validations are performed on both client and server and one is performed on the server only.

Note: At the present time, you have the option to forego server-side validation, which is considered very bad practice. Users can turn off JavaScript, so you should always backup client-side validation with server-side validation. In the future, Shale may enforce server-side validation if it's not explicitly specified.

Using Custom Validaton Rules

Shale's Commons Validator integration also allows you to use custom validation rules.

In most cases, you will want to include the default rule set in addition to your custom rules. In web.xml, use the org.apache.shale.validator.VALIDATOR_RULES context initialization parameter to specify a comma delimited list of files.

    <!-- Shale Validator Configuration Resources -->
    <context-param>
       <param-name>org.apache.shale.validator.VALIDATOR_RULES</param-name>
       <param-value>
           /org/apache/shale/validator/validator-rules.xml,
           /WEB-INF/custom-rules.xml
       </param-value>
    </context-param>

In this example, the default validator-rules.xml file will be loaded from the shale-core.jar archive, and the custom-rules.xml file will be loaded from WEB-INF.

To replace one of the provided rules, place a modified copy of validator-rules.xml in your webapp, and refer to it instead of the default file.

To add messages for your own validation rules, or to customize the provided messages, configure a message bundle for your application in /WEB-INF/faces-config.xml.

More information on Shale's Commons Validator integration, including step-by-step examples, can be found on the ShaleValidation Wiki page.