Skip Headers

# Unit of Work Life Cycle

Previous

Next

TopLink uses the unit of work as follows:

1. The client application acquires a unit of work from a session object.

2. The client application queries TopLink to obtain a cache object it wants to modify, and then registers the cache object with the unit of work.

3. The unit of work registers the object according to the object's change policy. For more information about how change policy affects registration, see "Unit of Work and Change Policy".

   By default, as each object is registered, the unit of work accesses the object from the session cache or database and creates a backup clone and working clone (see "Clones and the Unit of Work"). The unit of work returns the working clone to the client application.

4. The client application modifies the working object returned by the unit of work.

5. The client application (or external transaction controller) commits the transaction.

6. The unit of work calculates the change set for each registered object according to the object's change policy. For more information about how change policy affects change set calculation, see "Unit of Work and Change Policy".

   By default, at commit time, the unit of work compares the working clones to the backup clones and calculates the change set (that is, determines the minimum changes required). The comparison is done with a backup clone so that concurrent changes to the same objects will not result in incorrect changes being identified. The unit of work then attempts to commit any new or changed objects to the database.

   If the commit transaction succeeds, the unit of work merges changes into the shared session cache. Otherwise, no changes are made to the objects in the shared cache. For more details, see "Commit and Rollback Transactions".

   If there are no changes, the unit of work does not start a new transaction.

The Life Cycle of a Unit of Work

Description of "The Life Cycle of a Unit of Work"

Example: Unit of Work Life Cycle shows the default life cycle in code.

Unit of Work Life Cycle

    // The application reads a set of objects from the database
    Vector employees = session.readAllObjects(Employee.class);

    // The application specifies an employee to edit
    . . .
    Employee employee = (Employee) employees.elementAt(index);

    try {
        // Acquire a unit of work from the session
        UnitOfWork uow = session.acquireUnitOfWork();
        // Register the object that is to be changed. Unit of work returns a clone
        // of the object and makes a backup copy of the original employee
        Employee employeeClone = (Employee)uow.registerObject(employee);
        // Make changes to the employee clone by adding a new phoneNumber.
        // If a new object is referred to by a clone, it does not have to be
        // registered. Unit of work determines it is a new object at commit time
        PhoneNumber newPhoneNumber = new PhoneNumber("cell","212","765-9002");
        employeeClone.addPhoneNumber(newPhoneNumber);
        // Commit the transaction: unit of work compares the employeeClone with
        // the backup copy of the employee, begins a transaction, and updates the
        // database with the changes. If successful, the transaction is committed
        // and the changes in employeeClone are merged into employee. If there is an
        // error updating the database, the transaction is rolled back and the
        // changes are not merged into the original employee object
        uow.commit();
    } catch (DatabaseException ex) {
        // If the commit fails, the database is not changed. The unit of work should
        // be thrown away and application-specific action taken
    }
    // After the commit, the unit of work is no longer valid. Do not use further