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