1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 package javax.jdo;
24 import javax.transaction.Synchronization;
25
26 /*** The JDO <code>Transaction</code> interface provides for initiation and
27 * completion of transactions under user control.
28 * It is a sub-interface of the {@link PersistenceManager}
29 * that deals with options and transaction demarcation.
30 * <P>Transaction options include whether optimistic concurrency
31 * control should be used for the current transaction, whether instances
32 * may hold values in the cache outside transactions, and whether
33 * values should be retained in the cache after transaction completion. These
34 * options are valid for both managed and non-managed transactions.
35 *
36 * <P>Transaction initiation and completion methods have similar semantics to
37 * <code>javax.transaction.UserTransaction</code> when used outside a managed
38 * environment. When used in a managed environment, transaction initiation
39 * and completion methods may only be used with bean-managed transaction
40 * semantics.
41 * @version 2.0
42 */
43
44 public interface Transaction
45 {
46 /*** Begin a transaction. The type of transaction is determined by the
47 * setting of the Optimistic flag.
48 * @see #setOptimistic
49 * @see #getOptimistic
50 * @throws JDOUserException if transactions are managed by a container
51 * in the managed environment, or if the transaction is already active.
52 */
53 void begin();
54
55 /*** Commit the current transaction.
56 * @throws JDOUserException if transactions are managed by a container
57 * in the managed environment, or if the transaction is not active.
58 */
59 void commit();
60
61 /*** Roll back the current transaction.
62 * @throws JDOUserException if transactions are managed by a container
63 * in the managed environment, or if the transaction is not active.
64 */
65 void rollback();
66
67 /*** Returns whether there is a transaction currently active.
68 * @return <code>true</code> if the transaction is active.
69 */
70 boolean isActive();
71
72 /***
73 * Returns the rollback-only status of the transaction. When
74 * begun, the rollback-only status is false. Either the
75 * application or the JDO implementation may set this flag
76 * using setRollbackOnly.
77 * @return <code>true</code> if the transaction has been
78 * marked for rollback.
79 * @since 2.0
80 */
81 boolean getRollbackOnly();
82
83 /***
84 * Sets the rollback-only status of the transaction to <code>true</code>.
85 * After this flag is set to <code>true</code>, the transaction
86 * can no longer be committed, and any attempt to commit the
87 * transaction will throw <code>JDOFatalDataStoreException<code>.
88 * @since 2.0
89 */
90 void setRollbackOnly();
91
92 /*** If <code>true</code>, allow persistent instances to be read without
93 * a transaction active.
94 * If an implementation does not support this option, a
95 * <code>JDOUnsupportedOptionException</code> is thrown.
96 * @param nontransactionalRead the value of the nontransactionalRead
97 * property
98 */
99 void setNontransactionalRead (boolean nontransactionalRead);
100
101 /*** If <code>true</code>, allows persistent instances to be read without
102 * a transaction active.
103 * @return the value of the nontransactionalRead property
104 */
105 boolean getNontransactionalRead ();
106
107 /*** If <code>true</code>, allow persistent instances to be written without
108 * a transaction active.
109 * If an implementation does not support this option, a
110 * <code>JDOUnsupportedOptionException</code> is thrown.
111 * @param nontransactionalWrite the value of the nontransactionalRead
112 * property
113 */
114 void setNontransactionalWrite (boolean nontransactionalWrite);
115
116 /*** If <code>true</code>, allows persistent instances to be written without
117 * a transaction active.
118 * @return the value of the nontransactionalWrite property
119 */
120 boolean getNontransactionalWrite ();
121
122 /*** If <code>true</code>, at commit instances retain their values and the
123 * instances transition to persistent-nontransactional.
124 * If an implementation does not support this option, a
125 * <code>JDOUnsupportedOptionException</code> is thrown.
126 * @param retainValues the value of the retainValues property
127 */
128 void setRetainValues(boolean retainValues);
129
130 /*** If <code>true</code>, at commit time instances retain their field
131 * values.
132 * @return the value of the retainValues property
133 */
134 boolean getRetainValues();
135
136 /*** If <code>true</code>, at rollback, fields of newly persistent instances
137 * are restored to
138 * their values as of the beginning of the transaction, and the instances
139 * revert to transient. Additionally, fields of modified
140 * instances of primitive types and immutable reference types
141 * are restored to their values as of the beginning of the
142 * transaction.
143 * <P>If <code>false</code>, at rollback, the values of fields of
144 * newly persistent instances are unchanged and the instances revert to
145 * transient. Additionally, dirty instances transition to hollow.
146 * If an implementation does not support this option, a
147 * <code>JDOUnsupportedOptionException</code> is thrown.
148 * @param restoreValues the value of the restoreValues property
149 */
150 void setRestoreValues(boolean restoreValues);
151
152 /*** Return the current value of the restoreValues property.
153 * @return the value of the restoreValues property
154 */
155 boolean getRestoreValues();
156
157 /*** Optimistic transactions do not hold data store locks until commit time.
158 * If an implementation does not support this option, a
159 * <code>JDOUnsupportedOptionException</code> is thrown.
160 * @param optimistic the value of the Optimistic flag.
161 */
162 void setOptimistic(boolean optimistic);
163
164 /*** Optimistic transactions do not hold data store locks until commit time.
165 * @return the value of the Optimistic property.
166 */
167 boolean getOptimistic();
168
169 /*** Get the value for transaction isolation level for this transaction.
170 * @return the transaction isolation level
171 * @see #setIsolationLevel(String)
172 * @since 2.2
173 */
174 String getIsolationLevel();
175
176 /*** Set the value for transaction isolation level for this transaction.
177 * Transaction isolation levels are defined in javax.jdo.Constants.
178 * If the requested level is not available, but a higher level is
179 * available, the higher level is silently used.
180 * If the requested level is not available, and no higher level is
181 * available, then JDOUnsupportedOptionException is thrown.
182 * Five standard isolation levels are defined. Other isolation levels
183 * might be supported by an implementation but are not standard.
184 * <p>Standard values in order of low to high are:
185 * <ul><li>read-uncommitted
186 * </li><li>read-committed
187 * </li><li>repeatable-read
188 * </li><li>snapshot
189 * </li><li>serializable
190 * </li></ul>
191 * @param level the transaction isolation level
192 * @see #getIsolationLevel()
193 * @see Constants#TX_READ_UNCOMMITTED
194 * @see Constants#TX_READ_COMMITTED
195 * @see Constants#TX_REPEATABLE_READ
196 * @see Constants#TX_SNAPSHOT
197 * @see Constants#TX_SERIALIZABLE
198 * @since 2.2
199 */
200 void setIsolationLevel(String level);
201
202 /*** The user can specify a <code>Synchronization</code> instance to be
203 * notified on transaction completions. The <code>beforeCompletion</code>
204 * method is called prior to flushing instances to the data store.
205 *
206 * <P>The <code>afterCompletion</code> method is called after performing
207 * state transitions of persistent and transactional instances, following
208 * the data store commit or rollback operation.
209 * <P>Only one <code>Synchronization</code> instance can be registered with
210 * the <code>Transaction</code>. If the application requires more than one
211 * instance to receive synchronization callbacks, then the single
212 * application instance is responsible for managing them, and forwarding
213 * callbacks to them.
214 * @param sync the <code>Synchronization</code> instance to be notified;
215 * <code>null</code> for none
216 */
217 void setSynchronization(Synchronization sync);
218
219 /*** The user-specified <code>Synchronization</code> instance for this
220 * <code>Transaction</code> instance.
221 * @return the user-specified <code>Synchronization</code> instance.
222 */
223 Synchronization getSynchronization();
224
225 /*** The <code>Transaction</code> instance is always associated with exactly
226 * one <code>PersistenceManager</code>.
227 *
228 * @return the <code>PersistenceManager</code> for this
229 * <code>Transaction</code> instance
230 */
231 PersistenceManager getPersistenceManager();
232 }