1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package javax.jdo;
23 import javax.transaction.Synchronization;
24
25 /*** The JDO <code>Transaction</code> interface provides for initiation and
26 * completion of transactions under user control.
27 * It is a sub-interface of the {@link PersistenceManager}
28 * that deals with options and transaction demarcation.
29 * <P>Transaction options include whether optimistic concurrency
30 * control should be used for the current transaction, whether instances
31 * may hold values in the cache outside transactions, and whether
32 * values should be retained in the cache after transaction completion. These
33 * options are valid for both managed and non-managed transactions.
34 *
35 * <P>Transaction initiation and completion methods have similar semantics to
36 * <code>javax.transaction.UserTransaction</code> when used outside a managed
37 * environment. When used in a managed environment, transaction initiation
38 * and completion methods may only be used with bean-managed transaction
39 * semantics.
40 * @version 2.0
41 */
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>JDOUserException<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 /*** The user can specify a <code>Synchronization</code> instance to be
169 * notified on transaction completions. The <code>beforeCompletion</code>
170 * method is called prior to flushing instances to the data store.
171 *
172 * <P>The <code>afterCompletion</code> method is called after performing
173 * state transitions of persistent and transactional instances, following
174 * the data store commit or rollback operation.
175 * <P>Only one <code>Synchronization</code> instance can be registered with
176 * the <code>Transaction</code>. If the application requires more than one
177 * instance to receive synchronization callbacks, then the single
178 * application instance is responsible for managing them, and forwarding
179 * callbacks to them.
180 * @param sync the <code>Synchronization</code> instance to be notified;
181 * <code>null</code> for none
182 */
183 void setSynchronization(Synchronization sync);
184
185 /*** The user-specified <code>Synchronization</code> instance for this
186 * <code>Transaction</code> instance.
187 * @return the user-specified <code>Synchronization</code> instance.
188 */
189 Synchronization getSynchronization();
190
191 /*** The <code>Transaction</code> instance is always associated with exactly
192 * one <code>PersistenceManager</code>.
193 *
194 * @return the <code>PersistenceManager</code> for this
195 * <code>Transaction</code> instance
196 */
197 PersistenceManager getPersistenceManager();
198 }