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   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 
281
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags