iunitofwork.java

A Java web application, based on Struts and Hibernate, that serves as an online running log. Users m

/* @LICENSE_COPYRIGHT@ */
package net.sf.irunninglog.transaction;

import java.io.Serializable;
import java.util.Collection;

/**
 * Interface defining a unit of work for interacting with the application's
 * persistent store.  Unit of work objects are accessed with the scope of an
 * <code>ITransaction</code> instance which is responsible for coordinating the
 * transactional behavior of any changes made using the unit of work.  Unit of
 * work instances should be accessed using <code>ITransaction</code>'s
 * <code>getUnitOfWork</code> method.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.5 $ $Date: 2005/06/29 03:50:41 $
 * @since iRunningLog 1.0
 * @see ITransaction#getUnitOfWork()
 */
public interface IUnitOfWork {

    /**
     * Create a new record in the applicaiton's persistent store using a
     * business object.
     *
     * @param obj The business object to be used in creating the record
     * @throws TransactionException If the record cannot be created
     */
    void create(Serializable obj) throws TransactionException;

    /**
     * Update a record in the application's persistent store based on a business
     * object's values.
     *
     * @param obj The business object to be used in locating and updating the
     *            record
     * @throws TransactionException If the record cannot be updated
     */
    void update(Serializable obj) throws TransactionException;

    /**
     * Either create or update a record in the application's persistent store
     * based on the values of a business object.
     *
     * @param obj The business object to be used in either creating or updating
     *            the record
     * @throws TransactionException If the record cannot be created/updated
     */
    void createOrUpdate(Serializable obj) throws TransactionException;

    /**
     * Delete a record from the application's persistent store based on the
     * values of a business object.
     *
     * @param obj The business object to be used in locating the object to
     *            delete
     * @throws TransactionException If the record cannot be located/deleted
     */
    void delete(Serializable obj) throws TransactionException;

    /**
     * Load a record from the application's persistent store into a business
     * object.
     *
     * @param clazz The class of the business object to be returned
     * @param id The persistent id of the record to be loaded
     * @return The business object containing values loaded from the persistent
     *         store
     * @throws TransactionException If the record cannot be loaded
     */
    Serializable load(Class clazz, String id) throws TransactionException;

    /**
     * Locate records in the application's persistent store and return them
     * as business objects.
     *
     * @param query String representing the query to be executed
     * @param parameters Values to be substituted into the query string to
     *                   customize the query
     * @return The collection of business object(s) located by the query
     * @throws TransactionException If there is an error querying the persistent
     *                              store
     */
    Collection find(String query, Object [] parameters)
                                                    throws TransactionException;

}