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