12.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. In addition, ADF Faces provides separate validation classes that can be run on both the server and the client. You can also create your own validators.
Model layer: By default, when you use the Data Control Palette to create input text components, the components contain a validation tag that is bound to the validator property on the attribute's binding. This binding allows a faces application to run model layer validation during the JSF validation phase. To set model layer validation, you declaratively set validation rules on bindings to attributes of a collection.
Business layer: You can also set validation on objects in the business layer. An advantage to this type of validation is that it can be reused when that attribute's value is accessed by any page. However, it requires that the application accesses the business component in order for validation to be run. For the purposes of this chapter, only the view and model layer validation will be discussed.

12.3.1 How to Add Validation

You set ADF Faces validation on the JSF page and you set ADF Model layer 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 12.7, "Displaying Error Messages".

12.3.1.1 Adding ADF Faces Validation

By default, ADF Faces validation occurs on both the client and 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.
Default ADF Faces validators: The JSF and ADF Faces validators provide more complex validation, such as validating date ranges and validating the length of entered data.
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 12.4, "Creating Custom Validation".

12.3.1.1.1 Using Validation Attributes

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

Table 12-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 7.6, "Enable 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 `cols` attribute.	`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. This 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 this value, or you can manually set the required attribute.

Tip:

The object to which the UI component is bound varies depending on how the input component was created. For example, if a form was created using a method to create a parameter form, then the input components are usually bound to variables, since the attribute values do not yet exist. You need to set the isNotNull property on the variable if you wish to use the default EL expression. If a form was created using a collection returned by a method, then the input component is probably bound to an attribute on an entity object, and you need to set that object's isNotNull property.

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.
If you set the required attribute to true (or if you used an EL expression that can evaluate to true), enter a value for the RequiredMessageDetail attribute. This will be the message displayed if validation fails. You can also enter text for the Tip attribute. This text will display under the component, providing a tip for the user (such as the valid range for numbers) so they may correctly enter data.

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 12-1 shows a RequiredMessageDetail attribute that uses parameters.
Example 12-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.
Set the tip attribute (optional) to display text that will guide the user to entering correct data.

12.3.1.1.2 Using JSF and ADF Faces Validators

JSF and ADF Faces validators provide more complex validation routines. Table 12-2 describes the JSF reference implementation validators and Table 12-3 describes the default ADF Faces validators.

Table 12-2 JSF Reference Implementation Validators

Validator	Description
`validateDoubleRange`	Validates that a component value is within a specified range. The value must be convertible to floating-point type or a floating-point.
`validateLength`	Validates that the length of a component value is within a specified range. The value must be of type `java.lang.String`
`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 12-3 ADF Faces Validators

ADF Faces Validator	Description
`validateByteLength`	Validates the number of bytes in a String when encoded. You specify encoding as an attribute of the validator.
`validateDateTimeRange`	Validates that the entered date is within a given range. You specify the range as attributes of the validator.
`validateRegExp`	Validates the data using Java regular expression syntax
`validator`	Allows you to specify a validator. Use this validator when you create custom validators for which you did not create an associated tag. When you create an input text field using the Data Control Palette, this tag is automatically added and bound to the validator property on the associated binding. This binding allows access to ADF Model layer validation.

By default, whenever you drop an attribute as an input text component, JDeveloper inserts a generic validator tag for the component. This binding allows access to ADF Model layer validation for processing on the client side. If you don't wish to use an ADF Model layer rule, then you can delete the validator tag and insert the validation tag of your choice, or if you don't want to use any validation, you can delete the tag. However, if you do want to use only ADF Model layer validation, you must keep this tag as is.

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 validator, choose Insert inside <UI component> > JSF Core.
Choose a validator tag.
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.

12.3.1.2 Adding ADF Model Layer Validation

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

Table 12-4 ADF Model Layer Validation Rules

Validator 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 layer 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.

12.3.2 What Happens When You Add Validation

When you use the Data Control Palette to create input fields, JDeveloper automatically provides ADF Faces validation code on the JSF page by:

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

By default the globalOnly attribute is set to false, and the message and text attributes are not set. You need to configure these. For more information, see Section 12.7, "Displaying Error Messages".
Binding the required attribute for input fields to the mandatory property of the associated attribute binding.

This value 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. This validator is bound to the validator property of the associated binding.

This binding allows the JSF lifecycle to access, on the client side, any ADF Model layer validation that you may have set for the associated attribute. If you do not set any ADF Model layer validation, you may remove this binding. However, if you add any at a later point, you must add this binding back into the code.

Tip:

If you plan to use ADF Model layer binding, the validator tag must be bound to the associated attribute's validator property. For example:

<af:validator binding="#{bindings.<attribute>.validator}"/>

To create a simple input form for products in the SRDemo application, for example, you might drop the product constructor method from the Data Control Palette as a parameter form. Example 12-2 shows the JSF code created by JDeveloper.

Example 12-2 JSF Code for a Create Product Page

<afh:body>
  <af:messages/>
  <h:form>
    <af:panelForm>
      <af:inputText value="#{bindings.productId.inputValue}"
                    label="#{bindings.productId.label}"
                    required="#{bindings.productId.mandatory}"
                    columns="#{bindings.productId.displayWidth}">
        <af:validator binding="#{bindings.productId.validator}"/>
        <f:convertNumber groupingUsed="false"
                         pattern="#{bindings.productId.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>
    </af:panelForm>
    <af:commandButton actionListener="#{bindings.createProducts.execute}"
                      text="createProducts"
                      disabled="#{!bindings.createProducts.enabled}"/>
  </h:form>
</afh:body>

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

When you create an ADF Model layer validation rule for an attribute, JDeveloper adds the validation rule to the attribute binding, which in turn references the associated validation bean and provides the needed property values for the validation to run. Example 12-3 shows the page definition code created if you add a Length validation rule to the productDescription attribute setting the maximum size for the attribute to 20.

Example 12-3 Page Definition Validation Rule

<attributeValues id="description" IterBinding="variables"
                 ApplyValidation="true">
  <LengthValidationBean xmlns="http://xmlns.oracle.com/adfm/validation"
             OnAttribute="createProducts_description"
             DataType="CHARACTER" CompareType="LESSTHAN"
             ResId="description_Rule_0" Inverse="false"
             CompareLength="20"/>
  <AttrNames>
     <Item Value="createProducts_description"/>
  </AttrNames>
</attributeValues>

12.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 set to 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 validators are not run on the client-side

In Example 12-2, the image attribute is not required. However, all other columns are required, as set by the mandatory property. This is denoted in the web page by asterisk icons. Figure 12-2 shows the error message displayed if no data is entered for the product ID, and if client-side validation is enabled.

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

Error message displays in a pop-up dialog

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 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 validation is 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 12.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 12-3 shows a server-side validation error.

Figure 12-3 Server-Side Validation Error

12.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 ApplyRequestValues phase, thus bypassing the validation whenever the action is executed.