Using ADF BC Declarative Built-in Rules (Part 1 of 10): Collection Validator

I recently gave an ADF training and realized that many people where having difficulties using the predefined validation rules in ADF Business Components so i decided to write a series of blog posts describing the types of validation available to ADF BC applications.

There are various options for handling validation in ADF applications. You can either define validations on your business service layer or directly on your user interface.

Validations options on your business service layer consist of declarative and programmatic ADF BC validations and validations defined on your database.

Validation options on your user interface consist of built-in validation capabilities on components such as input components and select components. Please make sure though that validations defined on the user interface are also defined on your business service layer to leverage the validations defined on your business service layer when you choose to expose your model in other ways.

Validations can be defined at either the entity level or on a specific attribute. I will be covering in posts that will follow all validation rules. In this post i will explain how you can use the collection validator.

The collection validator is an entity level validator used to compute an aggregate value on an attribute in a child of the current entity object using an aggregate function such as Sum, Count, Average, Min and Max.

I will be using the HR schema to demo the Collection Validator and let's assume the following requirement. A department has a specific budget (let's say 20,000 Euros) comprised of the sum of its employees' salary.

I've created an application, "Collection Validator" using the "Fusion Web Applications (ADF)" template and accepting all the default settings (i just provided my own package name).

I then created the business component objects to use in the collection validator demo which includes two entity objects, one on the "Employees" table and one on the "Departments" table, their respective updatable view objects and an application module. I did all these using the "Business Components from Tables" wizard. And just to tidy up things i refactored all associations into the "associations" package under the "entities" package and refactored all view links into the "links" package under the "views" package.

A collection validator requires an accessor, an association that has been defined for the entity. The "Business Components from Tables" wizard automatically detected the foreign keys defined in the database and created an association for each foreign key, thus all accessor have been created for you automatically. We have two types of associations. The default association type that defines a "soft-type" relationship where entities are related but are not completely dependent and a composition association type that defines a more strict type of association where, in brief, a destination entity is completely dependent on the source.

The collection validator requires a "composition association". I will be using the default association created by the "Business Components from Tables" named "EmpDeptFkAssoc" to mark it as a composite association.

So open the "EmpDeptFkAssoc" association, select the "Relationship" tab and in the "Behavior" section select the check box "Composition Association".

The collection validator will be defined on the "Departments" entity. So open the "Departments" enity and on the "Business Rules" tab, select the "Entity Validators" folder and click on the green plus icon. This will open the "Add Validation" window.

 In the "Type" drop down select the "Collection" validator, in the operation select "Sum" and in the "Accessor" drop down, if you have accepted the default, you should have "Employees1". This is the accessor that got generated from the "EmpDeptFkAssoc" association. In the "Operator" selection i will choose "LessThan" and in the "Compare With" selection i will leave the default which is "Literal Value". In the "Enter Literal Value" box type i will type 20000.

In the "Validation Execution" tab you can control when the validation should be execute (using Groovy expressions which i will cover in another post) and the triggering attributes (to execute the validation only when the selected attribute(s) have been changed).

In the "Failure Handling" tab you can define the severity, either "Error" or "Informational Warning" and the actual failure message. A very cool feature here is tokens. Tokens which are defined in a failure message using the angle brackets {} are placeholders for passing either parameter values or parameter control hints (labels). I've defined the following failure message:

Department {DeptName} has reached it's allowed budget.

JDeveloper automatically detected the "DeptName" token and created it in the "Token Message Expressions" section. In the expression input field just type the name of the department name attribute, "DepartmentName". At runtime this will translate to the actual department name.

Click "OK" to define the business rule and run your Application Module to test the collection validator rule. In the "Business Composer Browser" select the "EmpDeptFkLink1" view link to present the Department record in a form with its Employee records displayed in a detailed table.

Add a new employee in a department and make sure you set the employee's salary to a value that when you sum the salaries of all employees in that department will be greater or equal to 20,000. In my case, i will add a new employee in the "Administration" department with a salary set to 15,600. Click the commit button in the employees detail section and you should get an error with your custom message displayed.

Download sample application: Collection Validator