package org.odmg;

/**
 * This interfaces provides the operations necessary to perform database transactions.
 * All access, creation, and modification of persistent objects and their fields
 * must be done within a transaction. Before performing any database operations,
 * a thread must explicitly create a transaction object or associate itself with
 * an existing transaction object (by calling <code>join</code>),
 * and that transaction must be open (through a call to <code>begin</code>).
 * All subsequent operations by the thread, including reads, writes, and lock
 * acquisitions, are done under the thread’s current transaction.
 * <p>
 * A thread may only operate on its current transaction. For example,
 * a <code>TransactionNotInProgressException</code> is thrown if a thread attempts
 * to begin, commit, checkpoint, or abort a transaction prior to joining itself
 * to that transaction.
 * <p>
 * A transaction is either <i>open</i> or <i>closed</i>. A transaction is open if a call
 * has been made to <code>begin</code>, but no call has been made to <code>commit</code> or
 * <code>abort</code>. Once <code>commit</code> or <code>abort</code> is called,
 * the transaction is closed. The method <code>isOpen</code> can be called to
 * determine the state of the transaction.
 * <p>
 * Read locks are implicitly obtained on objects as they are accessed.
 * Write locks are implicitly obtained as objects are modified.
 * <code>Transaction</code> objects are transient, they cannot be stored in the database.
 * @author	David Jordan (as Java Editor of the Object Data Management Group)
 * @version ODMG 3.0
 * @see TransactionNotInProgressException
 */

public interface Transaction
{
    /**
     * Attach the caller's thread to this <code>Transaction</code> and detach the thread
     * from any former <code>Transaction</code> the thread may have been associated with.
     */
    public void join();

    /**
     * Detach the caller's thread from this <code>Transaction</code>, but do not attach
     * the thread to another <code>Transaction</code>.
     */
    public void leave();

    /**
     * Start a transaction.
     * Calling <code>begin</code> multiple times on the same transaction object,
     * without an intervening call to <code>commit</code> or <code>abort</code>,
     * causes the exception <code>TransactionInProgressException</code> to be thrown
     * on the second and subsequent calls. Operations executed before a transaction
     * has been opened, or before reopening after a transaction is aborted or committed,
     * have undefined results;
     * these may throw a <code>TransactionNotInProgressException</code> exception.
     */
    public void begin();

    /**
     * Determine whether the transaction is open or not.
     * A transaction is open if a call has been made to <code>begin</code>,
     * but a subsequent call to either <code>commit</code> or <code>abort</code>
     * has not been made.
     * @return True if the transaction is open, otherwise false.
     */
    public boolean isOpen();

    /**
     * Commit and close the transaction.
     * Calling <code>commit</code> commits to the database all persistent object
     * modifications within the transaction and releases any locks held by the transaction.
     * A persistent object modification is an update of any field of an existing
     * persistent object, or an update or creation of a new named object in the database.
     * If a persistent object modification results in a reference from an existing
     * persistent object to a transient object, the transient object is moved to the
     * database, and all references to it updated accordingly. Note that the act of
     * moving a transient object to the database may create still more persistent
     * references to transient objects, so its referents must be examined and moved as well.
     * This process continues until the database contains no references to transient objects,
     * a condition that is guaranteed as part of transaction commit.
     * Committing a transaction does not remove from memory transient objects created
     * during the transaction
     */
    public void commit();

    /**
     * Abort and close the transaction.
     * Calling abort abandons all persistent object modifications and releases the
     * associated locks.
     * Aborting a transaction does not restore the state of modified transient objects
     */
    public void abort();

    /**
     * Commit the transaction, but reopen the transaction, retaining all locks.
     * Calling <code>checkpoint</code> commits persistent object modifications made
     * within the transaction since the last checkpoint to the database.
     * The transaction retains all locks it held on those objects at the time the
     * checkpoint was invoked.
     */
    public void checkpoint();

    /**
     * Read lock mode.
     */
    public static final int READ = 1;

    /**
     * Upgrade lock mode.
     */
    public static final int UPGRADE = 2;

    /**
     * Write lock mode.
     */
    public static final int WRITE = 4;

    /**
     * Upgrade the lock on the given object to the given lock mode.
     * The call has no effect if the object's current lock is already at or above
     * that level of lock mode.
     * @param	obj	The object to acquire a lock on.
     * @param	lockMode	The lock mode to acquire. The lock modes are <code>READ</code>,
     * <code>UPGRADE</code>, and <code>WRITE</code>.
     * @exception LockNotGrantedException	Is thrown if the given lock mode could not be acquired.
     */
    public void lock(Object obj, int lockMode)
            throws LockNotGrantedException;

    /**
     * Upgrade the lock on the given object to the given lock mode.
     * Method <code>tryLock</code> is the same as <code>lock</code> except it returns
     * a boolean indicating whether the lock was granted instead of generating an exception.
     * @param	obj	The object to acquire a lock on.
     * @param	lockMode	The lock mode to acquire. The lock modes are <code>READ</code>,
     * <code>UPGRADE</code>, and <code>WRITE</code>.
     * @return	True if the lock has been acquired, otherwise false.
     */
    public boolean tryLock(Object obj, int lockMode);

}