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 completion
26 * 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 semantics.
39 * @version 2.0
40 */
41
42 public interface Transaction
43 {
44 /*** Begin a transaction. The type of transaction is determined by the
45 * setting of the Optimistic flag.
46 * @see #setOptimistic
47 * @see #getOptimistic
48 * @throws JDOUserException if transactions are managed by a container
49 * in the managed environment, or if the transaction is already active.
50 */
51 void begin();
52
53 /*** Commit the current transaction.
54 * @throws JDOUserException if transactions are managed by a container
55 * in the managed environment, or if the transaction is not active.
56 */
57 void commit();
58
59 /*** Roll back the current transaction.
60 * @throws JDOUserException if transactions are managed by a container
61 * in the managed environment, or if the transaction is not active.
62 */
63 void rollback();
64
65 /*** Returns whether there is a transaction currently active.
66 * @return <code>true</code> if the transaction is active.
67 */
68 boolean isActive();
69
70 /***
71 * Returns the rollback-only status of the transaction. When
72 * begun, the rollback-only status is false. Either the
73 * application or the JDO implementation may set this flag
74 * using setRollbackOnly.
75 * @return <code>true</code> if the transaction has been
76 * marked for rollback.
77 * @since 2.0
78 */
79 boolean getRollbackOnly();
80
81 /***
82 * Sets the rollback-only status of the transaction to <code>true</code>.
83 * After this flag is set to <code>true</code>, the transaction
84 * can no longer be committed, and any attempt to commit the
85 * transaction will throw <code>JDOUserException<code>.
86 * @since 2.0
87 */
88 void setRollbackOnly();
89
90 /*** If <code>true</code>, allow persistent instances to be read without
91 * a transaction active.
92 * If an implementation does not support this option, a
93 * <code>JDOUnsupportedOptionException</code> is thrown.
94 * @param nontransactionalRead the value of the nontransactionalRead property
95 */
96 void setNontransactionalRead (boolean nontransactionalRead);
97
98 /*** If <code>true</code>, allows persistent instances to be read without
99 * a transaction active.
100 * @return the value of the nontransactionalRead property
101 */
102 boolean getNontransactionalRead ();
103
104 /*** If <code>true</code>, allow persistent instances to be written without
105 * a transaction active.
106 * If an implementation does not support this option, a
107 * <code>JDOUnsupportedOptionException</code> is thrown.
108 * @param nontransactionalWrite the value of the nontransactionalRead property
109 */
110 void setNontransactionalWrite (boolean nontransactionalWrite);
111
112 /*** If <code>true</code>, allows persistent instances to be written without
113 * a transaction active.
114 * @return the value of the nontransactionalWrite property
115 */
116 boolean getNontransactionalWrite ();
117
118 /*** If <code>true</code>, at commit instances retain their values and the instances
119 * transition to persistent-nontransactional.
120 * If an implementation does not support this option, a
121 * <code>JDOUnsupportedOptionException</code> is thrown.
122 * @param retainValues the value of the retainValues property
123 */
124 void setRetainValues(boolean retainValues);
125
126 /*** If <code>true</code>, at commit time instances retain their field values.
127 * @return the value of the retainValues property
128 */
129 boolean getRetainValues();
130
131 /*** If <code>true</code>, at rollback, fields of newly persistent instances
132 * are restored to
133 * their values as of the beginning of the transaction, and the instances
134 * revert to transient. Additionally, fields of modified
135 * instances of primitive types and immutable reference types
136 * are restored to their values as of the beginning of the
137 * transaction.
138 * <P>If <code>false</code>, at rollback, the values of fields of
139 * newly persistent instances are unchanged and the instances revert to
140 * transient. Additionally, dirty instances transition to hollow.
141 * If an implementation does not support this option, a
142 * <code>JDOUnsupportedOptionException</code> is thrown.
143 * @param restoreValues the value of the restoreValues property
144 */
145 void setRestoreValues(boolean restoreValues);
146
147 /*** Return the current value of the restoreValues property.
148 * @return the value of the restoreValues property
149 */
150 boolean getRestoreValues();
151
152 /*** Optimistic transactions do not hold data store locks until commit time.
153 * If an implementation does not support this option, a
154 * <code>JDOUnsupportedOptionException</code> is thrown.
155 * @param optimistic the value of the Optimistic flag.
156 */
157 void setOptimistic(boolean optimistic);
158
159 /*** Optimistic transactions do not hold data store locks until commit time.
160 * @return the value of the Optimistic property.
161 */
162 boolean getOptimistic();
163
164 /*** The user can specify a <code>Synchronization</code> instance to be notified on
165 * transaction completions. The <code>beforeCompletion</code> method is called prior
166 * to flushing instances to the data store.
167 *
168 * <P>The <code>afterCompletion</code> method is called after performing state
169 * transitions of persistent and transactional instances, following
170 * the data store commit or rollback operation.
171 * <P>Only one <code>Synchronization</code> instance can be registered with the
172 * <code>Transaction</code>. If the application requires more than one instance to
173 * receive synchronization callbacks, then the single application instance
174 * is responsible for managing them, and forwarding callbacks to them.
175 * @param sync the <code>Synchronization</code> instance to be notified; <code>null</code> for none
176 */
177 void setSynchronization(Synchronization sync);
178
179 /*** The user-specified <code>Synchronization</code> instance for this <code>Transaction</code> instance.
180 * @return the user-specified <code>Synchronization</code> instance.
181 */
182 Synchronization getSynchronization();
183
184 /*** The <code>Transaction</code> instance is always associated with exactly one
185 * <code>PersistenceManager</code>.
186 *
187 * @return the <code>PersistenceManager</code> for this <code>Transaction</code> instance
188 */
189 PersistenceManager getPersistenceManager();
190 }