9.3 Using Method Validators

Method validators are the primary way Oracle recommends supplementing declarative validation rules using your own Java code. Method validators trigger Java code that you write in your own validation methods at the appropriate time during the entity object validation cycle. You can add any number of attribute-level method validators or entity-level method validators, provided they each trigger a distinct method name in your code. All validation method names must begin with the word validate; however, following that rule you are free to name them in any way that most clearly identifies there functionality.

9.3.1 How to Create an Attribute-Level Method Validation

To create an attribute-level method validator:

Open the Entity Object Editor
If your entity object does not yet have a custom Java class, then first open the Java page and enable the generation of an Entity Object Class, and click Apply to generate the *.java file.
Open the Validation page and select the attribute that you want to validate.
Click New to add a validation rule.
Select the Method Validator type from the Rule dropdown list, as shown in Figure 9-3.

The Add Validation Rule dialog displays the expected method signature for an attribute-level validation method. You have two choices:

If you already have a method in your entity object's custom Java class of the appropriate signature, it will appear in the list and you can select it after unchecking the Create and Select Method checkbox.
If you leave the Create and Select Method checked, you can enter any method name in the Method Name box that begins with the word validate and when you click OK, JDeveloper will add that method to your entity object's custom Java class with the appropriate signature.

Finally, supply the text of the error message for the default locale that the end user should see if this validation rule fails.

Figure 9-3 Adding an Attribute-Level Method Validator

9.3.2 What Happens When You Create an Attribute-Level Method Validator

When you add a new method validator, JDeveloper updates the XML component definition to reflect the new validation rule. If you asked to have the method created, the method is added to the entity object's custom Java class. Example 9-1 illustrates a simple attribute-level validation rule that ensures the AssignedDate of a service request is a date in the current month. Notice that the method accepts an argument of the same type as the corresponding attribute, and that its conditional logic is based on the value of this incoming parameter. When the attribute validator fires, the attribute value has not yet been set to the new value in question, so calling the getAssignedDate() method inside the attribute validator for the AssignedDate attribute would return the attribute's current value, rather than the candidate value that the client is attempting to set.

Example 9-1 Simple Attribute-Level Method Validator

// In ServiceRequestImpl.java in SRDemo Sample
public boolean validateAssignedDate(Date  data) {
  if (data != null && data.compareTo(getFirstDayOfCurrentMonth()) <= 0) {
    return false;
  }
  return true;
}

Note:

The return value of the compareTo() method is zero (0) if the two dates are equal, negative one (-1) if the first date is less than the second, or positive one (1) if the first date is greater than the second.

9.3.3 How to Create an Entity-Level Method Validator

To create an entity-level method validator:

Open the Entity Object Editor.
If your entity object does not yet have a custom Java class, then first open the Java page and enable the generation of an Entity Object Class, and click Apply to generate the *.java file.
Open the Validation page and select root node in the tree that represents the entity object itself.
Click New to add a validation rule.
Select the Method Validator type from the Rule dropdown list, as shown in Figure 9-4.

The Add Validation Rule dialog displays the expected method signature for an entity-level validation method. You have two choices:

If you already have a method in your entity object's custom Java class of the appropriate signature, it will appear in the list and you can select it after unchecking the Create and Select Method checkbox
If you leave the Create and Select Method checked, you can enter any method name in the Method Name box that begins with the word validate and when you click OK JDeveloper will add that method to your entity object's custom Java class with the appropriate signature.

Finally, supply the text of the error message for the default locale that the end user should see if this validation rule fails.

Figure 9-4 Adding an Entity-Level Method Validator

9.3.4 What Happens When You Create an Entity-Level Method Validator

Example 9-2 Simple Entity-Level Method Validator

public boolean validateAssignedDateAfterRequestDate() {
  Date assignedDate = getAssignedDate();
  Date requestDate  = getRequestDate();
  if (assignedDate != null && assignedDate.compareTo(requestDate) < 0) {
    return false;
  }
  return true;
}

9.3.5 What You Might Need To Know About Translating Validation Rule Error Messages

Like the locale-specific UI control hints for entity object attributes, the validation rule error messages are added to the entity object's component message bundle file. These represent the strings for the default locale for your application. To provide translated versions of the validation error messages, follow the same steps as for translating the UI control hints that you've seen in previous chapters.

9.3.6 What You May Need to Know About Referencing the Invalid Value in an Attribute-Level Validation Error Message

The validation error message you supply when adding an attribute-level validation rule can reference the invalid value by referencing the message parameter token "{3}" in the string. The other error parameters supplied are useful for programmatic processing of the ValidationException, but not typically useful in the message string itself.