TransactionDefinition


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.transaction;
18  
19  import java.sql.Connection  ;
20  
21  /**
22   * Interface that defines Spring-compliant transaction properties.
23   * Based on the propagation behavior definitions analogous to EJB CMT attributes.
24   *
25   * <p>Note that isolation level and timeout settings will not get applied unless
26   * an actual new transaction gets started. As only {@link #PROPAGATION_REQUIRED},
27   * {@link #PROPAGATION_REQUIRES_NEW} and {@link #PROPAGATION_NESTED} can cause
28   * that, it usually doesn't make sense to specify those settings in other cases.
29   * Furthermore, be aware that not all transaction managers will support those
30   * advanced features and thus might throw corresponding exceptions when given
31   * non-default values.
32   *
33   * <p>The {@link #isReadOnly() read-only flag} applies to any transaction context,
34   * whether backed by an actual resource transaction or operating non-transactionally
35   * at the resource level. In the latter case, the flag will only apply to managed
36   * resources within the application, such as a Hibernate <code>Session</code>.
37   *
38   * @author Juergen Hoeller
39   * @since 08.05.2003
40   * @see PlatformTransactionManager#getTransaction(TransactionDefinition)
41   * @see org.springframework.transaction.support.DefaultTransactionDefinition
42   * @see org.springframework.transaction.interceptor.TransactionAttribute
43   */
44  public interface TransactionDefinition {
45  
46      /**
47       * Support a current transaction; create a new one if none exists.
48       * Analogous to the EJB transaction attribute of the same name.
49       * <p>This is typically the default setting of a transaction definition,
50       * and typically defines a transaction synchronization scope.
51       */
52      int PROPAGATION_REQUIRED = 0;
53  
54      /**
55       * Support a current transaction; execute non-transactionally if none exists.
56       * Analogous to the EJB transaction attribute of the same name.
57       * <p><b>NOTE:</b> For transaction managers with transaction synchronization,
58       * <code>PROPAGATION_SUPPORTS</code> is slightly different from no transaction
59       * at all, as it defines a transaction scope that synchronization might apply to.
60       * As a consequence, the same resources (a JDBC <code>Connection</code>, a
61       * Hibernate <code>Session</code>, etc) will be shared for the entire specified
62       * scope. Note that the exact behavior depends on the actual synchronization
63       * configuration of the transaction manager!
64       * <p>In general, use <code>PROPAGATION_SUPPORTS</code> with care! In particular, do
65       * not rely on <code>PROPAGATION_REQUIRED</code> or <code>PROPAGATION_REQUIRES_NEW</code>
66       * <i>within</i> a <code>PROPAGATION_SUPPORTS</code> scope (which may lead to
67       * synchronization conflicts at runtime). If such nesting is unavoidable, make sure
68       * to configure your transaction manager appropriately (typically switching to
69       * "synchronization on actual transaction").
70       * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#setTransactionSynchronization
71       * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#SYNCHRONIZATION_ON_ACTUAL_TRANSACTION
72       */
73      int PROPAGATION_SUPPORTS = 1;
74  
75      /**
76       * Support a current transaction; throw an exception if no current transaction
77       * exists. Analogous to the EJB transaction attribute of the same name.
78       * <p>Note that transaction synchronization within a <code>PROPAGATION_MANDATORY</code>
79       * scope will always be driven by the surrounding transaction.
80       */
81      int PROPAGATION_MANDATORY = 2;
82  
83      /**
84       * Create a new transaction, suspending the current transaction if one exists.
85       * Analogous to the EJB transaction attribute of the same name.
86       * <p><b>NOTE:</b> Actual transaction suspension will not work out-of-the-box
87       * on all transaction managers. This in particular applies to
88       * {@link org.springframework.transaction.jta.JtaTransactionManager},
89       * which requires the <code>javax.transaction.TransactionManager</code>
90       * to be made available it to it (which is server-specific in standard J2EE).
91       * <p>A <code>PROPAGATION_REQUIRES_NEW</code> scope always defines its own
92       * transaction synchronizations. Existing synchronizations will be suspended
93       * and resumed appropriately.
94       * @see org.springframework.transaction.jta.JtaTransactionManager#setTransactionManager
95       */
96      int PROPAGATION_REQUIRES_NEW = 3;
97  
98      /**
99       * Do not support a current transaction; rather always execute non-transactionally.
100      * Analogous to the EJB transaction attribute of the same name.
101      * <p><b>NOTE:</b> Actual transaction suspension will not work out-of-the-box
102      * on all transaction managers. This in particular applies to
103      * {@link org.springframework.transaction.jta.JtaTransactionManager},
104      * which requires the <code>javax.transaction.TransactionManager</code>
105      * to be made available it to it (which is server-specific in standard J2EE).
106      * <p>Note that transaction synchronization is <i>not</i> available within a
107      * <code>PROPAGATION_NOT_SUPPORTED</code> scope. Existing synchronizations
108      * will be suspended and resumed appropriately.
109      * @see org.springframework.transaction.jta.JtaTransactionManager#setTransactionManager
110      */
111     int PROPAGATION_NOT_SUPPORTED = 4;
112 
113     /**
114      * Do not support a current transaction; throw an exception if a current transaction
115      * exists. Analogous to the EJB transaction attribute of the same name.
116      * <p>Note that transaction synchronization is <i>not</i> available within a
117      * <code>PROPAGATION_NEVER</code> scope.
118      */
119     int PROPAGATION_NEVER = 5;
120 
121     /**
122      * Execute within a nested transaction if a current transaction exists,
123      * behave like {@link #PROPAGATION_REQUIRED} else. There is no analogous
124      * feature in EJB.
125      * <p><b>NOTE:</b> Actual creation of a nested transaction will only work on specific
126      * transaction managers. Out of the box, this only applies to the JDBC
127      * {@link org.springframework.jdbc.datasource.DataSourceTransactionManager}
128      * when working on a JDBC 3.0 driver. Some JTA providers might support
129      * nested transactions as well.
130      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager
131      */
132     int PROPAGATION_NESTED = 6;
133 
134 
135     /**
136      * Use the default isolation level of the underlying datastore.
137      * All other levels correspond to the JDBC isolation levels.
138      * @see java.sql.Connection
139      */
140     int ISOLATION_DEFAULT = -1;
141 
142     /**
143      * Indicates that dirty reads, non-repeatable reads and phantom reads
144      * can occur.
145      * <p>This level allows a row changed by one transaction to be read by
146      * another transaction before any changes in that row have been committed
147      * (a "dirty read"). If any of the changes are rolled back, the second
148      * transaction will have retrieved an invalid row.
149      * @see java.sql.Connection#TRANSACTION_READ_UNCOMMITTED
150      */
151     int ISOLATION_READ_UNCOMMITTED = Connection.TRANSACTION_READ_UNCOMMITTED;
152 
153     /**
154      * Indicates that dirty reads are prevented; non-repeatable reads and
155      * phantom reads can occur.
156      * <p>This level only prohibits a transaction from reading a row
157      * with uncommitted changes in it.
158      * @see java.sql.Connection#TRANSACTION_READ_COMMITTED
159      */
160     int ISOLATION_READ_COMMITTED = Connection.TRANSACTION_READ_COMMITTED;
161 
162     /**
163      * Indicates that dirty reads and non-repeatable reads are prevented;
164      * phantom reads can occur.
165      * <p>This level prohibits a transaction from reading a row with
166      * uncommitted changes in it, and it also prohibits the situation
167      * where one transaction reads a row, a second transaction alters
168      * the row, and the first transaction rereads the row, getting
169      * different values the second time (a "non-repeatable read").
170      * @see java.sql.Connection#TRANSACTION_REPEATABLE_READ
171      */
172     int ISOLATION_REPEATABLE_READ = Connection.TRANSACTION_REPEATABLE_READ;
173 
174     /**
175      * Indicates that dirty reads, non-repeatable reads and phantom reads
176      * are prevented.
177      * <p>This level includes the prohibitions in
178      * {@link #ISOLATION_REPEATABLE_READ} and further prohibits the
179      * situation where one transaction reads all rows that satisfy a
180      * <code>WHERE</code> condition, a second transaction inserts a
181      * row that satisfies that <code>WHERE</code> condition, and the
182      * first transaction rereads for the same condition, retrieving
183      * the additional "phantom" row in the second read.
184      * @see java.sql.Connection#TRANSACTION_SERIALIZABLE
185      */
186     int ISOLATION_SERIALIZABLE = Connection.TRANSACTION_SERIALIZABLE;
187 
188 
189     /**
190      * Use the default timeout of the underlying transaction system,
191      * or none if timeouts are not supported. 
192      */
193     int TIMEOUT_DEFAULT = -1;
194 
195 
196     /**
197      * Return the propagation behavior.
198      * <p>Must return one of the <code>PROPAGATION_XXX</code> constants
199      * defined on {@link TransactionDefinition this interface}.
200      * @return the propagation behavior
201      * @see #PROPAGATION_REQUIRED
202      * @see org.springframework.transaction.support.TransactionSynchronizationManager#isActualTransactionActive()
203      */
204     int getPropagationBehavior();
205 
206     /**
207      * Return the isolation level.
208      * <p>Must return one of the <code>ISOLATION_XXX</code> constants
209      * defined on {@link TransactionDefinition this interface}.
210      * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
211      * or {@link #PROPAGATION_REQUIRES_NEW}.
212      * <p>Note that a transaction manager that does not support custom
213      * isolation levels will throw an exception when given any other level
214      * than {@link #ISOLATION_DEFAULT}.
215      * @return the isolation level
216      */
217     int getIsolationLevel();
218 
219     /**
220      * Return the transaction timeout.
221      * <p>Must return a number of seconds, or {@link #TIMEOUT_DEFAULT}.
222      * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
223      * or {@link #PROPAGATION_REQUIRES_NEW}.
224      * <p>Note that a transaction manager that does not support timeouts
225      * will throw an exception when given any other timeout than
226      * {@link #TIMEOUT_DEFAULT}.
227      * @return the transaction timeout
228      */
229     int getTimeout();
230 
231     /**
232      * Return whether to optimize as a read-only transaction.
233      * <p>The read-only flag applies to any transaction context, whether
234      * backed by an actual resource transaction
235      * ({@link #PROPAGATION_REQUIRED}/{@link #PROPAGATION_REQUIRES_NEW}) or
236      * operating non-transactionally at the resource level
237      * ({@link #PROPAGATION_SUPPORTS}). In the latter case, the flag will
238      * only apply to managed resources within the application, such as a
239      * Hibernate <code>Session</code>.
240      * <p>This just serves as a hint for the actual transaction subsystem;
241      * it will <i>not necessarily</i> cause failure of write access attempts.
242      * A transaction manager that cannot interpret the read-only hint will
243      * <i>not</i> throw an exception when asked for a read-only transaction.
244      * @return <code>true</code> if the transaction is to be optimized as read-only 
245      * @see org.springframework.transaction.support.TransactionSynchronization#beforeCommit(boolean)
246      * @see org.springframework.transaction.support.TransactionSynchronizationManager#isCurrentTransactionReadOnly()
247      */
248     boolean isReadOnly();
249 
250     /**
251      * Return the name of this transaction. Can be <code>null</code>.
252      * <p>This will be used as the transaction name to be shown in a
253      * transaction monitor, if applicable (for example, WebLogic's).
254      * <p>In case of Spring's declarative transactions, the exposed name
255      * must (and will) be the
256      * <code>fully-qualified class name + "." + method name</code>
257      * (by default).
258      * @return the name of this transaction
259      * @see org.springframework.transaction.interceptor.TransactionAspectSupport
260      * @see org.springframework.transaction.support.TransactionSynchronizationManager#getCurrentTransactionName()
261      */
262     String   getName();
263 
264 }
265
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags