6.7 Using Declarative Validation Rules

One page of the Entity Object Editor worthy of special attention is the Validation page, where you can see and manage the declarative validation rules for the entity or any of its attributes. The framework enforces entity-level validation rules when a user tries to commit pending changes or simply navigates between rows. Attribute-level validation rules are enforced when the user changes the value of the related attribute. When you add a validation rule, you supply an appropriate error message and can later translate it easily into other languages if needed. Oracle ADF ships with a number of built-in declarative validation rules that you'll see in this section. Section 9.3, "Using Method Validators" explains how to use the Method Validator to invoke custom validation code and in Section 26.9, "Implementing Custom Validation Rules" you'll learn how to extend the basic set of declarative rules with custom rules of your own.

6.7.1 How to Add a Validation Rule

To add a validation rule to an entity object, use the Validation page of the Entity Object Editor, as shown in Figure 6-17. To add an attribute-level validation rule, select the attribute in the Declared Validation Rules tree, and click New.... Defining an entity-level validation rule is similar, except that you select the root entity object node in the tree before clicking New....

Figure 6-17 Validation Page of the Entity Object Editor

When you add a new validation rule, the Add Validation Rule dialog appears. Use the Rule dropdown list to select the kind of validation rule you want, and configure its declarative settings using the other controls in the page. The controls will change depending on the kind of validation rule you select. Figure 6-18 illustrates what the Add Validation Rule dialog would look like when defining a range validation rule for the ProdId attribute of the ServiceRequest entity object. This validation rule has been selected to enforce that the value lie between 100 and 999 inclusive. When you add a validation rule, you also can enter an error message that will be shown to the user if the validation rule fails.

Figure 6-18 Adding a New Range Validation Rule for the ProdId Attribute

6.7.2 What Happens When You Add a Validation Rule

When you add a validation rule to an entity object, JDeveloper updates its XML component definition to include an entry describing what rule you've used and what rule properties you've entered. For example, if you add the range validation rule above to the ProdId attribute, this results in a RangeValidationBean entry in the XML file:

<Entity Name="ServiceRequest"
   <!-- : -->
   <Attribute Name="ProdId" IsNotNull="true" Precision="8" Scale="0"
      ColumnName="PROD_ID" Type="oracle.jbo.domain.Number" 
      ColumnType="NUMBER" SQLType="NUMERIC" TableName="SERVICE_REQUESTS" >
      <RangeValidationBean
         xmlns="http://xmlns.oracle.com/adfm/validation"
         ResId="ProdId_Rule_0" 
         OnAttribute="ProdId"
         OperandType="LITERAL"
         MinValue="100"
         MaxValue="999" >
      </RangeValidationBean>
   </Attribute>
   <!-- : -->
</Entity>

At runtime, the rule is automatically enforced by the entity object based on this declarative information. The error message is a translatable string and is managed in the same way as translatable UI control hints in an entity object message bundle class. The ResId property in the XML component definition entry for the validator corresponds to the String key in the message bundle. Example 6-4 shows the relevant bit of the ServiceRequest entity object's message bundle, where the ProdId_Rule_0 key appears with the error message for the default locale. The validation errors messages get translated using the same mechanism described above for UI control hints.

Example 6-4 Entity Object Message Bundle Contains Validation Error Messages

package devguide.model.entities.common;
import oracle.jbo.common.JboResourceBundle;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---------------------------------------------------------------------
public class ServiceRequestImplMsgBundle extends JboResourceBundle {
  static final Object[][] sMessageStrings = {
  // other strings here
  { "ProdId_Rule_0", "Valid product codes are between 100 and 999" },
  // other strings here
  };
  // etc.
}

6.7.3 What You May Need to Know About Validation Rules

{para}?>It is important to know that some validators can be used at the entity level, and some are used on the attribute level. Also, you should be aware the List Validator is designed for working with a relatively small set.

6.7.3.1 Understanding the Built-in Entity-Level Validators

You can use the following built-in validators at the entity object level:

Unique Key Validator

Validates that the primary key for an entity is unique.

Method Validator

Invokes a method in an entity object's custom Java class to evaluate a programmatic validation.

6.7.3.2 Understanding the Built-in Attribute-Level Validators

You can use the following built-in validators at the entity object attribute level:

Compare Validator

Validates an attribute value against:

• A literal value,

• A selected attribute of the first row of a view object query result, or

• The first column of the first row of a SQL query result

List Validator

Validates that an attribute exists in an in-memory set of values from a:

• Static list,

• A selected attribute in the rows of view object's default row set, or

• The first column value in the rows of a SQL query result.

Range Validator

Validates that an attribute lies between a minimum and maximum value, inclusive.

Length Validator

Validates whether the string length of an attribute's value is less than, equal to, or greater than a fixed number of characters.

Regular Expression Validator

Validates that an attribute's value matches a regular expression.

Method Validator

Invokes a method in an entity object's custom Java class to evaluate a programmatic validation.

6.7.3.3 Caveat About the List Validator

The List Validator is designed for validating an attribute against a relatively small set of values. As shown in Figure 6-19, if you select the Query Result or View Object Attribute style of list validation, keep in mind the validator will retrieve all of the rows from the query before performing an in-memory scan to validate whether the attribute value in question matches an attribute in the list. The query performed by the Validator's SQL or view object query does not reference the value being validated in the WHERE clause of the query.

In other words, this is not the feature to use if you want to validate that a user-entered product code exists in a table of a million products. Section 9.6, "Using View Objects for Validation", explains the technique you can use to efficiently perform SQL-based validations by using a view object to perform a targeted validation query against the database.

Figure 6-19 List Validator is Designed for Relatively Small Lists of Values