1. Home
  2. Docs
  3. Chapter 14. Database Design & Engineering
  4. 4. Programmer’s Guide
  5. Using ORM Qualifier

Using ORM Qualifier

Download PDF

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.
    Open class specification
  2. Open the ORM Query tab.
  3. Click Add… in the ORM Qualifiers section.
    Add a ORM Qualifier
  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.
    Defining an ORM Qualifier
  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.

Return Type Method Name Sample Description
Class loadByORMQualifier
(DataType attribute)
loadByGender(char gender) Retrieve the first record that matches the specified value with the attribute defined in the ORM Qualifier.
Class loadByORMQualifier
(PersistentSession session,
DataType attribute)
loadByGender(PersistentSession
session, char gender)
Retrieve the first record that matches the specified value with the attribute defined in the ORM Qualifier and specified session.
Class[] listByORMQualifier (DataType
attribute)
listByGender(char gender) Retrieve the records that match the specified value with the attribute defined in the ORM Qualifier.
Class[] listByORMQualifier
(PersistentSession session,
DataType attribute)
listByGender(PersistentSession
session, char gender)
Retrieve the records that match the specified value with the attribute defined in the ORM Qualifier and specified session.

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 ]