Tuesday, April 15, 2014

Using ADF BC Declarative Built-in Rules (Part 2 of 10): Unique Key Validator

Following my previous post Using ADF BC Declarative Built-in Rules: Collection Validator I would like to cover another declarative build-in rule, the "Unique Key Validator".

The "Unique Key Validator" is an entity level validator that ensures that primary key values for an entity object are always unique. For example, in the Employees table in the HR schema you can create a "Unique Key Validator" on the "EMPLOYEE_ID" (since this is the primary key) to ensure that an employee should have a unique employee id. If a key (in this example an employee id) is found in either the entity's cache or the database a "TooManyObjectsException" is thrown. Let's see how you can define a "Unique Key Validator" on the EMPLOYEE_ID column of the EMPLOYEES HR table.

I've created a new ADF Application "UniqueKeyValidatorDemo" using the "Fusion Web Application (ADF)" template and using the "Business Components from Tables" wizard I've created an Entity "EmployeesEO" based on the EMPLOYEES table, a view "EmployeesVO" based on the "EmployeesEO" entity and an Application Module "UniqueKeyValidatorAM".

Business rules are defined on the entity object so to create a 'Unique Key Validator" open the "EmployeesEO" and in the "Business Rules" tab click the green plus icon "Create new validator".

From the "Add Validation Rule" window select "UniqueKey" in the "Type" drop down and select the "EmpEmpIdPk(Employee_ID)" key.

In the "Failure Handling" tab define a failure message and click "OK". In my example I have used three message token expressions to construct a dynamic error message, passing to the failure message the "Employee Id" (using the newValue expression to get the value being validated), "First Name" and "Last Name".

To test your newly defined "Unique Key Validator" run the Application module and and try to update one of the employees using an existing employee id. For example, try to update Steven King's employee id to 101. You should get your custom dynamic error message displayed.

What if you wanted to enforce a "Unique Key Validator" on a non-primary key attribute? For example, what if you wanted to ensure that every employee should have a unique email address. The The "Unique Key Validator" can be applied on non-primary key attributes known as "alternate keys".

You can create an alternate key using the entity's "General" tab. So in our case, let's create an alternate key for the "Email" attribute of the "EmployeesEO" entity object.  Under the "Alternate Keys" section click on the green plus icon "Add Alternate Key".

 In the "Define Alternate Key" window specify a name in the "Alternate key Name" field (in my case it's "EmailAltKey") and shuffle the "Email" attribute from the "Available" list to the "Selected" list and click "OK".

To define a "Unique Key Validator" based on the newly created email alternate key go to the "Business Rules" tab and click on the green plus button "Create new validator" (just as you did above with the "Unique Key Validator" defined on the Employee Id primary key). In the "Add Validation Rule" window select "UniqueKey" in the "Rule" drop down and select alternate key that you have created above.

Define a failure message using the "Failure Handling" tab and click "OK".
Run your application module and update an employee's email  with an existing email. For example, update Steven King's email to "NKOCHHAR". You should get an error message saying that the email is already in use.

Download sample application: Unique Key Validator

No comments:

Post a Comment