001/* 002 * Copyright 2002-2017 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 * https://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 017package org.springframework.transaction; 018 019import 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}. 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 */ 044public 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} 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}, a 061 * Hibernate {@code Session}, 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} with care! In particular, do 065 * not rely on {@code PROPAGATION_REQUIRED} or {@code PROPAGATION_REQUIRES_NEW} 066 * <i>within</i> a {@code PROPAGATION_SUPPORTS} 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} 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} to be 090 * made available it to it (which is server-specific in standard Java EE). 091 * <p>A {@code PROPAGATION_REQUIRES_NEW} 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} to be 105 * made available it to it (which is server-specific in standard Java EE). 106 * <p>Note that transaction synchronization is <i>not</i> available within a 107 * {@code PROPAGATION_NOT_SUPPORTED} 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} 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 126 * specific 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 another 146 * transaction before any changes in that row have been committed (a "dirty read"). 147 * If any of the changes are rolled back, the second transaction will have 148 * 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 uncommitted changes 166 * in it, and it also prohibits the situation where one transaction reads a row, 167 * a second transaction alters the row, and the first transaction re-reads the row, 168 * getting 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 {@link #ISOLATION_REPEATABLE_READ} 177 * and further prohibits the situation where one transaction reads all rows that 178 * satisfy a {@code WHERE} condition, a second transaction inserts a row 179 * that satisfies that {@code WHERE} condition, and the first transaction 180 * re-reads for the same condition, retrieving the additional "phantom" row 181 * in the second read. 182 * @see java.sql.Connection#TRANSACTION_SERIALIZABLE 183 */ 184 int ISOLATION_SERIALIZABLE = Connection.TRANSACTION_SERIALIZABLE; 185 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 /** 195 * Return the propagation behavior. 196 * <p>Must return one of the {@code PROPAGATION_XXX} constants 197 * defined on {@link TransactionDefinition this interface}. 198 * @return the propagation behavior 199 * @see #PROPAGATION_REQUIRED 200 * @see org.springframework.transaction.support.TransactionSynchronizationManager#isActualTransactionActive() 201 */ 202 int getPropagationBehavior(); 203 204 /** 205 * Return the isolation level. 206 * <p>Must return one of the {@code ISOLATION_XXX} constants defined on 207 * {@link TransactionDefinition this interface}. Those constants are designed 208 * to match the values of the same constants on {@link java.sql.Connection}. 209 * <p>Exclusively designed for use with {@link #PROPAGATION_REQUIRED} or 210 * {@link #PROPAGATION_REQUIRES_NEW} since it only applies to newly started 211 * transactions. Consider switching the "validateExistingTransactions" flag to 212 * "true" on your transaction manager if you'd like isolation level declarations 213 * to get rejected when participating in an existing transaction with a different 214 * isolation level. 215 * <p>Note that a transaction manager that does not support custom isolation levels 216 * will throw an exception when given any other level than {@link #ISOLATION_DEFAULT}. 217 * @return the isolation level 218 * @see #ISOLATION_DEFAULT 219 * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#setValidateExistingTransaction 220 */ 221 int getIsolationLevel(); 222 223 /** 224 * Return the transaction timeout. 225 * <p>Must return a number of seconds, or {@link #TIMEOUT_DEFAULT}. 226 * <p>Exclusively designed for use with {@link #PROPAGATION_REQUIRED} or 227 * {@link #PROPAGATION_REQUIRES_NEW} since it only applies to newly started 228 * transactions. 229 * <p>Note that a transaction manager that does not support timeouts will throw 230 * an exception when given any other timeout than {@link #TIMEOUT_DEFAULT}. 231 * @return the transaction timeout 232 */ 233 int getTimeout(); 234 235 /** 236 * Return whether to optimize as a read-only transaction. 237 * <p>The read-only flag applies to any transaction context, whether backed 238 * by an actual resource transaction ({@link #PROPAGATION_REQUIRED}/ 239 * {@link #PROPAGATION_REQUIRES_NEW}) or operating non-transactionally at 240 * the resource level ({@link #PROPAGATION_SUPPORTS}). In the latter case, 241 * the flag will only apply to managed resources within the application, 242 * such as a Hibernate {@code Session}. 243 * <p>This just serves as a hint for the actual transaction subsystem; 244 * it will <i>not necessarily</i> cause failure of write access attempts. 245 * A transaction manager which cannot interpret the read-only hint will 246 * <i>not</i> throw an exception when asked for a read-only transaction. 247 * @return {@code true} if the transaction is to be optimized as read-only 248 * @see org.springframework.transaction.support.TransactionSynchronization#beforeCommit(boolean) 249 * @see org.springframework.transaction.support.TransactionSynchronizationManager#isCurrentTransactionReadOnly() 250 */ 251 boolean isReadOnly(); 252 253 /** 254 * Return the name of this transaction. Can be {@code null}. 255 * <p>This will be used as the transaction name to be shown in a 256 * transaction monitor, if applicable (for example, WebLogic's). 257 * <p>In case of Spring's declarative transactions, the exposed name will be 258 * the {@code fully-qualified class name + "." + method name} (by default). 259 * @return the name of this transaction 260 * @see org.springframework.transaction.interceptor.TransactionAspectSupport 261 * @see org.springframework.transaction.support.TransactionSynchronizationManager#getCurrentTransactionName() 262 */ 263 String getName(); 264 265}