1 package org.odmg;
2
3
4
5 /**
6
7 * This interfaces provides the operations necessary to perform database transactions.
8
9 * All access, creation, and modification of persistent objects and their fields
10
11 * must be done within a transaction. Before performing any database operations,
12
13 * a thread must explicitly create a transaction object or associate itself with
14
15 * an existing transaction object (by calling <code>join</code>),
16
17 * and that transaction must be open (through a call to <code>begin</code>).
18
19 * All subsequent operations by the thread, including reads, writes, and lock
20
21 * acquisitions, are done under the thread�s current transaction.
22
23 * <p>
24
25 * A thread may only operate on its current transaction. For example,
26
27 * a <code>TransactionNotInProgressException</code> is thrown if a thread attempts
28
29 * to begin, commit, checkpoint, or abort a transaction prior to joining itself
30
31 * to that transaction.
32
33 * <p>
34
35 * A transaction is either <i>open</i> or <i>closed</i>. A transaction is open if a call
36
37 * has been made to <code>begin</code>, but no call has been made to <code>commit</code> or
38
39 * <code>abort</code>. Once <code>commit</code> or <code>abort</code> is called,
40
41 * the transaction is closed. The method <code>isOpen</code> can be called to
42
43 * determine the state of the transaction.
44
45 * <p>
46
47 * Read locks are implicitly obtained on objects as they are accessed.
48
49 * Write locks are implicitly obtained as objects are modified.
50
51 * <code>Transaction</code> objects are transient, they cannot be stored in the database.
52
53 * @author David Jordan (as Java Editor of the Object Data Management Group)
54
55 * @version ODMG 3.0
56
57 * @see TransactionNotInProgressException
58
59 */
60
61
62
63 public interface Transaction
64
65 {
66
67 /**
68
69 * Attach the caller's thread to this <code>Transaction</code> and detach the thread
70
71 * from any former <code>Transaction</code> the thread may have been associated with.
72
73 */
74
75 public void join();
76
77
78
79 /**
80
81 * Detach the caller's thread from this <code>Transaction</code>, but do not attach
82
83 * the thread to another <code>Transaction</code>.
84
85 */
86
87 public void leave();
88
89
90
91 /**
92
93 * Start a transaction.
94
95 * Calling <code>begin</code> multiple times on the same transaction object,
96
97 * without an intervening call to <code>commit</code> or <code>abort</code>,
98
99 * 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