001: /*
002: * Copyright 2002-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.transaction;
018:
019: import java.sql.Connection;
020:
021: /**
022: * Interface that defines Spring-compliant transaction properties.
023: * Based on the propagation behavior definitions analogous to EJB CMT attributes.
024: *
025: * <p>Note that isolation level and timeout settings will not get applied unless
026: * an actual new transaction gets started. As only {@link #PROPAGATION_REQUIRED},
027: * {@link #PROPAGATION_REQUIRES_NEW} and {@link #PROPAGATION_NESTED} can cause
028: * that, it usually doesn't make sense to specify those settings in other cases.
029: * Furthermore, be aware that not all transaction managers will support those
030: * advanced features and thus might throw corresponding exceptions when given
031: * non-default values.
032: *
033: * <p>The {@link #isReadOnly() read-only flag} applies to any transaction context,
034: * whether backed by an actual resource transaction or operating non-transactionally
035: * at the resource level. In the latter case, the flag will only apply to managed
036: * resources within the application, such as a Hibernate <code>Session</code>.
037: *
038: * @author Juergen Hoeller
039: * @since 08.05.2003
040: * @see PlatformTransactionManager#getTransaction(TransactionDefinition)
041: * @see org.springframework.transaction.support.DefaultTransactionDefinition
042: * @see org.springframework.transaction.interceptor.TransactionAttribute
043: */
044: public interface TransactionDefinition {
045:
046: /**
047: * Support a current transaction; create a new one if none exists.
048: * Analogous to the EJB transaction attribute of the same name.
049: * <p>This is typically the default setting of a transaction definition,
050: * and typically defines a transaction synchronization scope.
051: */
052: int PROPAGATION_REQUIRED = 0;
053:
054: /**
055: * Support a current transaction; execute non-transactionally if none exists.
056: * Analogous to the EJB transaction attribute of the same name.
057: * <p><b>NOTE:</b> For transaction managers with transaction synchronization,
058: * <code>PROPAGATION_SUPPORTS</code> is slightly different from no transaction
059: * at all, as it defines a transaction scope that synchronization might apply to.
060: * As a consequence, the same resources (a JDBC <code>Connection</code>, a
061: * Hibernate <code>Session</code>, etc) will be shared for the entire specified
062: * scope. Note that the exact behavior depends on the actual synchronization
063: * configuration of the transaction manager!
064: * <p>In general, use <code>PROPAGATION_SUPPORTS</code> with care! In particular, do
065: * not rely on <code>PROPAGATION_REQUIRED</code> or <code>PROPAGATION_REQUIRES_NEW</code>
066: * <i>within</i> a <code>PROPAGATION_SUPPORTS</code> scope (which may lead to
067: * synchronization conflicts at runtime). If such nesting is unavoidable, make sure
068: * to configure your transaction manager appropriately (typically switching to
069: * "synchronization on actual transaction").
070: * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#setTransactionSynchronization
071: * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#SYNCHRONIZATION_ON_ACTUAL_TRANSACTION
072: */
073: int PROPAGATION_SUPPORTS = 1;
074:
075: /**
076: * Support a current transaction; throw an exception if no current transaction
077: * exists. Analogous to the EJB transaction attribute of the same name.
078: * <p>Note that transaction synchronization within a <code>PROPAGATION_MANDATORY</code>
079: * scope will always be driven by the surrounding transaction.
080: */
081: int PROPAGATION_MANDATORY = 2;
082:
083: /**
084: * Create a new transaction, suspending the current transaction if one exists.
085: * Analogous to the EJB transaction attribute of the same name.
086: * <p><b>NOTE:</b> Actual transaction suspension will not work out-of-the-box
087: * on all transaction managers. This in particular applies to
088: * {@link org.springframework.transaction.jta.JtaTransactionManager},
089: * which requires the <code>javax.transaction.TransactionManager</code>
090: * to be made available it to it (which is server-specific in standard J2EE).
091: * <p>A <code>PROPAGATION_REQUIRES_NEW</code> scope always defines its own
092: * transaction synchronizations. Existing synchronizations will be suspended
093: * and resumed appropriately.
094: * @see org.springframework.transaction.jta.JtaTransactionManager#setTransactionManager
095: */
096: int PROPAGATION_REQUIRES_NEW = 3;
097:
098: /**
099: * 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: * Use the default isolation level of the underlying datastore.
136: * All other levels correspond to the JDBC isolation levels.
137: * @see java.sql.Connection
138: */
139: int ISOLATION_DEFAULT = -1;
140:
141: /**
142: * Indicates that dirty reads, non-repeatable reads and phantom reads
143: * can occur.
144: * <p>This level allows a row changed by one transaction to be read by
145: * another transaction before any changes in that row have been committed
146: * (a "dirty read"). If any of the changes are rolled back, the second
147: * transaction will have retrieved an invalid row.
148: * @see java.sql.Connection#TRANSACTION_READ_UNCOMMITTED
149: */
150: int ISOLATION_READ_UNCOMMITTED = Connection.TRANSACTION_READ_UNCOMMITTED;
151:
152: /**
153: * Indicates that dirty reads are prevented; non-repeatable reads and
154: * phantom reads can occur.
155: * <p>This level only prohibits a transaction from reading a row
156: * with uncommitted changes in it.
157: * @see java.sql.Connection#TRANSACTION_READ_COMMITTED
158: */
159: int ISOLATION_READ_COMMITTED = Connection.TRANSACTION_READ_COMMITTED;
160:
161: /**
162: * Indicates that dirty reads and non-repeatable reads are prevented;
163: * phantom reads can occur.
164: * <p>This level prohibits a transaction from reading a row with
165: * uncommitted changes in it, and it also prohibits the situation
166: * where one transaction reads a row, a second transaction alters
167: * the row, and the first transaction rereads the row, getting
168: * different values the second time (a "non-repeatable read").
169: * @see java.sql.Connection#TRANSACTION_REPEATABLE_READ
170: */
171: int ISOLATION_REPEATABLE_READ = Connection.TRANSACTION_REPEATABLE_READ;
172:
173: /**
174: * Indicates that dirty reads, non-repeatable reads and phantom reads
175: * are prevented.
176: * <p>This level includes the prohibitions in
177: * {@link #ISOLATION_REPEATABLE_READ} and further prohibits the
178: * situation where one transaction reads all rows that satisfy a
179: * <code>WHERE</code> condition, a second transaction inserts a
180: * row that satisfies that <code>WHERE</code> condition, and the
181: * first transaction rereads for the same condition, retrieving
182: * the additional "phantom" row in the second read.
183: * @see java.sql.Connection#TRANSACTION_SERIALIZABLE
184: */
185: int ISOLATION_SERIALIZABLE = Connection.TRANSACTION_SERIALIZABLE;
186:
187: /**
188: * Use the default timeout of the underlying transaction system,
189: * or none if timeouts are not supported.
190: */
191: int TIMEOUT_DEFAULT = -1;
192:
193: /**
194: * Return the propagation behavior.
195: * <p>Must return one of the <code>PROPAGATION_XXX</code> constants
196: * defined on {@link TransactionDefinition this interface}.
197: * @return the propagation behavior
198: * @see #PROPAGATION_REQUIRED
199: * @see org.springframework.transaction.support.TransactionSynchronizationManager#isActualTransactionActive()
200: */
201: int getPropagationBehavior();
202:
203: /**
204: * Return the isolation level.
205: * <p>Must return one of the <code>ISOLATION_XXX</code> constants
206: * defined on {@link TransactionDefinition this interface}.
207: * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
208: * or {@link #PROPAGATION_REQUIRES_NEW}.
209: * <p>Note that a transaction manager that does not support custom
210: * isolation levels will throw an exception when given any other level
211: * than {@link #ISOLATION_DEFAULT}.
212: * @return the isolation level
213: */
214: int getIsolationLevel();
215:
216: /**
217: * Return the transaction timeout.
218: * <p>Must return a number of seconds, or {@link #TIMEOUT_DEFAULT}.
219: * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
220: * or {@link #PROPAGATION_REQUIRES_NEW}.
221: * <p>Note that a transaction manager that does not support timeouts
222: * will throw an exception when given any other timeout than
223: * {@link #TIMEOUT_DEFAULT}.
224: * @return the transaction timeout
225: */
226: int getTimeout();
227:
228: /**
229: * Return whether to optimize as a read-only transaction.
230: * <p>The read-only flag applies to any transaction context, whether
231: * backed by an actual resource transaction
232: * ({@link #PROPAGATION_REQUIRED}/{@link #PROPAGATION_REQUIRES_NEW}) or
233: * operating non-transactionally at the resource level
234: * ({@link #PROPAGATION_SUPPORTS}). In the latter case, the flag will
235: * only apply to managed resources within the application, such as a
236: * Hibernate <code>Session</code>.
237: * <p>This just serves as a hint for the actual transaction subsystem;
238: * it will <i>not necessarily</i> cause failure of write access attempts.
239: * A transaction manager that cannot interpret the read-only hint will
240: * <i>not</i> throw an exception when asked for a read-only transaction.
241: * @return <code>true</code> if the transaction is to be optimized as read-only
242: * @see org.springframework.transaction.support.TransactionSynchronization#beforeCommit(boolean)
243: * @see org.springframework.transaction.support.TransactionSynchronizationManager#isCurrentTransactionReadOnly()
244: */
245: boolean isReadOnly();
246:
247: /**
248: * Return the name of this transaction. Can be <code>null</code>.
249: * <p>This will be used as the transaction name to be shown in a
250: * transaction monitor, if applicable (for example, WebLogic's).
251: * <p>In case of Spring's declarative transactions, the exposed name
252: * must (and will) be the
253: * <code>fully-qualified class name + "." + method name</code>
254: * (by default).
255: * @return the name of this transaction
256: * @see org.springframework.transaction.interceptor.TransactionAspectSupport
257: * @see org.springframework.transaction.support.TransactionSynchronizationManager#getCurrentTransactionName()
258: */
259: String getName();
260:
261: }
|