itransaction.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;

/**
 * Interface defining a transaction within the application.  This interface
 * defines the methods needed to begin, commit and roll back a transactional
 * unit of work within the application.  The <code>IUnitOfWork</code> object
 * used to interact with the persistent store is accessible via the
 * <code>getUnitOfWork</code>.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.3 $ $Date: 2005/06/29 03:50:41 $
 * @since iRunningLog 1.0
 * @see IUnitOfWork
 */
public interface ITransaction {

    /**
     * Determine whether or not this transaction is active.  An active
     * transaction is one that has been begun, but not yet committed or
     * rolled back.
     *
     * @return True if the transaction is active, false otherwise
     */
    boolean isActive();

    /**
     * Get the id of the transaction.  This will return a value that uniquely
     * identifies the transaction within the context of the currently running
     * JVM.
     *
     * @return The id of this transaction
     */
    long getId();

    /**
     * Initiate a transaction.  This will make the transaciton active, and
     * will establish a unit of work that may be obtained using the <code>
     * getUnitOfWork</code> method.
     *
     * @throws TransactionException If the transaction cannot be initiated
     * @see #getUnitOfWork()
     */
    void begin() throws TransactionException;

    /**
     * Commit a transaction.  Any work done using the transaction's unit of
     * work will be committed to the persistent store, and the transaction will
     * be made inactive.
     *
     * @throws TransactionException If the transaciton cannot be committed
     */
    void commit() throws TransactionException;

    /**
     * Roll back a transaction.  Any work done using the transaction's unit of
     * work will be discarded, and the transaction will be made inactive.
     *
     * @throws TransactionException If the transaciton cannot be rolled back
     */
    void rollback() throws TransactionException;

    /**
     * Retrieve the unit of work for this transaction.  This will return an
     * <code>IUnitOfWork</code> instance that can be used to perform actions
     * against the application's persistent store.
     *
     * @return The transaction's unit of work
     * @throws TransactionException If the unit of work cannot be obtained
     * @see IUnitOfWork
     */
    IUnitOfWork getUnitOfWork() throws TransactionException;

}