Using Standard Validators

It's difficult to imagine a Web application that does not perform a healthy dose of data validation. Since validation is so pervasive, it should be easy to use and extend. JavaServer Faces fits the bill in both respects by providing a handful of standard validators and affording you a simple mechanism for implementing your own validators.

A key role of validation is to protect the model. Because JSF uses separate phases for processing validations and updating model values, you can be assured that the model is not put into an inconsistent state if some of the inputs cannot be validated.

Validating String Lengths and Numeric Ranges

It's easy to use JSF validators within JSF pages simply add validator tags to the body of a component tag, like this:

 <h:inputText  value="#{payment.card}">    <f:validateLength minimum="13"/> </h:inputText>

The preceding code fragment adds a validator to a text field; when the text field's form is submitted, the validator makes sure that the string contains at least 13 characters. When validation fails (in this case, when the string has 12 or fewer characters), validators generate error messages associated with the guilty component. These messages can later be displayed in a JSF page by the h:message or h:messages tag.

NOTE

JavaServer Faces 1.0 does not explicitly support client-side validation. All validation occurs on the server after the user has submitted the form data. If you want validation to occur inside the browser, you need to supply custom tags that contain the appropriate JavaScript commands. See Chapter 12 for details.

JavaServer Faces has built-in mechanisms that let you carry out the following validations:

Checking the length of a string
Checking limits for a numerical value (for example, > 0 or 100)

Table 6-3 lists the standard validators that are provided with JSF. You saw the string length validator in the preceding section. To validate numerical input, you use a range validator. For example,

 <h:inputText  value="#{payment.amount}">   <f:validateLongRange minimum="10" maximum="10000"/> </h:inputText>

Table 6-3. Standard Validators
JSP Tag	Validator Class	Attributes	Validates
`f:validateDoubleRange`	`DoubleRangeValidator`	`minimum, maximum`	a `double` value within an optional range
`f:validateLongRange`	`LongRangeValidator`	`minimum, maximum`	a `long` value within an optional range
`f:validateLength`	`LengthValidator`	`minimum, maximum`	a `String` with a minimum and maximum number of characters

The validator checks that the supplied value is 10 and 10000.

All the standard validator tags have minimum and maximum attributes. You need to supply one or both of these attributes.

Checking for Required Values

To check that a value is supplied, you do not nest a validator inside the input component tag. Instead, you supply the attribute required="true":

 <h:inputText  value="#{payment.date}" required="true"/>

All JSF input tags support the required attribute. You can combine the required attribute with a nested validator:

 <h:inputText  value="#{payment.card}" required="true">    <f:validateLength minimum="13"/> </h:inputText>

CAUTION

If the required attribute is not set and a user supplies a blank input, then no validation occurs at all! Instead, the blank input is interpreted as a request to leave the existing value unchanged.

Displaying Validation Errors

Validation errors are handled in the same way as conversion errors. A message is added to the component that failed validation, the component is invalidated, and the current page is redisplayed immediately after the "Process Validations" phase has completed.

You use the h:message or h:messages tag to display the validation errors. For details see the section on displaying conversion errors on page 211.

You can override the default validator messages shown in Table 6-4. Define a message bundle for your application, and supply messages with the appropriate keys, as shown on page 213.

Table 6-4. Standard Validation Error Messages
Resource ID	Default Text	Reported by
`javax.faces.component.UIInput.REQUIRED`	Validation Error: Value is required.	`UIInput` with `required` attribute when value is missing
`javax.faces.validator.NOT_IN_RANGE`	Validation Error: Specified attribute is not between the expected values of {0} and {1}.	`DoubleRangeValidator` and `LongRangeValidator` when value is out of range and both `minimum` and `maximum` are specified
javax.faces.validator.DoubleRangeValidator.MAXIMUM javax.faces.validator.LongRangeValidator.MAXIMUM	Validation Error: Value is greater than allowable maximum of '{0}'.	`DoubleRangeValidator` or `LongRangeValidator` when value is out of range and only `maximum` is specified
javax.faces.validator.DoubleRangeValidator.MINIMUM javax.faces.validator.LongRangeValidator.MINIMUM	Validation Error: Value is less than allowable minimum of '{0}'.	`DoubleRangeValidator` or `LongRangeValidator` when value is out of range and only `minimum` is specified
javax.faces.validator.DoubleRangeValidator.TYPE javax.faces.validator.LongRangeValidator.TYPE	Validation Error: Value is not of the correct type.	`DoubleRangeValidator` or `LongRangeValidator` when value cannot be converted to `double` or `long`
`javax.faces.validator.LengthValidator.MAXIMUM`	Validation Error: Value is greater than allowable maximum of ''{0}''.	`LengthValidator` when string length is greater than `maximum`
`javax.faces.validator.LengthValidator.MINIMUM`	Validation Error: Value is less than allowable minimum of ''{0}''.	`LengthValidator` when string length is less than `minimum`

Bypassing Validation

As you saw in the preceding examples, validation errors (as well as conversion errors) force a redisplay of the current page. This behavior can be problematic with certain navigation actions. Suppose, for example, you add a "Cancel" button to a page that contains required fields. If the user simply clicks Cancel, leaving a required field blank, then the validation mechanism kicks in and forces the current page to be redisplayed.

It would be unreasonable to expect your users to fill in required fields before they are allowed to cancel their input. Fortunately, a bypass mechanism is available. If a command has the immediate attribute set, then the command is executed during the "Apply Request Values" phase.

Thus, you would implement a Cancel button like this:

 <h:commandButton value="Cancel" action="cancel" immediate="true"/>

A Complete Validation Example

The following sample application shows a form that employs all of the standard JSF validation checks: required fields, string length, and numeric limits. The application makes sure that values are entered in all fields, the amount is between $10 and $10,000, the credit card number has at least 13 characters, and the PIN is a number between 1000 and 9999. Figure 6-6 shows typical validation error messages. A Cancel button is also provided to demonstrate the validation bypass.

Figure 6-6. Typical Validation Error Messages

Figure 6-7 shows the directory structure of the application. Listing 6-5 contains the JSF page with the validators.

Listing 6-5. `validator/index.jsp`

  1. <html>  2.    <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>  3.    <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>  4.    <f:view>  5.       <head>  6.          <link href="styles.css" rel="stylesheet" type="text/css"/>  7.          <f:loadBundle basename="com.corejsf.messages" var="msgs"/>  8.          <title><h:outputText value="#{msgs.title}"/></title>  9.       </head> 10.       <body> 11.          <h:form> 12.             <h1><h:outputText value="#{msgs.enterPayment}"/></h1> 13.             <h:panelGrid columns="3"> 14.                <h:outputText value="#{msgs.amount}"/> 15.                <h:inputText  value="#{payment.amount}" 16.                   required="true"> 17.                   <f:convertNumber minFractionDigits="2"/> 18.                   <f:validateDoubleRange minimum="10" maximum="10000"/> 19.                </h:inputText> 20.                <h:message for="amount" style/> 21. 22.                <h:outputText value="#{msgs.creditCard}"/> 23.                <h:inputText  value="#{payment.card}" 24.                   required="true"> 25.                   <f:validateLength minimum="13"/> 26.                </h:inputText> 27.                <h:message for="card" style/> 28. 29.                <h:outputText value="#{msgs.expirationDate}"/> 30.                <h:inputText  value="#{payment.date}" 31.                   required="true"> 32.                   <f:convertDateTime pattern="MM/yyyy"/> 33.                </h:inputText> 34.                <h:message for="date" style/> 35.             </h:panelGrid> 36.             <h:commandButton value="Process" action="process"/> 37.             <h:commandButton value="Cancel" action="cancel" immediate="true"/> 38.          </h:form> 39.       </body> 40.    </f:view> 41. </html>