20.3 Adding Validation

You can add validation so that when a user edits or enters data in a field and submits the form, the data is validated against any set rules and conditions. If validation fails, the application displays an error message.

Those rules and conditions can be set at one of the following layers:

View layer: You can use ADF Faces validation when you need client-side validation. Many ADF Faces components have attributes that provide validation. For information, see Section 20.3.1.1.1, "Using Validation Attributes". In addition, ADF Faces provides separate validation classes that can be run on both the client and the server. For details, see Section 20.3.1.1.2, "Using JSF and ADF Faces Validators". You can also create your own validators. For information about custom validators, see Section 20.4.3, "How to Create a Custom JSF Validator".
Model layer: By default, when you use the Data Control Palette to create input text components, the components contain the af:validator tag that is bound to the validator property on the attribute's binding. This binding allows a JSF application to run ADF Model validation during the JSF Process Validations phase. Note that in an ADF Business Components application, unless you use data controls other than the application module data controls, you don't need to use additional ADF Model validation rules. If you want to use ADF Model validation, you declaratively set the validation rules on bindings to attributes of a collection. For more information, see Section 20.3.1.2, "Adding ADF Model Validation".
Business layer: You set declarative validation rules for the entity object in the business layer, and any of the entity object attributes. By placing validation in the business domain layer of entity objects, the validation can be reused when that attribute's value is accessed by any page. Consider placing all, if not most, of your validation rules in the centralized, more reusable, and easier to maintain entity objects of your business domain layer.

For the purposes of this chapter, only the ADF Faces validators and ADF Model validation will be discussed. For information about using ADF Business Components declarative validation rules, see Section 6.7, "Using Declarative Validation Rules". For information about using or extending the basic set of declarative rules with custom rules and code of your own, see Section 9.3, "Using Method Validators".

20.3.1 How to Add Validation

You set ADF Faces validation on the JSF page and you set ADF Model validation on the page definition file. Message display for both is handled on the JSF page. For more information about displaying messages created by validation errors, see Section 20.7, "Displaying Error Messages".

20.3.1.1 Adding ADF Faces Validation

By default, ADF Faces validation occurs on both the client and server side. Although both syntactic and semantic validation are performed on the client side and server side, the client side performs only a subset of the validation performed by the server side. Client-side validation allows validators to catch and display data without requiring a round-trip to the server.

Note:

If the JavaScript form.submit() function is called on a JSF page, the ADF Faces support for client-side validation is bypassed. ADF Faces provides a submitForm() method that you can use instead, or you could use the autoSubmit attribute on ADF Faces input components.

To set ADF Faces to not run client-side validation, add the <client-validation-disabled> element in adf-faces-config.xml and set it to true.

ADF Faces provides the following types of validation:

UI component attributes: ADF Faces input components provide attributes that can be used to validate data. For example, you can supply simple validation using the required attribute on ADF Faces input components to specify whether a value must be supplied. When set to true, the component must have a value. Otherwise the application displays an error message. For more information, see Section 20.3.1.1.1, "Using Validation Attributes".
Default ADF Faces validators: The validators supplied by ADF Faces and the JSF reference implementation provide common validation checks, such as validating date ranges and validating the length of entered data. For more information, see Section 20.3.1.1.2, "Using JSF and ADF Faces Validators".
Custom ADF Faces validators: You can create your own validators and then select them to be used in conjunction with UI components. For more information, see Section 20.4, "Creating Custom JSF Validation".

20.3.1.1.1 Using Validation Attributes

Many ADF Faces UI components have attributes that provide simple validation. Table 20-1 shows these attributes, along with a description of the validation logic they provide and the UI components that contain them.

Table 20-1 ADF Faces Validation Attributes

Attribute	Description	Available on
`MaxValue`	The maximum value allowed for the `Date` value.	`chooseDate`
`MinValue`	The minimum value allowed for the `Date` value.	`chooseDate`
`Required`	When set to `true` (or set to an EL expression that evaluates to `true`), the component must have a non-null value or a `String` value of at least one character. For table selection components (see Section 14.6, "Enabling Row Selection in a Table"), if the `required` attribute is set to `true`, then at least one row in the table must be selected.	All input components, all select components, `tableSelectMany`, `tableSelectOne`
`MaximumLength`	The maximum number of characters that can be entered. Note that this value is independent of the value set for the `columns` attribute. See also `ByteLengthValidator` in Table 20-3, "ADF Faces Validators".	`inputText`

When you use the Data Control Palette to create input components, the required attribute is bound to the mandatory property of its associated binding, as shown in the following EL expression:

<af:inputText required="#{bindings.ProblemDescription.mandatory}"

The EL expression evaluates to whether or not the attribute on the object to which it is bound can be null. You can choose to keep the expression as is, or you can manually set the required attribute to "true" or "false".

Tip:

The object to which the UI component is bound varies depending on how the input component was created. For example, if a search form was created using a parameter form, then the input components are usually bound to variables, since the attribute values are only temporarily stored in the binding container before passing them onto methods or parameterized actions. If a form was created using a collection, then the input component is probably bound to an attribute on an entity object.

To use UI component attributes that provide validation:

In the Structure window, select the UI component.
In the Property Inspector, enter a value for the validation attribute. See Table 20-1 for a list of validation attributes you could use.
(Optional) Set the tip attribute to display text that will guide the user to entering correct data (for example, a valid range for numbers). This text will display under the component.
(Optional) If you set the required attribute to true (or if you used an EL expression that can evaluate to true), you can also enter a value for the RequiredMessageDetail attribute. Instead of displaying a default message, ADF Faces will display this message, if validation fails.

For tables with a selection component set to required, you must place the error message in the summary attribute of the table in order for the error message to display.

Messages can include optional placeholders (such as {0}, {1}, and so on) for parameters. At runtime, the placeholders are replaced with the appropriate parameter values. The order of parameters is:
- Component label input value (if present)
- Minimum value (if present)
- Maximum value (if present)
- Pattern value (if present)
Example 20-1 shows a RequiredMessageDetail attribute that uses parameters.
Example 20-1 Parameters in a RequiredMessageDetail Attribute
```
<af:inputText value="#{bindings.productId.inputValue}"
              label="Product ID"
              requiredMessageDetail="You must enter a {0}."
              required="true"
</af:inputText>
```
This message evaluates to You must enter a Product ID.

For additional help with UI component attributes, in the Property Inspector, right-click the attribute name and choose Help.

20.3.1.1.2 Using JSF and ADF Faces Validators

JSF and ADF Faces validators provide more complex validation routines. Table 20-2 describes the JSF reference implementation validators that have supplied tags.

Table 20-2 JSF Reference Implementation Validators

Validator	Tag Name	Description
`DoubleRangeValidator`	`f:validateDoubleRange`	Validates that a component value is within a specified range. The value must be convertible to floating-point type or a floating-point.
`LengthValidator`	`f:validateLength`	Validates that the length of a component value is within a specified range. The value must be of type `java.lang.String`
`LongRangeValidator`	`f:validateLongRange`	Validates that a component value is within a specified range. The value must be any numeric type or `String` that can be converted to a `long`

Table 20-3 describes the built-in validators and tags supplied by ADF Faces.

Table 20-3 ADF Faces Validators

Validator Tag Name Description

Validator	Tag Name	Description
`ByteLengthValidator`	`af:validateByteLength`	Validates the number of bytes in a `String` when Java encoding is used. For example, six English characters do not use the same byte storage as 6 Japanese characters. You specify the encoding to use as an attribute of the validator. In cases where the server must limit the number of bytes required to store a string, use this validator instead of specifying the `maximumLength` attribute on an input component. In an Oracle database table column of type `VARCHAR2(n)`, when using multi-byte character sets, the maximum allowed byte length might be different from `n`, depending on whether or not the size of the `VARCHAR2` in the database implies character or byte size.
`DateTimeRangeValidator`	`af:validateDateTimeRange`	Validates that the entered date is within a given range. You specify the range as attributes of the validator.
`RegExpValidator`	`af:validateRegExp`	Validates the data using Java regular expression syntax.

ByteLengthValidator

af:validateByteLength

Validates the number of bytes in a String when Java encoding is used. For example, six English characters do not use the same byte storage as 6 Japanese characters. You specify the encoding to use as an attribute of the validator.

In cases where the server must limit the number of bytes required to store a string, use this validator instead of specifying the maximumLength attribute on an input component.

In an Oracle database table column of type VARCHAR2(n), when using multi-byte character sets, the maximum allowed byte length might be different from n, depending on whether or not the size of the VARCHAR2 in the database implies character or byte size.

DateTimeRangeValidator

af:validateDateTimeRange

Validates that the entered date is within a given range. You specify the range as attributes of the validator.

RegExpValidator

af:validateRegExp

Validates the data using Java regular expression syntax.

Note:

ADF Faces also provides the af:validator tag, which you can use to register a custom validator on a component. For information about using custom validators, see Section 20.4, "Creating Custom JSF Validation".

By default, whenever you drop an attribute from the Data Control Palette as an input text component, JDeveloper automatically adds the af:validator tag to the component, and binds it to the validator property on the associated binding. The binding allows access to ADF Model validation for processing on the client side. For more information, see Section 20.3.2, "What Happens When You Create Input Fields Using the Data Control Palette". For information about ADF Model validation, see Section 20.3.1.2, "Adding ADF Model Validation".

To add ADF Faces validators:

In the Structure window, right-click the component for which you'd like to add a validator.
In the context menu, choose Insert inside <UI component> > ADF Faces Core to insert an ADF Faces validator. (To insert a JSF reference implementation validator, choose Insert inside <UI component> > JSF Core.)
Choose a validator tag (for example, ValidateDateTimeRange).
In the Property Inspector, set values for the attributes, including any messages for validation errors. For additional help, right-click any of the attributes and choose Help.

ADF Faces lets you customize the detail portion of a validation error message. By setting a value for an XxxMessageDetail attribute, where Xxx is the validation error type (for example, maximumMessageDetail), ADF Faces displays the custom message instead of a default message, if validation fails.

20.3.1.2 Adding ADF Model Validation

Note that you don't need to add additional ADF Model validation if you have already set validation rules in the business domain layer of your entity objects. In an ADF Business Components application, unless you use data controls other than your application module data controls, you won't need to use ADF Model validation.

Table 20-4 describes the ADF Model validation rules that you can configure for an attribute.

Table 20-4 ADF Model Validation Rules

Validator Rule Name	Description
Compare	Compares the attribute's value with a literal value
List	Validates whether or not the value is in or is not in a list of values
Range	Validates whether or not the value is within a range of values
Length	Validates the value's character or byte size against a size and operand (such as greater than or equal to)
Regular Expression	Validates the data using Java regular expression syntax

To create an ADF Model validation rule:

Open the page definition that contains the attribute for which you want to create a rule.
In the Structure window, select the attribute, list, or table binding.
In the Property Inspector, select the Edit Validation Rule link.
In the Validation Rules Editor, select the attribute name and click New.
In the Add Validation Rule dialog, select a validation rule and configure the rule accordingly. For additional help on creating the different types of rules, click Help.

Note:

For information about ADF Business Components declarative validation rules, see Section 6.7, "Using Declarative Validation Rules".

20.3.2 What Happens When You Create Input Fields Using the Data Control Palette

When you use the Data Control Palette to create input text fields (for example, by dropping an attribute from the Data Control Palette as an inputText component), JDeveloper automatically provides ADF Faces validation code on the JSF page by:

Adding an af:messages tag as a child of the afh:body tag.

By default the globalOnly attribute is set to false, and the message and text attributes are not set. For more information, see Section 20.7, "Displaying Error Messages".
Binding the required attribute for input fields to the mandatory property of the associated attribute binding, as shown in the following EL expression:
```
<af:inputText required="#{bindings.ProblemDescription.mandatory}"
```
The expression evaluates to whether or not a null value is allowed based on the attribute of the associated business object. By default, all components whose required attribute evaluates to true will display an asterisk.

Adding an af:validator tag as a child of the input component, and binding the tag to the validator property of the associated binding, as shown below:

<af:inputText value="#{bindings.SomeAttribute.inputValue}"...>
  <af:validator binding="#{bindings.SomeAttribute.validator}"/>
</af:inputText>

The binding allows the JSF lifecycle to access, on the client side, any ADF Model validation that you may have set for the associated attribute. If you don't wish to use ADF Model validation, then you can delete the af:validator tag and insert the validation tag of your choice, or if you don't want to use any validation, you can simply delete the tag. If you do want to use only ADF Model validation, you must keep the tag as is.

Tip:

If you delete the af:validator tag and its binding, and want to add ADF Model validation at a later point, you must add the tag back into the code with the binding attribute bound to the associated attribute's validator property.

To create a simple input form for products in the SRDemo application, for example, you might drop a collection similar to the ProductList collection from the Data Control Palette as a creation form. Example 20-2 shows the JSF code created by JDeveloper if such a collection were dropped.

Example 20-2 JSF Code for a Create Product Page

<afh:body>
  <af:messages/>
  <h:form>
    <af:panelForm>
      <af:inputText value="#{bindings.ProdId.inputValue}"
                    label="#{bindings.ProdId.label}"
                    required="#{bindings.ProdId.mandatory}"
                    columns="#{bindings.ProdId.displayWidth}">
        <af:validator binding="#{bindings.ProdId.validator}"/>
        <f:convertNumber groupingUsed="false"
                         pattern="#{bindings.ProdId.format}"/>
      </af:inputText>
      <af:inputText value="#{bindings.Name.inputValue}"
                    label="#{bindings.Name.label}"
                    required="#{bindings.Name.mandatory}"
                    columns="#{bindings.Name.displayWidth}">
        <af:validator binding="#{bindings.Name.validator}"/>
      </af:inputText>
      <af:inputText value="#{bindings.Image.inputValue}"
                    label="#{bindings.Image.label}"
                    required="#{bindings.Image.mandatory}"
                    columns="#{bindings.Image.displayWidth}">
        <af:validator binding="#{bindings.Image.validator}"/>
      </af:inputText>
      <af:inputText value="#{bindings.Description.inputValue}"
                    label="#{bindings.Description.label}"
                    required="#{bindings.Description.mandatory}"
                    columns="#{bindings.Description.displayWidth}">
        <af:validator binding="#{bindings.Description.validator}"/>
      </af:inputText>
      <f:facet name="footer">
        <af:commandButton text="Submit"/>
      </f:facet>
    </af:panelForm>
  </h:form>
</afh:body>

Note that each inputText component's required attribute is bound to the mandatory property of its associated binding. The EL expression evaluates to whether or not the attribute on the object to which it is bound can be null.

20.3.3 What Happens at Runtime

When the user submits the page, the ADF Faces validate() method first checks for a submitted value if the required attribute of a component is true. If the value is null or a zero-length string, the component is invalidated. At this point, what happens depends on whether or not client-side validation is enabled.

If client-side validation is enabled, an error message is placed in the queue. If there are other validators registered on the component, they are not called at all, and the current page is redisplayed with a dialog displaying the error message.

Note:

JSF reference implementation validators are not run on the client side.

In Example 20-2, a value for the image attribute is not required. However, all other values are required, as set by the mandatory property. This is denoted in the web page by asterisks next to the input text fields, as shown in Figure 20-2. Figure 20-2 also shows the alert dialog that is displayed if no data is entered for the product ID, and if client-side validation is enabled. If no data is entered for all three required fields, then the alert would show three error messages.

Figure 20-2 Client-Side Error for a Required Value

If the submitted value is a non-null value or a string value of at least one character, the validation process continues and all validators on the component are called one at a time. Because the af:validator tag on the component is bound to the validator property on the binding, any validation routines set on the model are also accessed and executed at this time.

The process then continues to the next component. If all validations are successful, the Update Model Values phase starts and a local value is used to update the model. If any validation fails, the current page is redisplayed along with the error dialog.

When client-side validation is disabled, all validations are done on the server. First, the ADF Faces validation is performed during the Process Validations phase. If any errors are encountered, the values are invalidated and the associated messages are added to the queue in FacesContext. Once all validation is run on the components, control passes to the model layer, which runs the Validate Model Updates phase. As with the Process Validations phase, if any errors are encountered, the values are invalidated and the associated messages are added to the queue in FacesContext (for information on how errors other than validation or conversion are handled, see Section 20.8, "Handling and Displaying Exceptions in an ADF Application"). The lifecycle then jumps to the Render Response phase and redisplays the current page. ADF Faces automatically displays an error icon next to the label of any input component that generated an error, and it displays the associated messages below the input field. If there is a tip associated with the field, the error message displays below the tip. Figure 20-3 shows a server-side validation error.

Figure 20-3 Server-Side Validation Error

20.3.4 What You May Need to Know

You can both set the required attribute and use validators on a component. However, if you set the required attribute to true and the value is null or a zero-length string, the component is invalidated and any other validators registered on the component are not called.

This combination might be an issue if there is a valid case for the component to be empty. For example, if the page contains a Cancel button, the user should be able to click that button and navigate off the page without entering any data. To handle this case, you set the immediate attribute on the Cancel button's component to true. This attribute allows the action to be executed during the Apply Request Values phase, thus bypassing the validation whenever the action is executed.