001: package org.odmg;
002:
003: /**
004:
005: * This interfaces provides the operations necessary to perform database transactions.
006:
007: * All access, creation, and modification of persistent objects and their fields
008:
009: * must be done within a transaction. Before performing any database operations,
010:
011: * a thread must explicitly create a transaction object or associate itself with
012:
013: * an existing transaction object (by calling <code>join</code>),
014:
015: * and that transaction must be open (through a call to <code>begin</code>).
016:
017: * All subsequent operations by the thread, including reads, writes, and lock
018:
019: * acquisitions, are done under the thread’s current transaction.
020:
021: * <p>
022:
023: * A thread may only operate on its current transaction. For example,
024:
025: * a <code>TransactionNotInProgressException</code> is thrown if a thread attempts
026:
027: * to begin, commit, checkpoint, or abort a transaction prior to joining itself
028:
029: * to that transaction.
030:
031: * <p>
032:
033: * A transaction is either <i>open</i> or <i>closed</i>. A transaction is open if a call
034:
035: * has been made to <code>begin</code>, but no call has been made to <code>commit</code> or
036:
037: * <code>abort</code>. Once <code>commit</code> or <code>abort</code> is called,
038:
039: * the transaction is closed. The method <code>isOpen</code> can be called to
040:
041: * determine the state of the transaction.
042:
043: * <p>
044:
045: * Read locks are implicitly obtained on objects as they are accessed.
046:
047: * Write locks are implicitly obtained as objects are modified.
048:
049: * <code>Transaction</code> objects are transient, they cannot be stored in the database.
050:
051: * @author David Jordan (as Java Editor of the Object Data Management Group)
052:
053: * @version ODMG 3.0
054:
055: * @see TransactionNotInProgressException
056:
057: */
058:
059: public interface Transaction
060:
061: {
062:
063: /**
064:
065: * Attach the caller's thread to this <code>Transaction</code> and detach the thread
066:
067: * from any former <code>Transaction</code> the thread may have been associated with.
068:
069: */
070:
071: public void join();
072:
073: /**
074:
075: * Detach the caller's thread from this <code>Transaction</code>, but do not attach
076:
077: * the thread to another <code>Transaction</code>.
078:
079: */
080:
081: public void leave();
082:
083: /**
084:
085: * Start a transaction.
086:
087: * Calling <code>begin</code> multiple times on the same transaction object,
088:
089: * without an intervening call to <code>commit</code> or <code>abort</code>,
090:
091: * causes the exception <code>TransactionInProgressException</code> to be thrown
092:
093: * on the second and subsequent calls. Operations executed before a transaction
094:
095: * has been opened, or before reopening after a transaction is aborted or committed,
096:
097: * have undefined results;
098:
099: * these may throw a <code>TransactionNotInProgressException</code> exception.
100:
101: */
102:
103: public void begin();
104:
105: /**
106:
107: * Determine whether the transaction is open or not.
108:
109: * A transaction is open if a call has been made to <code>begin</code>,
110:
111: * but a subsequent call to either <code>commit</code> or <code>abort</code>
112:
113: * has not been made.
114:
115: * @return True if the transaction is open, otherwise false.
116:
117: */
118:
119: public boolean isOpen();
120:
121: /**
122:
123: * Commit and close the transaction.
124:
125: * Calling <code>commit</code> commits to the database all persistent object
126:
127: * modifications within the transaction and releases any locks held by the transaction.
128:
129: * A persistent object modification is an update of any field of an existing
130:
131: * persistent object, or an update or creation of a new named object in the database.
132:
133: * If a persistent object modification results in a reference from an existing
134:
135: * persistent object to a transient object, the transient object is moved to the
136:
137: * database, and all references to it updated accordingly. Note that the act of
138:
139: * moving a transient object to the database may create still more persistent
140:
141: * references to transient objects, so its referents must be examined and moved as well.
142:
143: * This process continues until the database contains no references to transient objects,
144:
145: * a condition that is guaranteed as part of transaction commit.
146:
147: * Committing a transaction does not remove from memory transient objects created
148:
149: * during the transaction
150:
151: */
152:
153: public void commit();
154:
155: /**
156:
157: * Abort and close the transaction.
158:
159: * Calling abort abandons all persistent object modifications and releases the
160:
161: * associated locks.
162:
163: * Aborting a transaction does not restore the state of modified transient objects
164:
165: */
166:
167: public void abort();
168:
169: /**
170:
171: * Commit the transaction, but reopen the transaction, retaining all locks.
172:
173: * Calling <code>checkpoint</code> commits persistent object modifications made
174:
175: * within the transaction since the last checkpoint to the database.
176:
177: * The transaction retains all locks it held on those objects at the time the
178:
179: * checkpoint was invoked.
180:
181: */
182:
183: public void checkpoint();
184:
185: /**
186:
187: * Read lock mode.
188:
189: */
190:
191: public static final int READ = 1;
192:
193: /**
194:
195: * Upgrade lock mode.
196:
197: */
198:
199: public static final int UPGRADE = 2;
200:
201: /**
202:
203: * Write lock mode.
204:
205: */
206:
207: public static final int WRITE = 4;
208:
209: /**
210:
211: * Upgrade the lock on the given object to the given lock mode.
212:
213: * The call has no effect if the object's current lock is already at or above
214:
215: * that level of lock mode.
216:
217: * @param obj The object to acquire a lock on.
218:
219: * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
220:
221: * <code>UPGRADE</code>, and <code>WRITE</code>.
222:
223: * @exception LockNotGrantedException Is thrown if the given lock mode could not be acquired.
224:
225: */
226:
227: public void lock(Object obj, int lockMode)
228:
229: throws LockNotGrantedException;
230:
231: /**
232:
233: * Upgrade the lock on the given object to the given lock mode.
234:
235: * Method <code>tryLock</code> is the same as <code>lock</code> except it returns
236:
237: * a boolean indicating whether the lock was granted instead of generating an exception.
238:
239: * @param obj The object to acquire a lock on.
240:
241: * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
242:
243: * <code>UPGRADE</code>, and <code>WRITE</code>.
244:
245: * @return True if the lock has been acquired, otherwise false.
246:
247: */
248:
249: public boolean tryLock(Object obj, int lockMode);
250:
251: }
|