Chapter 18 - Manipulating Persistent Data with Java

Chapter 18 - Manipulating Persistent Data with Java

Java and .NET persistent code can be generated to manipulate persistent data with the database. This chapter shows the use of the generated Java persistent code by inserting, retrieving, updating and deleting persistent data and demonstrates how to run the generated sample code.

In this chapter:

Introduction
Using ORM-Persistable Class to manipulate persistent data
Using Criteria Class to retrieve persistent data
Using ORM Implementation
Using Entity Bean to manipulate persistent data
Using Transactions in Enterprise JavaBeans

Introduction

With the Smart Development Environment Enterprise Edition (SDE EE) and Professional Edition (SDE PE), you can generate Java persistence code to manipulate the persistent data of the relational database easily.

In the working environment, you are allowed to configure the database connection for your development project. As the database was configured before the generation of persistent code, the ORM persistable Java classes and a set of ORM files are generated together; while the set of ORM files configures the environment for connecting the generated persistence classes and the database. And hence, you are allowed to access the database directly by using the Java persistence class without using any code for setting up the database connection in your project.

There are several mappings in the SDE environment:

Mapping between data model and relational database.
Mapping between data model and object model.
Mapping between object model and persistent code.

And hence, there is an indirect mapping between persistent code and relational database. Each persistence class represents a table in the database and an instance of the class represents one record of the table. In the generated persistence class, there is not only a pair of getter and setter methods for manipulating the corresponding attribute, but also a set of methods for manipulating records with the database.

Using ORM-Persistable Class

Java ORM-Persistable class is generated based on the object model defined in the class diagram. The generated Java persistence code can be identified into two categories - Model API and Persistent API. The Model API refers to the manipulation of attributes of models and associations between models while the Persistent API refers to the persistent code used to manipulate the persistent data with relational database.

Model API

Model API refers to the generated Java persistent code which is capable of manipulating the properties of the object model in terms of attributes and associations.

Manipulating Attributes

In order to specify and retrieve the value to the attributes of the ORM-Persistable class, a pair of getter and setter methods for each attribute is generated to the Java ORM-Persistable class.

Table shows the method summary of the persistence class to be used for inserting a row to database.

Return Type	Method Name	Description
void	setAttribute(DataType value)	Set the value to the property of an instance.
DataType	getAttribute()	Get the value of the property of an instance.

Table 18.1

Remark:

Attribute should be replaced by the name of the generated persistence class.
DataType should be replaced by the data type of the attribute defined in the object model.

Example:


Figure 18.1 - ORM Persisteable Class mapping

From the above example, an ORM-Persistable object model of Customer maps to an ORM-Persistable Java class generated with the getter and setter methods for each attribute.

To set the values of properties of the Customer object, the following lines of code should be used.

customer.setCustomerName("Joe Cool");
customer.setAddress("1212, Happy Building");
customer.setContactPhone("23453256");
customer.setEmail("joe@cool.com");

To get the values of properties of the Customer object:

String name = customer.getCustomerName();
String address = customer.getAddress();
String phone = customer.getContactPhone();
String email = customer.getEmail();

Manipulating Association

When mapping a navigable association to persistence code, the role name of the association will become an attribute of the class. A pair of getter and setter methods for the role will be generated to the persistence class so as to manipulate its role associated with its supplier class. There are two ways in manipulating association, including Smart Association Handling and Standard Association Handling.

Smart Association Handling

Using smart association handling, the generated persistent code is capable of defining one end of the association which updates the other end of association automatically in a bi-directional association regardless of multiplicity. Examples are given to show how the generated persistent code manipulates the one-to-one, one-to-many and many-to-many associations with smart association handling.

One-to-One Association

In order to manipulate the directional association, implement the program with the following steps:

Set the properties of role name of the object.

Table shows the method summary of the persistence class to be used for setting the directional association.

Return Type	Method Name	Description
void	setRoleName(Class value)	Set the value to the role of an instance.

Table 18.2

Remark:

RoleName should be replaced by the role of the navigable association.
Class should be replaced by the data type of the supplier class in the navigable association.

Example:


Figure 18.2 - Mapping one-to-one association

From the above example, an ORM-Persistable object model of Software maps to an ORM-Persistable Java class with an attribute of role, "contains" in the association typed as its associated persistence class, License. Meanwhile, the object model of License maps to a Java class with an attribute of role, "belongsTo" typed as Software. It specifies the association that Software contains a particular License and a License belongs to particular software.

To manipulate the association, the following lines of code should be implemented.

Software software = Software.createSoftware();
License license = License.createLicense();
license.setBelongsTo(software);

In the above association, the primary key of the Software table will become a foreign key in License table when transforming to data model. Thus, after executing the lines of code, the primary key of the software will be referenced as a foreign key of the license record.


Figure 18.3 - Code for one-to-one association

It is a bi-directional association with smart association handling. The association link can be created by setting either the role of Software, or the role of License, i.e. setting one of the roles builds up a bi-directional association automatically. It is not required to set one role after the other. Hence, both license.setBelongsTo(software) and software.setContains(license) result in building up the bi-directional association.

One-to-Many Association

In a bi-directional one-to-many association, a class has multiplicity of one while the other has many. If the class has multiplicity of many, the corresponding collection class will be automatically generated for manipulating the objects. When transforming the association to persistent code, the role name will map to an attribute with data type of a collection class. For more detailed information on the collection class, refer to the description in Using Collection section.

A bi-directional one-to-many association is shown below.


Figure 18.4 - One-to-Many Association

To manipulate the bi-directional one-to-many association, you can create the association in one of the two ways:

Set the properties of role with an instance of the associated class; i.e. classB.setRoleB(classA)
Add the objects to the collection of the associated class; i.e. classA.roleA.add(classB)

where classA is an object of ClassA; classB is an object of ClassB;
roleA is the collection of ClassB; setRoleB is the setter method of property, roleB.

After specifying the association, the value of primary key of the object of ClassA will be referenced as a foreign key of the associated object of ClassB.

Setting the property of role

For information on setting the properties of role, refer to the description in the One-to-One Association section.

Adding objects to the collection

In order to add an object to the collection, implement the program with the following steps:

Create a new instance of the class which associates with more than one instance of associated class.
Create a new object of the associated class.
Add a new object or an existing object of the associated class to the collection belonging to the class.

Table shows the method summary of the collection class to be used for adding a new object to it

Return Type	Method Name	Description
void	add(Class value)	Add a new object to the collection of the associated class.

Table 18.3

Remark:

Class should be replaced by the name of the associated class.

Example:


Figure 18.5 - One-to-many association

From the above example, an ORM-Persistable object model of PurchaseOrder maps to an ORM-Persistable Java class with an attribute of role, "PlacedBy" in the association typed as an instance of Customer, specifying that the particular purchase order is placed by a particular customer. Moreover, the object model of Customer maps to a Java class with an attribute of role, "Places" in the association typed as a collection class, PurchaseOrderSetCollection which manipulates instances of PurhcaseOrder.

To add a PurchaseOrder object to the collection of PurchaseOrder, the following lines of code should be implemented.

Customer customer = Customer.createCustomer();
PurchaseOrder po = PurchaseOrder.createPurchaseOrder();
customer.places.add(po);

After executing these lines of code, an object is added to the collection representing the association. When inserting records to the database tables, the primary key of the customer will be referenced to as the foreign key of the purchase order record.

The alternative way to create the association is using
po.setPlacedBy(customer);


Figure 18.6 - Code for one-to-many association

Retrieving objects from the collection

In order to retrieve an object from the collection, implement the program with the following steps:

Retrieve an instance of the class which associates with more than one instance of associated class.
Get the collection from the class, and convert the collection into an array.

Table shows the method summary of the collection class to convert the collection into an array.

Return Type	Method Name	Description
Class[]	toArray()	Convert the collection into an array which stores the objects of the associated class.

Table 18.4

Remark:

Class should be replaced by the name of the associated class.

Example:

Refer to the example of the one-to-many association between the ORM-Persistable object models of Customer and PurchaseOrder, implement the following lines of code to retrieve a collection of PurchaseOrder objects from the customer.

Customer customer = Customer.loadByName("Joe Cool");
PurchaseOrder[] orders = customer.places.toArray();

After executing these lines of code, the purchase order records associated with the customer are retrieved and stored in the array.

Retrieve the customer record by using the loadByName() method which is the method provided by the persistent API. For more information on retrieving persistent object, refer to the Persistent API section.

Many-to-Many Association

When transforming a many-to-many association between two ORM-Persistable classes, the corresponding persistent and collection Java class will be generated simultaneously such that the collection class is able to manipulate its related objects within the collection.

In order to specify the many-to-many association, add the objects to the corresponding collection of the associated class. For information on adding objects to the collection, refer to the description in the One-to-Many Association section.

In addition, a many-to-many association in the object model is transformed to data model by generating a Link Entity to form two one-to-many relationships between two generated entities. The primary keys of the two entities will migrate to the link entity as the primary/foreign keys. When specifying the association by adding objects to the collection, the primary key of the two related instances will be inserted as a pair for a row of the Link Entity automatically.

Example:


Figure 18.7 - Mapping many-to-many association

Four classes including Student, StudentSetCollection, Course and CourseSetCollection are generated from the above object model.

By executing the following lines of code:

Student student = Student.createStudent();
student.setStudentID(0021345);
student.setName("Wenda Wong");
Course course = Course.createCourse();
course.setCourseCode(5138);
course.setName("Object Oriented Technology");
course.setTutor("Kelvin Woo");
course.contains.add(student);

Both the Student table and Course table are inserted with a new record. After specifying the association by course.contains.add(student) the corresponding primary keys of student record and course record migrate to the Student_Course Link Entity to form a row of record.


Figure 18.8 - Code for many-to-many association

Using Collection

A collection represents a group of objects. Some collections allow duplicate objects and others do not. Some collections are ordered and other unordered. A collection class thus supports the manipulation of the objects within a collection. There are four types of collection class supported, including set, bag, list and map.

The type of collection can be specified in advance of generating persistence code. Refer to Specifying Collection Type in the Object Model chapter for more information.

Set

Set is an unordered collection that does not allow duplication of objects. It is the default type for unordered collection.

Table shows the method summary of the collection class typed as Set.

Return Type	Method Name	Description
void	add(Class value)	Add the specified persistent object to this set if it is not already present.
void	clear()	Remove all of the persistent objects from this set.
boolean	contains(Class value)	Return true if this set contains the specified persistent object.
Iterator	getIterator()	Return an iterator over the persistent objects in this set.
boolean	isEmpty()	Return true if this set contains no persistent object.
void	remove(Class value)	Remove the specified persistent object from this set if it is present.
int	size()	Return the number of persistent objects in this set.
Class[]	toArray()	Return an array containing all of the persistent objects in this set.

Table 18.5

Remark:

Class should be replaced by the persistence class.

Bag

Bag is an unordered collection that may contain duplicate objects.

Table shows the method summary of the collection class typed as Bag.

Return Type	Method Name	Description
void	add(Class value)	Add the specified persistent object to this bag.
void	clear()	Remove all of the persistent objects from this bag.
boolean	contains(Class value)	Return true if this bag contains the specified persistent object.
Iterator	getIterator()	Return an iterator over the persistent objects in this bag.
boolean	isEmpty()	Return true if this bag contains no persistent object.
void	remove(Class value)	Remove the specified persistent object from this bag.
int	size()	Return the number of persistent objects in this bag.
Class[]	toArray()	Return an array containing all of the persistent objects in this bag.

Table 18.6

Remark:

Class should be replaced by the persistence class.

List

List is an ordered collection that allows duplication of objects. It is the default type for ordered collection.

Table shows the method summary of the collection class typed as List.

Return Type	Method Name	Description
void	add(Class value)	Append the specified persistent object to the end of this list.
void	add(int index, Class value)	Insert the specified persistent object at the specified position in this list.
void	clear()	Remove all of the persistent objects from this list.
boolean	contains(Class value)	Return true if this list contains the specified persistent object.
Class	get(int index)	Return the persistent object at the specified position in this list.
Iterator	getIterator()	Return an iterator over the persistent objects in this list in proper sequence.
boolean	isEmpty()	Return true if this list contains no persistent object.
void	remove(Class value)	Remove the first occurrence in this list of the specified persistent object.
Class	remove(int index)	Remove the persistent object at the specified position in this list.
int	set(int index, Class value)	Replace the persistent object at the specified position in this list with the specified persistent object.
int	size()	Return the number of persistent objects in this list.
Class[]	toArray()	Return an array containing all of the persistent objects in this list in proper sequence.

Table 18.7

Remark:

Class should be replaced by the persistence class.

Map

Map is an ordered collection which is a set of key-value pairs while duplicate keys are not allowed.

Table shows the method summary of the collection class typed as Map.

Return Type	Method Name	Description
void	add(Object key, Class value)	Add the specified persistent object with the specified key to this map.
void	clear()	Remove all mappings from this map.
boolean	contains(Object key)	Return true if this map contains a mapping for the specified key.
Class	get(Object key)	Return the persistent object to which this map maps the specified key.
Iterator	getIterator()	Return an iterator over the persistent objects in this map.
Iterator	getKeyIterator()	Return an iterator over the persistent objects in this map.
boolean	isEmpty()	Return true if this map contains no key-value mappings.
void	remove(Object key)	Remove the mapping for this key from this map if it is present.
int	size()	Return the number of key-value mappings in this map.
Class[]	toArray()	Return an array containing all of the persistent objects in this map.

Table 18.8

Remark:

Class should be replaced by the persistence class.

Standard Association Handling

With standard association handling, when updating one end of the association, the generated persistent code will not update the other end of a bi-directional association automatically. Hence, you have to define the two ends of the bi-directional association manually to maintain consistency. Examples are given to show how to manipulate the one-to-one, one-to-many and many-to-many associations with standard association handling.

One-to-One Association

In order to manipulate the directional association, implement the program with the following steps:

Set the properties of role name of the object.

Table shows the method summary of the persistence class to be used for setting the directional association.

Return Type	Method Name	Description
void	setRoleName(Class value)	Set the value to the role of an instance.

Table 18.9

Remark:

RoleName should be replaced by the role of the navigable association.
Class should be replaced by the data type of the supplier class in the navigable association.

Example:


Figure 18.9 - Mapping one-to-one association

To manipulate the association, the following lines of code should be implemented.

Software software = Software.createSoftware();
License license = License.createLicense();
license.setBelongsTo(software);
software.setContains(license);


Figure 18.10 - Code for one-to-one association

It is a bi-directional association with standard association handling. The association link must be created by setting both the roles of Software and License.

One-to-Many Association

In a bi-directional one-to-many association, a class has multiplicity of one while the other has many. When transforming the association to persistent code, the role name will map to an attribute of the class with data type of a Java collection class. The type of collection is specified in the object model, refer to the description in Using Collection section for mapping the type of collection with Java collection class.

A bi-directional one-to-many association is shown below.


Figure 18.11 - An one-to-many association

With standard association handling, you have to create the association with the following steps in order to manipulate the bi-directional one-to-many association:

Set the properties of role with an instance of the associated class; i.e. classB.setRoleB(classA)
Add the objects to the collection of the associated class; i.e. classA.getRoleA().add(classB)

where classA is an object of ClassA; classB is an object of ClassB;
getRoleA returns the collection of ClassB; setRoleB is the setter method of property, roleB.

After specifying the association, the value of primary key of the object of ClassA will be referenced as a foreign key of the associated object of ClassB.

Setting the property of role

For information on setting the properties of role, refer to the description in the One-to-One Association section.

Adding objects to the collection

In order to add an object to the collection, implement the program with the following steps:

Create a new instance of the class which associates with more than one instance of associated class.
Create a new object of the associated class.
Add a new object or an existing object of the associated class to the collection belonging to the class.

Example:


Figure 18.12 - Mapping one-to-many association with using Collection

From the above example, an ORM-Persistable object model of PurchaseOrder maps to an ORM-Persistable Java class with an attribute of role, "PlacedBy" in the association typed as an instance of Customer, specifying that the particular purchase order is placed by a particular customer. Moreover, the object model of Customer maps to a Java class with an attribute of role, "Places" in the association typed as a collection, Set which is the specified type of collection in the model manipulating instances of PurhcaseOrder.

To add a PurchaseOrder object to the collection of PurchaseOrder, the following lines of code should be implemented.

Customer customer = Customer.createCustomer();
PurchaseOrder po = PurchaseOrder.createPurchaseOrder();
customer.getPlaces().add(po);
po.setPlacedBy(customer);


Figure 18.13 - Code for one-to-many association with using Collection

Retrieving objects from the collection

In order to retrieve an object from the collection, implement the program with the following steps:

Retrieve an instance of the class which associates with more than one instance of associated class.
Get the collection from the class, and convert the collection into an object array.

Example:

Customer customer = Customer.loadByName("Joe Cool");
Object[] orders = customer.getPlaces().toArray();

After executing these lines of code, the purchase order records associated with the customer are retrieved and stored in the object array.

Many-to-Many Association

When transforming a many-to-many association between two ORM-Persistable classes with standard association handling, the role names will map to one type of collection defined in the object model. In order to specify the many-to-many association, add the objects to the corresponding collection of the associated class. For information on adding objects to the collection, refer to the description in the One-to-Many Association section.

Example:


Figure 18.14 - Mapping Many-to-many association with using Collection

With standard association handling, only two classes including Student and Course are generated from the above object model.

By executing the following lines of code:

Both the Student table and Course table are inserted with a new record. After specifying the association by course.getContains().add(student) and student.getEnrols().add(course), the corresponding primary keys of student record and course record migrate to the Student_Course Link Entity to form a row of record.


Figure 18.15 - Code for many-to-many association with using Collection

Using Collection

With standard association handling, the role name which associates with more than one instance of the supplier class is transformed into one type of Java collection class. The type of collection can be specified before the generation of code, refer to the description of Specifying Collection Type in the Object Model chapter.

The following table shows the mapping between the collection type defined in the association specification and the Java collection class.

Collection Type	Java Collection Class
Set	java.util.Set
Bag	java.util.Collection
List	java.util.List
Map	java.util.Map

Table 18.10

Persistent API

Persistent API refers to the persistent code used to manipulate the persistent data. There are four types of persistent API available for generating the Java persistence code. The four types of persistent API, which include Static Method, Factory Class, POJO and Data Access Object (DAO), are capable of manipulating the persistent data with the relational database, i.e., inserting, retrieving, updating and deleting records.

Using Static Method

Using static method persistent API, a persistence class for the ORM-Persistable class is generated with static methods which is capable of creating, retrieving persistent object and persisting data. The following class diagram shows the dependency relationship between the client program and the generated persistence class.


Figure 18.16 - Class with static methods

In the above class diagram, the PersistentObject refers to the ORM-Persistable class defined in the class diagram. For example, the ORM-Persistable class, Customer persists with the Customer data in the Customer table.

Example:


Figure 18.17 - Mapping with static methods

From the above example, a Customer persistence class is generated with a set of methods supporting the database manipulation.

In this section, it introduces how to use the static methods of the generated persistence classes to manipulate the persistent data with the relational database.

Creating a Persistent Object

As a persistence class represents a table in the database and an instance of the class represents a record of the table, creating a persistent object in the application system is the same as adding a row of new record to the table.

In order to insert a new row to the database table, implement the program with the following steps:

Create a new instance of the class.
Set the properties of the object.
Insert the object as a row to the database.

Table shows the method summary of the persistence class

Return Type	Method Name	Description
Class	createClass()	Create a new instance of the class.
void	setAttribute(DataType value)	Set the value to the property of an instance.
boolean	save()	Insert the object as a row to the database table.

Table 18.11

Remark:

Class should be replaced by the name of the generated persistence class.
Attribute should be replaced by the name of the attribute.
DataType should be replaced by the data type of the attribute defined in the object model.

Example:


Figure 18.18 - Mapping ORM Persistent Class

From the above example, an ORM-Persistable object model of Customer maps to an ORM-Persistable Java class generated with methods for creating a new instance and inserting the instance as a row of the database table.

To insert a new Customer record to the table, Customer of the database, the following lines of code should be implemented.

Customer customer = Customer.createCustomer();
customer.setCustomerID(3);
customer.setCustomerName("Peter Chan");
customer.setAddress("6C, Pert Court");
customer.setEmail("peter.chan@gmail.com");
customer.save();

After executing these lines of code, a row of record is inserted to the database table.

An alternative way to create a new instance of the class is using the new operator:
Class c = new Class();

From the above example, Customer customer = Customer.createCustomer() can be replaced by Customer customer = new Customer() to create a Customer object.


Figure 18.19 - Save a Data object to the database

Loading a Persistent Object

As the database table is represented by a persistence class, a record of the table can thus be represented by an instance. A record retrieved from the table will be stored as an object.

In order to retrieve a record from the database table, you have to specify the condition for finding the record. To retrieve a record, implement the program with the following steps:

Specify the condition for searching the record.
Load the retrieved record to an object.

Table shows the method summary of the persistence class to be used for retrieving a record from database.

Return Type	Method Name	Description
Class	loadClassByORMID(DataType PrimaryKey)	Retrieve a record matching with the specified value of primary key.
Class	loadClassByORMID(PersistentSession session, DataType PrimaryKey)	Retrieve a record matching with the specified value of primary key and specified session.
Class	loadClassByQuery(String condition, String orderBy)	Retrieve the first record matching the user defined condition while the matched records are ordered by a specified attribute.
Class	loadClassByQuery(PersistentSession session, String condition, String orderBy)	Retrieve the first record matching the user defined condition and specified session while the matched records are ordered by a specified attribute.

Table 18.12

Remark:

Class should be replaced by the name of the persistence class.
DataType should be replaced by the data type of the attribute defined in the object model.

Example:


Figure 18.20 - Mapping with load method

From the above example, an ORM-Persistable object model, Customer maps to an ORM-Persistable Java class generated with methods for retrieving a matched record.

To retrieve a record from the Customer table, the following line of code should be implemented.

Loading an object by passing the value of primary key:

Customer customer = Customer.loadCustomerByORMID(2);

Loading an object by specifying a user defined condition:

Customer customer = Customer.loadCustomerByQuery("Customer.CustomerName='Peter'", "Customer.CustomerName");

After executing the code, a matched row is retrieved and loaded to a Customer object.


Figure 18.21 - Load record from database

Updating a Persistent Object

As a record can be retrieved from the table and loaded to an object of the persistence class, the record is allowed to update by simply using the setter method of the property.

In order to update a record, you have to retrieve the row being updated, update the value by setting the property to the database. To update the record, implement the program with the following steps:

Retrieve a record from database table and load as an object.
Set the updated value to the property of the object.
Save the updated record to the database.

Table shows the method summary of the persistence class to be used for updating a record.

Return Type	Method Name	Description
void	setAttribute(DataType value)	Set the value to the property of an instance.
boolean	save()	Update the value to database.

Table 18.13

Remark:

Attribute should be replaced by the name of the attribute.
DataType should be replaced by the data type of the attribute defined in the object model.

Example:


Figure 18.22 - Mapping with save methods

From the above example, an ORM-Persistable object model, Customer maps to an ORM-Persistable Java class generated with the methods for setting the properties and updating the row.

To update a Customer record, the following lines of code should be implemented.

customer.setCustomerName("Peter Pang");
customer.save();

After executing the above lines of code, the customer name is updated to "Peter Pang" in the database.


Figure 18.23 - Code for update record

Deleting a Persistent Object

As a record can be retrieved from the table and loaded to an object of the persistence class, the record can be deleted by simply using the delete method of the persistence class.

In order to delete a record, implement the program with the following steps:

Retrieve a record from database table and load as an object.
Delete the retrieved record.

Table shows the method summary of the persistence class to be used for

Return Type	Method Name	Description
boolean	delete()	Delete the current instance.

Table 18.14

Example:


Figure 18.24 - Mapping delete methods

From the above example, an ORM-Persistable object model, Customer maps to an ORM-Persistable Java class generated with the methods for deleting the specified record from the database.

To delete a Customer record, the following lines of code should be implemented.

Customer customer = Customer.loadCustomerByORMID(2);
customer.delete();

After executing the above code, the specified customer record is deleted from the database.


Figure 18.25 - Code for delete record

Querying

For most of the database application, the database is enriched with information. Information may be requested from the database so as to performing an application function, such as retrieving the unit price of products for calculating the total amount for a purchase order.

As the persistence class represents a table, the ORM-Persistable Java class is generated with methods for retrieving information from the database.

Loading a Collection of Persistent Objects

As the database table usually contains many records, you may want to query the tables by a specified condition. The generated persistent code supports querying the database, the matched records will be retrieved and loaded as an object array.

In order to retrieve records from the table, you have to specify the condition for querying. To retrieve a number of records, implement the program with the following steps:

Specify the condition for searching the record.
Load the retrieved records as an object array.

Table shows the method summary of the persistence class to be used for retrieving records from database table.

Return Type	Method Name	Description
Class[]	listClassByQuery(String condition, String orderBy)	Retrieve the records matched with the user defined condition and ordered by a specified attribute.
Class[]	listClassByQuery(PersistentSession session, String condition, String orderBy)	Retrieve the records matched with the user defined condition and specified session and ordered by a specified attribute.

Table 18.15

Remark:

Class should be replaced by the name of the persistence class.

Example:


Figure 18.26 - Mapping with list methods

From the above example, an ORM-Persistable object model, Customer maps to an ORM-Persistable Java class generated with methods for retrieving records.

To retrieve records from the Customer table, the following line of code should be implemented.

Customer[] customer = Customer.listCustomerByQuery("Customer.CustomerName='Peter'", "Customer.CustomerName");

After executing the code, the matched rows are retrieved and loaded to an object array of Customer.


Figure 18.27 - Code for retrieve a list of records

Using ORM Qualifier

ORM Qualifier is an additional feature which allows you to specify the extra data retrieval rules apart from the system pre-defined rules. The ORM Qualifier can be defined in order to generate persistence code. Refer to Defining ORM Qualifier in the Object Model chapter for more information.

By defining the ORM Qualifier in a class, the persistence class will be generated with additional data retrieval methods, load and list methods.

Table shows the method summary generated by defining the ORM Qualifier.

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

Table 18.16

Remark:

Class should be replaced by the name of the persistence class.
ORMQualifier should be replaced by the Name defined in the ORM Qualifier.
DataType should be replaced by the data type of the attribute which associated with the ORM Qualifier.
attribute is the specified value to be used for querying the table.

Example:


Figure 18.28 - Mapping with load and list by qualifier

In the above example, a customer object model is defined with an ORM Qualifier named as Name and qualified with the attribute, CustomerName.

To query the Customer table with the ORM Qualifier in one of the two ways

By Load method

Customer customer = Customer.loadByName("Peter");

After executing the code code, the first occurrence of "Peter" in the CustomerName column in the Customer table will be loaded to the object identified as customer.


Figure 18.29 - Code for retrieve a record by qualifier

By List method

Customer[] customer = Customer.listByName("Peter");

After executing the code, all rows which contain "Peter" in the CustomerName column in the Customer table will be retrieved and stored in an array of Customer object.


Figure 18.30 - Code for retrieve a list of records by qualifier

Using Criteria Class

When generating the persistence class for each ORM-Persistable class defined in the object model, the corresponding criteria class can also be generated. Criteria class is a helper class which provides an additional way to specify the condition to retrieve records from the database. Refer to Using Criteria Class section for more detailed information on how to specify the conditions to query the database by the criteria class.

You can get the retrieved records from the criteria class in one of the two ways:

Use the retrieval methods of the criteria class.

For information on the retrieval methods provided by the criteria class, refer to the description of Loading Retrieved Records section.

Use the retrieval by criteria methods of the persistence class.

Table shows the method summary generated to the persistence class to retrieve records from the criteria class.

Return Type	Method Name	Description
Class	loadClassByCriteria(ClassCriteria value)	Retrieve the single record that matches the specified conditions applied to the criteria class.
Class[]	listClassByCriteria(ClassCriteria value)	Retrieve the records that match the specified conditions applied to the criteria class.

Table 18.17

Remark:

Class should be replaced by the name of the persistence class.

Example:


Figure 18.31 - Mapping with dependency

To retrieve records from the Criteria Class in one of the two ways:

By Load method

CustomerCriteria customerCriteria = new CustomerCriteria();
customerCriteria.CustomerName.like("%Peter%");
Customer customer = Customer.loadCustomerByCriteria(customerCriteria);

After executing the code, the first occurrence of "Peter" in the CustomerName column in the Customer table will be loaded to the object identified as customer.

By List method

CustomerCriteria customerCriteria = new CustomerCriteria();
CustomerCriteria.CustomerName.like("%Peter%");
Customer[] customer = Customer.listCustomerByCriteria(customerCriteria);

After executing the code, all rows which contain "Peter" in the CustomerName column in the Customer table will be retrieved and stored in an array of Customer object.

Using Factory Class

Using factory class persistent API, not only the persistence class will be generated, but also the corresponding factory class for each ORM-Persistable class. The generated factory class is capable of creating a new instance of the persistence class, which assists in inserting a new record to the database, and retrieving record(s) from the database by specifying the condition for query. After an instance is created by the factory class, the persistence class allows setting the values of its property and updating into the database. The persistence class also supports the deletion of records.

The following class diagram shows the relationship between the client program, persistent object and factory object.


Figure 18.32 - Mapping with using Factory Class

In the above class diagram, the PersistentObject refers to the ORM-Persistable class defined in the class diagram while the PersistentObjectFactory refers to the generated factory class of the ORM-Persistable class. For example, the CustomerFactory class creates and retrieves Customer persistent object while the ORM-Persistable class, Customer persists with the Customer data in the Customer table.

Example:


Figure 18.33 - Class Diagram with Factory Class

From the above example, the CustomerFactory class supports the creation of Customer persistent object, the retrieval of Customer records from the Customer table while the Customer persistence class supports the update and deletion of customer record.