Source code: org/odmg/Transaction.java
1 package org.odmg;
2
3 /**
4 * This interfaces provides the operations necessary to perform database transactions.
5 * All access, creation, and modification of persistent objects and their fields
6 * must be done within a transaction. Before performing any database operations,
7 * a thread must explicitly create a transaction object or associate itself with
8 * an existing transaction object (by calling <code>join</code>),
9 * and that transaction must be open (through a call to <code>begin</code>).
10 * All subsequent operations by the thread, including reads, writes, and lock
11 * acquisitions, are done under the thread’s current transaction.
12 * <p>
13 * A thread may only operate on its current transaction. For example,
14 * a <code>TransactionNotInProgressException</code> is thrown if a thread attempts
15 * to begin, commit, checkpoint, or abort a transaction prior to joining itself
16 * to that transaction.
17 * <p>
18 * A transaction is either <i>open</i> or <i>closed</i>. A transaction is open if a call
19 * has been made to <code>begin</code>, but no call has been made to <code>commit</code> or
20 * <code>abort</code>. Once <code>commit</code> or <code>abort</code> is called,
21 * the transaction is closed. The method <code>isOpen</code> can be called to
22 * determine the state of the transaction.
23 * <p>
24 * Read locks are implicitly obtained on objects as they are accessed.
25 * Write locks are implicitly obtained as objects are modified.
26 * <code>Transaction</code> objects are transient, they cannot be stored in the database.
27 * @author David Jordan (as Java Editor of the Object Data Management Group)
28 * @version ODMG 3.0
29 * @see TransactionNotInProgressException
30 */
31
32 public interface Transaction
33 {
34 /**
35 * Attach the caller's thread to this <code>Transaction</code> and detach the thread
36 * from any former <code>Transaction</code> the thread may have been associated with.
37 */
38 public void join();
39
40 /**
41 * Detach the caller's thread from this <code>Transaction</code>, but do not attach
42 * the thread to another <code>Transaction</code>.
43 */
44 public void leave();
45
46 /**
47 * Start a transaction.
48 * Calling <code>begin</code> multiple times on the same transaction object,
49 * without an intervening call to <code>commit</code> or <code>abort</code>,
50 * causes the exception <code>TransactionInProgressException</code> to be thrown
51 * on the second and subsequent calls. Operations executed before a transaction
52 * has been opened, or before reopening after a transaction is aborted or committed,
53 * have undefined results;
54 * these may throw a <code>TransactionNotInProgressException</code> exception.
55 */
56 public void begin();
57
58 /**
59 * Determine whether the transaction is open or not.
60 * A transaction is open if a call has been made to <code>begin</code>,
61 * but a subsequent call to either <code>commit</code> or <code>abort</code>
62 * has not been made.
63 * @return True if the transaction is open, otherwise false.
64 */
65 public boolean isOpen();
66
67 /**
68 * Commit and close the transaction.
69 * Calling <code>commit</code> commits to the database all persistent object
70 * modifications within the transaction and releases any locks held by the transaction.
71 * A persistent object modification is an update of any field of an existing
72 * persistent object, or an update or creation of a new named object in the database.
73 * If a persistent object modification results in a reference from an existing
74 * persistent object to a transient object, the transient object is moved to the
75 * database, and all references to it updated accordingly. Note that the act of
76 * moving a transient object to the database may create still more persistent
77 * references to transient objects, so its referents must be examined and moved as well.
78 * This process continues until the database contains no references to transient objects,
79 * a condition that is guaranteed as part of transaction commit.
80 * Committing a transaction does not remove from memory transient objects created
81 * during the transaction
82 */
83 public void commit();
84
85 /**
86 * Abort and close the transaction.
87 * Calling abort abandons all persistent object modifications and releases the
88 * associated locks.
89 * Aborting a transaction does not restore the state of modified transient objects
90 */
91 public void abort();
92
93 /**
94 * Commit the transaction, but reopen the transaction, retaining all locks.
95 * Calling <code>checkpoint</code> commits persistent object modifications made
96 * within the transaction since the last checkpoint to the database.
97 * The transaction retains all locks it held on those objects at the time the
98 * checkpoint was invoked.
99 */
100 public void checkpoint();
101
102 /**
103 * Read lock mode.
104 */
105 public static final int READ = 1;
106
107 /**
108 * Upgrade lock mode.
109 */
110 public static final int UPGRADE = 2;
111
112 /**
113 * Write lock mode.
114 */
115 public static final int WRITE = 4;
116
117 /**
118 * Upgrade the lock on the given object to the given lock mode.
119 * The call has no effect if the object's current lock is already at or above
120 * that level of lock mode.
121 * @param obj The object to acquire a lock on.
122 * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
123 * <code>UPGRADE</code>, and <code>WRITE</code>.
124 * @exception LockNotGrantedException Is thrown if the given lock mode could not be acquired.
125 */
126 public void lock(Object obj, int lockMode)
127 throws LockNotGrantedException;
128
129 /**
130 * Upgrade the lock on the given object to the given lock mode.
131 * Method <code>tryLock</code> is the same as <code>lock</code> except it returns
132 * a boolean indicating whether the lock was granted instead of generating an exception.
133 * @param obj The object to acquire a lock on.
134 * @param lockMode The lock mode to acquire. The lock modes are <code>READ</code>,
135 * <code>UPGRADE</code>, and <code>WRITE</code>.
136 * @return True if the lock has been acquired, otherwise false.
137 */
138 public boolean tryLock(Object obj, int lockMode);
139
140 }