KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > odmg > Transaction


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 JavaDoc 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 JavaDoc obj, int lockMode);
276
277
278
279 }
280
281
Popular Tags