Monday, January 12, 2015

Using ADF BC Declarative Built-in Rules (Part 8 of 10): Regular Expression validator

The last validator in the entity attribute validator set is the "Regular Expression" validator. The "Regular Expression" validator allows you to validate whether an entity attribute either matches or does not matches a regular expression.

You can either use one of the predefined expressions such as the "Email" regular expression or the "Phone" regular expression to validate whether a specific attribute conforms to a specific pattern.

For example, ensure that an email consists of a specific number of predefined characters followed by the "at sign" (@) followed by a specific number of predefined characters followed by the "dot character" (.) followed by a specific number of predefined characters.

So let's see how we can use one of the predefined regular expressions, how you can create your own regular expression and how you can register your custom expressions for re-usability.

For the purpose of demoing the "Regular Expression" validator I have created an ADF Fusion Web Application and created the basic business components that I will be using in this demo; an entity object based on the Employees HR table, a default view object based on the Employees entity object and a default application module.

Next let’s define a "Regular Expression" validator on the Employees entity object to ensure that an employee's email conforms to a specific pattern (<character(s)>@<character(s)>.<characters(s)>). So on the  “Business Rules” tab of the Employees entity object, click on the green plus icon “Create new validator”.  This will open the “Add Validation Rule” editor for defining the validation specifics.

In the “Type” combo select “Regular Expression”, select the attribute that you want to define the validator, in my demo it's the "Email" attribute and then select an operator, either "Matches" or "Not Matches". In my demo I have selected the "Matches" operator.

Under the regular expression section you can either select one of the predefined expressions (currently two, "Email" and "Phone Number(US)") or type your own regular expression. I've selected the "Email" regular expression and clicked on the "Use Pattern" button to generate the pattern.

In the "Failure Handling" tab define a failure message and click "OK". In my example I have used a message token expression to construct a dynamic error message, passing to the failure message the  email value.
If you inspect the Employee’s entity source code you will see that JDeveloper added a RegExpValidationBean tag to the XML entity definition file.

Run the Application module to test your "Regular Expression" validator and try to update an employee's email, for example update Steven King's email from "SKING" to "SKING1". The "Regular Expression" validator should have fired displaying your error message.

Change the email to "". The validation should succeed.

You can of course create your own custom regular expressions. As with the example below, I have defined a regular expression to ensure that an employee's first name consists of only alpha characters and that the first name always starts with an upper case.

What if you wanted to re-use this custom regular expression in other attributes or in other ADF applications? It would be a really bad practice to just copy and paste the same expression in different attributes. What if you wanted to apply a change to your custom expression. It would require you to go through all occurrences and apply the change one by one.

A much better approach would be to register your custom regular expression into the file and your custom regular expression will appear into the list of "Predefined Expressions". This file is located in the o.BC4J subdirectory of the JDeveloper system directory (in my case it's system12., which is a subdirectory of JDeveloper’s user directory (the file in my case is located in "/home/oracle/apps/.jdeveloper/system12.").

Edit the file and add your own custom regular expression.

Restart JDeveloper and go to the Employees entity and create a new regular expression validation on the first name attribute. In the predefined expressions list you should see your own custom regular expression. Select it and click on the use expression button to populate your expression into the "Enter Regular Expression" text area.
Define a failure message and test your custom expression. If you followed my exact steps, try to update an employee's first name to start with a lower case alpha character. The validation should fail.

Download sample application: Regular Expression

No comments:

Post a Comment