OracleAS TopLink - HowTo manipulate objects using Unit of Work

Date: 20/Apr/2004

Table of Contents

Introduction 

Oracle Application Server TopLink is an advanced object-to-relational persistence. It helps to build high performance applications that store persistent data in a relational database. Session queries enables you to read and write objects in a database. The Session class and its subclasses, such as DatabaseSession and UnitOfWork, provide methods to retrieve objects stored in a database. These methods are called query methods, and allow queries to be made in terms of the object model rather than the relational model. In this document we will try to understand simple read and write operations using Toplink.

Prerequisites 

• You must have basic knowledge of Toplink.

Software Requirements 

• Oracle9i Database installed with HR Schema
• OracleAS TopLink 10g

HowTo manipulate objects using OracleAS TopLink 

In this section we will cover how to perform query and DML operations using Toplink

Reading Objects using Toplink

The readAllObjects() method retrieves a Vector of objects from the database. The application must specify the class to read. An expression can be supplied to provide query parameters to identify specific objects within the collection. If no objects matching the criteria are found, an empty Vector is returned. The readAllObjects() method returns the objects unordered.

   UnitOfWork uow = aSession.acquireUnitOfWork();
   Vector empList = uow.readAllObjects(Employees.class);
   uow.release();

The readObject() methods retrieve a single object from the database. The application must specify the class of object to read. If no object matching the criteria is found, null is returned. When looking for a specific object, it is preferable to use the readObject() methods rather than the readAllObjects() method. In the code snippet below an Employee object is retrieved

    UnitOfWork uow = aSession.acquireUnitOfWork();

    // Use an expression to read in the Employee whose employee id is given
    ExpressionBuilder builder = new ExpressionBuilder();
    Expression expression = builder.get("employeeID").equal(empID);      
    Employees emp = (Employees) uow.readObject(Employees.class, expression);
    uow.release();

Adding Objects using Toplink

Units of work are the preferred method of writing to a database in TopLink. To use a unit of work, the application typically acquires an instance of UnitOfWork from the session and registers the persistent objects that are to change. All newly created objects must be registered to be inserted on commit. Once registered any changes to the objects will be commited to the database on commit.

    UnitOfWork uow = aSession.acquireUnitOfWork();
    Employees emp = new Employees();
    emp.setEmployeeId(empID);
    emp.setLastName("Smith");
    emp.setJobId("AC_MGR");    
    ....
    UnitOfWork uow = aSession.acquireUnitOfWork();
    uow.registerObject(emp);
    uow.commit();

Editing Objects using Toplink

Editing objects using Toplink involves first retrieving the object to be modified and then making the required changes. The code snippet below first queries for a given employee and then updates the employee's phone number. Again the modified object is registered with the unit of work.

  UnitOfWork uow = aSession.acquireUnitOfWork();

  ExpressionBuilder builder = new ExpressionBuilder();
  Expression expression = builder.get("employeeID").equal(empID);      
  Employees emp = (Employees) uow.readObject(Employees.class, expression);
      
  // Edit the employee's first name
  emp.setPhoneNumber("650 506 1234");
      
  // Register the modified employee object with unit of work and commit the changes
  uow.registerObject(emp);    
  uow.commit();

Deleting Objects using Toplink

Deleting objects in a unit of work is done using the deleteObject() or deleteAllObjects() method. If an object being deleted has not been registered,
then it is registered automatically. At commit time, SQL is generated to delete the objects, taking database constraints into account. The code snippet below deletes an employee with last name 'Smith'.

   UnitOfWork uow = aSession.acquireUnitOfWork();

   ExpressionBuilder builder = new ExpressionBuilder();
   Expression expression = builder.get("lastName").equalsIgnoreCase("Smith");
   Employees emp = (Employees) uow.readObject(Employees.class, expression);
      
   // Delete the employee object and commit the changes
   uow.deleteObject(emp);
   uow.commit();      

Steps to run the sample 

• Download the jar file from here and extract it.
• Edit <SAMPLE_HOME>/src/META-INF/EmployeeDescriptor.xml, set database parameters in the tag connection-url.
• Add toplink.jar, xmlparserv2.jar, connector.jar and classes12.jar to the classpath. Also ensure that <SAMPLE_HOME>/src/META-INF directory is added to your classpath
• From <SAMPLE_HOME>/src/oracle/otnsamples/toplink directory, Compile the java sources as shown below
  javac -d . *.java
• From <SAMPLE_HOME>/src/oracle/otnsamples/toplink directory, execute the java class as shown below
  java oracle.otnsamples.toplink.EmployeeManagement

Useful References 

• OracleAS TopLink 10g
• OracleAS TopLink Discussion Forum