Using Descriptors in an Application

After creating the descriptor files, you must write Java code to register the files with the OracleAS TopLink session. After registering the files, the application can read and write Java class instances from the database.

To read instances from the database, use the database session object.
To write instances to the database, use a unit of work object.

Transactions and Units of Work

A transaction is a set of database operations that can be either committed (accepted) or rolled back (undone). Transactions can be as simple as inserting an object into a database, but also allow complex operations to be committed or rolled back as a single unit. Unsuccessful transactions can be discarded, leaving the database in its original state.

A unit of work is an object that simplifies the transaction process and stores transaction information for its registered persistent objects. The unit of work enhances database commit performance by updating only the changed portions of an object. Units of work are the preferred method of writing to a database in OracleAS TopLink.

To use a unit of work, create an instance of UnitOfWork and register the desired persistent objects. The registering process returns clones that can be modified. After changes are made to the clones, use the commit() method to commit an entire transaction. The unit of work inserts new objects or updates changed objects in the database, as Figure B-29 illustrates.

If an error occurs when writing the objects to the database, a DatabaseException is thrown, and the unit of work is rolled back to its original state. If no database error occurs, the original objects are updated with the new values from the clones.

Figure B-29 Unit of Work Example

Description of the illustration uow.gif

Reading and Writing Java Class Instances

Sessions can read instances from the database using the readObject() method. Database sessions can write instances to the database using the writeObject() method, but note that write is neither required nor used when employing a unit of work. An application typically uses the session to read the instances of a given class from the database and determines which of the instances require changes. The instances requiring changes are then registered with a unit of work. After the changes have been made, the unit of work is used to commit only the changed objects to the database.

This model provides the optimum performance for most applications. Read performance is optimized by using the session because the unit of work does not have to keep track of objects that do not change. Write performance is optimized because the unit of work keeps track of transaction information and writes only the changed portions of an instance to the database.

Using a Unit of Work to Write an Object

After the descriptors have been registered with the session, you are ready to read and write objects to the database. Objects are registered with a unit of work and then committed to the database.

The code fragment in the following example is a continuation of the fragment in Example B-3 and uses the session created there.

Example B-4 Unit of Work

The following code example illustrates using a unit of work to write an object.

//Create an Employee object for the company president, as well as the associated personal information objects.
Employee president = new Employee();

Address presidentHome = new Address();
presidentHome.setStreet("601-1140 Meadowlands Dr.");
presidentHome.setCity("Ottawa");
presidentHome.setPostalCode("K2E 6J6");
presidentHome.setProvince("ON");
presidentHome.setCountry("Canada");

PhoneNumber homePhone = new PhoneNumber();
homePhone.setType("Home");
homePhone.setAreaCode("555");
homePhone.setNumber("555-1234");

PhoneNumber businessPhone = new PhoneNumber();
businessPhone.setType("Business");
businessPhone.setAreaCode("555");
businessPhone.setNumber("555-5678");

president.setName("John Smith");
president.setAddress(presidentHome);
president.addPhoneNumber(homePhone);
president.addPhoneNumber(businessPhone);

//Register objects with a new unit of work. Registered objects will return a clone which should be used to make changes to the object.
UnitOfWork unitOfWork;
unitOfWork = session.acquireUnitOfWork();
Employee tempPresident = (Employee)unitOfWork.registerObject(president);

//Register any other objects, or change registered objects.
tempPresident.setName("Johnny Smith");

//Commit the objects to the database.
unitOfWork.commit();

Using a Session to Read an Object

To change the information in the database, the application must create an Expression that contains information about the query to be made. The session then searches the database for an object that matches the query and returns the instance. The returned object is registered with the unit of work, and the application makes changes to the object. The application then commits the changes to the database using the commit() method.

Example B-5 Session

The following code example illustrates using a session to read an object.

//Import the Expression classes.
import oracle.toplink.expressions.*;

//Import the other classes. Create a session and login. Create a query expression to find the database object.
ExpressionBuilder builder = new ExpressionBuilder();
Expression expression = builder.get("name").equal("John Smith");

//Read the object from the database using the query expression.
Employee president = (Employee) session.readObject(Employee.class, expression);

//Register the object with a new unit of work.
UnitOfWork unitOfWork = session.acquireUnitOfWork();
Employee tempPresident = (Employee)unitOfWork.registerObject(president);

//Make the change to the object.
tempPresident.setName("Johnny Smith");

//Commit the change to the database. Only the NAME field is actually updated.
unitOfWork.commit();