This covers starting and stopping transactions. It include how within the transaction you can add, delete and update domain objects.

Contents

1. Starting A Transaction
2. Committing A Transaction
3. Rolling Back Transaction
4. Adding a new Persistent Object
5. Updating a Persistent Object
6. Deleting a Persistent Object

The UOW (Unit of Work) is the application developers interface to the persistence layer. Through this all writes, updates and deletes are executed.

The creation of the UOW marks the start of a transaction. An UOW will acquire a Connection from the connection pool. An UOWException will be thrown if the database connect info is incorrect, or if the preload classes do not match the corresponding mapping files, or if a Connection is not available, or if the JdbcSecurityPlugin throws an error.

UOW uow = new UOW();

Invoking the commit method of the UOW marks the completion of a transaction.

Objects that have been added, objects that have been deleted, and objects that have been updated, will all be persisted via an invocation of this method. After a successful commit, the UOW will free up its connection to the database, and should not be used again.

UOW uow = new UOW();
...
...
uow.commit();

Invoking the rollback method of the UOW is another way of completing a transaction.

Invoking this method will rollback all the additions, deletions, updations performed on the UOW. After a successful rollback, the UOW will free up its connection to the database, and should not be used again.

UOW uow = null;
try {
    uow = new UOW();
    ...
    ...
    uow.commit();
} catch (UOWException e) {
    // handle the exception
} finally {
    if (uow != null)
        uow.rollback();
}

Invoking the add method of the UOW, will add an object to the database. The preAdd trigger of the domain object is fired before the object is added. The persistence engine may choose to add the object to the database anytime it desires. A commit will however guarantee that the object was added, provided there were no errors.

UOW uow = null;
try {
    uow = new UOW();
    // create the domain object and set the initial fields.. Remember to use the updateXxx() methods
    DomainObject do = new DomainObject();
    do.updateField1("Value1");
    do.updateField2("Value2");
    // now add the object to the database
    uow.add(do);
    // this will commit the newly added object to the database
    uow.commit();
} catch (UOWException e) {
    // handle the exception
} finally {
    if (uow != null)
        uow.rollback();
}

Invoking the update method of the UOW, will update the corresponding row in the database. The preUpdate trigger of the domain object is fired before the object is updated. The persistence engine may choose to perform the updations to the database anytime it desires. A commit will however guarantee that the object was updated, provided there were no errors.

UOW uow = null;
try {
    uow = new UOW();
    // retrieve the domain object(s) to be updated, providing the appropriate query
    Criteria c = new Criteria();
    ...
    Collection results = uow.query( c );
    for (Iterator itr = results.iterator(); itr.hasNext(); ) {
        DomainObject do = (DomainObject) itr.next();
        do.updateField1("Value1");
        do.updateField2("Value2");
        uow.update(do);
    }
    // this will commit the updations to the database
    uow.commit();
} catch (UOWException e) {
    // handle the exception
} finally {
    if (uow != null)
        uow.rollback();
}

Invoking the delete method of the UOW, will delete the corresponding row in the database. The preDelete trigger of the domain object is fired before the object is deleted. The persistence engine may choose to perform the deletions to the database anytime it desires. A commit will however guarantee that the object was deleted, provided there were no errors.

UOW uow = null;
try {
    uow = new UOW();
    // retrieve the domain object(s) to be deleted, providing the appropriate query
    Criteria c = new Criteria();
    ...
    Collection results = uow.query( c );
    for (Iterator itr = results.iterator(); itr.hasNext(); )
        uow.delete(itr.next());
    // this will commit the deletions to the database
    uow.commit();
} catch (UOWException e) {
    // handle the exception
} finally {
    if (uow != null)
        uow.rollback();
}