transaction.java

Java的面向对象数据库系统的源代码

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抯 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);

}