001: package org.odmg;
002:
003: /**
004: * This interfaces provides the operations necessary to perform database transactions.
005: * All access, creation, and modification of persistent objects and their fields
006: * must be done within a transaction. Before performing any database operations,
007: * a thread must explicitly create a transaction object or associate itself with
008: * an existing transaction object (by calling <code>join</code>),
009: * and that transaction must be open (through a call to <code>begin</code>).
010: * All subsequent operations by the thread, including reads, writes, and lock
011: * acquisitions, are done under the thread’s current transaction.
012: * <p>
013: * A thread may only operate on its current transaction. For example,
014: * a <code>TransactionNotInProgressException</code> is thrown if a thread attempts
015: * to begin, commit, checkpoint, or abort a transaction prior to joining itself
016: * to that transaction.
017: * <p>
018: * A transaction is either <i>open</i> or <i>closed</i>. A transaction is open if a call
019: * has been made to <code>begin</code>, but no call has been made to <code>commit</code> or
020: * <code>abort</code>. Once <code>commit</code> or <code>abort</code> is called,
021: * the transaction is closed. The method <code>isOpen</code> can be called to
022: * determine the state of the transaction.
023: * <p>
024: * Read locks are implicitly obtained on objects as they are accessed.
025: * Write locks are implicitly obtained as objects are modified.
026: * <code>Transaction</code> objects are transient, they cannot be stored in the database.
027: * @author David Jordan (as Java Editor of the Object Data Management Group)
028: * @version ODMG 3.0
029: * @see TransactionNotInProgressException
030: */
031:
032: public interface Transaction {
033: /**
034: * Attach the caller's thread to this <code>Transaction</code> and detach the thread
035: * from any former <code>Transaction</code> the thread may have been associated with.
036: */
037: public void join();
038:
039: /**
040: * Detach the caller's thread from this <code>Transaction</code>, but do not attach
041: * the thread to another <code>Transaction</code>.
042: */
043: public void leave();
044:
045: /**
046: * Start a transaction.
047: * Calling <code>begin</code> multiple times on the same transaction object,
048: * without an intervening call to <code>commit</code> or <code>abort</code>,
049: * causes the exception <code>TransactionInProgressException</code> to be thrown
050: * on the second and subsequent calls. Operations executed before a transaction
051: * has been opened, or before reopening after a transaction is aborted or committed,
052: * have undefined results;
053: * these may throw a <code>TransactionNotInProgressException</code> exception.
054: */
055: public void begin();
056:
057: /**
058: * Determine whether the transaction is open or not.
059: * A transaction is open if a call has been made to <code>begin</code>,
060: * but a subsequent call to either <code>commit</code> or <code>abort</code>
061: * has not been made.
062: * @return True if the transaction is open, otherwise false.
063: */
064: public boolean isOpen();
065:
066: /**
067: * Commit and close the transaction.
068: * Calling <code>commit</code> commits to the database all persistent object
069: * modifications within the transaction and releases any locks held by the transaction.
070: * A persistent object modification is an update of any field of an existing
071: * persistent object, or an update or creation of a new named object in the database.
072: * If a persistent object modification results in a reference from an existing
073: * persistent object to a transient object, the transient object is moved to the
074: * database, and all references to it updated accordingly. Note that the act of
075: * moving a transient object to the database may create still more persistent
076: * references to transient objects, so its referents must be examined and moved as well.
077: * This process continues until the database contains no references to transient objects,
078: * a condition that is guaranteed as part of transaction commit.
079: * Committing a transaction does not remove from memory transient objects created
080: * during the transaction
081: */
082: public void commit();
083:
084: /**
085: * Abort and close the transaction.
086: * Calling abort abandons all persistent object modifications and releases the
087: * associated locks.
088: * Aborting a transaction does not restore the state of modified transient objects
089: */
090: public void abort();
091:
092: /**
093: * Commit the transaction, but reopen the transaction, retaining all locks.
094: * Calling <code>checkpoint</code> commits persistent object modifications made
095: * within the transaction since the last checkpoint to the database.
096: * The transaction retains all locks it held on those objects at the time the
097: * checkpoint was invoked.
098: */
099: public void checkpoint();
100:
101: /**
102: * Read lock mode.
103: */
104: public static final int READ = 1;
105:
106: /**
107: * Upgrade lock mode.
108: */
109: public static final int UPGRADE = 2;
110:
111: /**
112: * Write lock mode.
113: */
114: public static final int WRITE = 4;
115:
116: /**
117: * Upgrade the lock on the given object to the given lock mode.
118: * The call has no effect if the object's current lock is already at or above
119: * that level of lock mode.
120: * @param obj The object to acquire a lock on.
121: * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
122: * <code>UPGRADE</code>, and <code>WRITE</code>.
123: * @exception LockNotGrantedException Is thrown if the given lock mode could not be acquired.
124: */
125: public void lock(Object obj, int lockMode)
126: throws LockNotGrantedException;
127:
128: /**
129: * Upgrade the lock on the given object to the given lock mode.
130: * Method <code>tryLock</code> is the same as <code>lock</code> except it returns
131: * a boolean indicating whether the lock was granted instead of generating an exception.
132: * @param obj The object to acquire a lock on.
133: * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
134: * <code>UPGRADE</code>, and <code>WRITE</code>.
135: * @return True if the lock has been acquired, otherwise false.
136: */
137: public boolean tryLock(Object obj, int lockMode);
138:
139: }
|