Using ORM Qualifier

ORM Qualifier allows you to specify extra data retrieval rules apart from the system pre-defined rules. With ORM Qualifier, you can define retrieval rules that match your business logic. Let’s say your program requires retrieving staff records for specific gender. Without using ORM Qualifier, you will need to retrieve all records, and check record by record to find out the staff that match the gender you look for. With ORM Qualifier, you can retrieve data with specialized methods like listByGender(char gender). This not only makes the code looks tidier but also reduce the chance of making error.

Defining ORM Qualifier in object model

In order to use ORM Qualifier you need to define the qualifier(s) in your object model by selecting the attribute(s) to be included in qualifier.

1. Right click on the ORM Persistable class in which you want to define an ORM Qualifier.
   
2. Open the ORM Query tab.
3. Click Add… in the ORM Qualifiers section.
   
4. In the ORM Qualifier Specification window, enter the name of the ORM Qualifier and select the key attribute. The name you defined will be appended to method names in generated code. For example, an ORM qualifier named Gender will result in generating methods like loadByGender(…), listByGender(…), etc.
   
5. Click OK to confirm.
6. Click OK to return to diagram.

ORM Qualifier (generated code)

ORM Qualifier methods will be generated in Persistent class according to the selected Persistent API. For example, if you selected Factory class as Persistent API, then the following methods will be generated in the StaffFactory class.

Using ORM Qualifier in programming

You can use the qualifier methods to load or list data from database. The following examples show how to load or list via ORM qualifier.

Load

System.out.println(com.PersonFactory.loadByGender('m'));

By executing the code the FIRST occurrence of ‘m’ gender column in the Staff table will be loaded to a Staff object. Here is the result:

Person[ Name=Paul Age=12 Gender=m Dob=1993-11-07 ID=1 ]

List

com.Staff[] staffs = com.StaffFactory.listByGender('f');
for (int i = 0; i < staffs.length; i++){
   System.out.println(staffs[i]);
}

By executing the code, ALL rows that contain ‘f’ in the gender column in the Staff table will be retrieved and stored in an array of Staff object.

Staff[ Name=Erica Age=33 Gender=f Dob=1972-11-07 ID=2 ]
Staff[ Name=Peggy Age=45 Gender=f Dob=1960-11-07 ID=3 ]