001/* 002 * Copyright 2002-2020 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.annotation; 018 019import java.lang.annotation.Documented; 020import java.lang.annotation.ElementType; 021import java.lang.annotation.Inherited; 022import java.lang.annotation.Retention; 023import java.lang.annotation.RetentionPolicy; 024import java.lang.annotation.Target; 025 026import org.springframework.core.annotation.AliasFor; 027import org.springframework.transaction.TransactionDefinition; 028 029/** 030 * Describes a transaction attribute on an individual method or on a class. 031 * 032 * <p>At the class level, this annotation applies as a default to all methods of 033 * the declaring class and its subclasses. Note that it does not apply to ancestor 034 * classes up the class hierarchy; methods need to be locally redeclared in order 035 * to participate in a subclass-level annotation. 036 * 037 * <p>This annotation type is generally directly comparable to Spring's 038 * {@link org.springframework.transaction.interceptor.RuleBasedTransactionAttribute} 039 * class, and in fact {@link AnnotationTransactionAttributeSource} will directly 040 * convert the data to the latter class, so that Spring's transaction support code 041 * does not have to know about annotations. If no custom rollback rules apply, 042 * the transaction will roll back on {@link RuntimeException} and {@link Error} 043 * but not on checked exceptions. 044 * 045 * <p>For specific information about the semantics of this annotation's attributes, 046 * consult the {@link org.springframework.transaction.TransactionDefinition} and 047 * {@link org.springframework.transaction.interceptor.TransactionAttribute} javadocs. 048 * 049 * <p>This annotation commonly works with thread-bound transactions managed by 050 * {@link org.springframework.transaction.PlatformTransactionManager}, exposing a 051 * transaction to all data access operations within the current execution thread. 052 * <b>Note: This does NOT propagate to newly started threads within the method.</b> 053 * 054 * <p>Alternatively, this annotation may demarcate a reactive transaction managed 055 * by {@link org.springframework.transaction.ReactiveTransactionManager} which 056 * uses the Reactor context instead of thread-local attributes. As a consequence, 057 * all participating data access operations need to execute within the same 058 * Reactor context in the same reactive pipeline. 059 * 060 * @author Colin Sampaleanu 061 * @author Juergen Hoeller 062 * @author Sam Brannen 063 * @since 1.2 064 * @see org.springframework.transaction.interceptor.TransactionAttribute 065 * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute 066 * @see org.springframework.transaction.interceptor.RuleBasedTransactionAttribute 067 */ 068@Target({ElementType.TYPE, ElementType.METHOD}) 069@Retention(RetentionPolicy.RUNTIME) 070@Inherited 071@Documented 072public @interface Transactional { 073 074 /** 075 * Alias for {@link #transactionManager}. 076 * @see #transactionManager 077 */ 078 @AliasFor("transactionManager") 079 String value() default ""; 080 081 /** 082 * A <em>qualifier</em> value for the specified transaction. 083 * <p>May be used to determine the target transaction manager, matching the 084 * qualifier value (or the bean name) of a specific 085 * {@link org.springframework.transaction.TransactionManager TransactionManager} 086 * bean definition. 087 * @since 4.2 088 * @see #value 089 * @see org.springframework.transaction.PlatformTransactionManager 090 * @see org.springframework.transaction.ReactiveTransactionManager 091 */ 092 @AliasFor("value") 093 String transactionManager() default ""; 094 095 /** 096 * The transaction propagation type. 097 * <p>Defaults to {@link Propagation#REQUIRED}. 098 * @see org.springframework.transaction.interceptor.TransactionAttribute#getPropagationBehavior() 099 */ 100 Propagation propagation() default Propagation.REQUIRED; 101 102 /** 103 * The transaction isolation level. 104 * <p>Defaults to {@link Isolation#DEFAULT}. 105 * <p>Exclusively designed for use with {@link Propagation#REQUIRED} or 106 * {@link Propagation#REQUIRES_NEW} since it only applies to newly started 107 * transactions. Consider switching the "validateExistingTransactions" flag to 108 * "true" on your transaction manager if you'd like isolation level declarations 109 * to get rejected when participating in an existing transaction with a different 110 * isolation level. 111 * @see org.springframework.transaction.interceptor.TransactionAttribute#getIsolationLevel() 112 * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#setValidateExistingTransaction 113 */ 114 Isolation isolation() default Isolation.DEFAULT; 115 116 /** 117 * The timeout for this transaction (in seconds). 118 * <p>Defaults to the default timeout of the underlying transaction system. 119 * <p>Exclusively designed for use with {@link Propagation#REQUIRED} or 120 * {@link Propagation#REQUIRES_NEW} since it only applies to newly started 121 * transactions. 122 * @see org.springframework.transaction.interceptor.TransactionAttribute#getTimeout() 123 */ 124 int timeout() default TransactionDefinition.TIMEOUT_DEFAULT; 125 126 /** 127 * A boolean flag that can be set to {@code true} if the transaction is 128 * effectively read-only, allowing for corresponding optimizations at runtime. 129 * <p>Defaults to {@code false}. 130 * <p>This just serves as a hint for the actual transaction subsystem; 131 * it will <i>not necessarily</i> cause failure of write access attempts. 132 * A transaction manager which cannot interpret the read-only hint will 133 * <i>not</i> throw an exception when asked for a read-only transaction 134 * but rather silently ignore the hint. 135 * @see org.springframework.transaction.interceptor.TransactionAttribute#isReadOnly() 136 * @see org.springframework.transaction.support.TransactionSynchronizationManager#isCurrentTransactionReadOnly() 137 */ 138 boolean readOnly() default false; 139 140 /** 141 * Defines zero (0) or more exception {@link Class classes}, which must be 142 * subclasses of {@link Throwable}, indicating which exception types must cause 143 * a transaction rollback. 144 * <p>By default, a transaction will be rolling back on {@link RuntimeException} 145 * and {@link Error} but not on checked exceptions (business exceptions). See 146 * {@link org.springframework.transaction.interceptor.DefaultTransactionAttribute#rollbackOn(Throwable)} 147 * for a detailed explanation. 148 * <p>This is the preferred way to construct a rollback rule (in contrast to 149 * {@link #rollbackForClassName}), matching the exception class and its subclasses. 150 * <p>Similar to {@link org.springframework.transaction.interceptor.RollbackRuleAttribute#RollbackRuleAttribute(Class clazz)}. 151 * @see #rollbackForClassName 152 * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute#rollbackOn(Throwable) 153 */ 154 Class<? extends Throwable>[] rollbackFor() default {}; 155 156 /** 157 * Defines zero (0) or more exception names (for exceptions which must be a 158 * subclass of {@link Throwable}), indicating which exception types must cause 159 * a transaction rollback. 160 * <p>This can be a substring of a fully qualified class name, with no wildcard 161 * support at present. For example, a value of {@code "ServletException"} would 162 * match {@code javax.servlet.ServletException} and its subclasses. 163 * <p><b>NB:</b> Consider carefully how specific the pattern is and whether 164 * to include package information (which isn't mandatory). For example, 165 * {@code "Exception"} will match nearly anything and will probably hide other 166 * rules. {@code "java.lang.Exception"} would be correct if {@code "Exception"} 167 * were meant to define a rule for all checked exceptions. With more unusual 168 * {@link Exception} names such as {@code "BaseBusinessException"} there is no 169 * need to use a FQN. 170 * <p>Similar to {@link org.springframework.transaction.interceptor.RollbackRuleAttribute#RollbackRuleAttribute(String exceptionName)}. 171 * @see #rollbackFor 172 * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute#rollbackOn(Throwable) 173 */ 174 String[] rollbackForClassName() default {}; 175 176 /** 177 * Defines zero (0) or more exception {@link Class Classes}, which must be 178 * subclasses of {@link Throwable}, indicating which exception types must 179 * <b>not</b> cause a transaction rollback. 180 * <p>This is the preferred way to construct a rollback rule (in contrast 181 * to {@link #noRollbackForClassName}), matching the exception class and 182 * its subclasses. 183 * <p>Similar to {@link org.springframework.transaction.interceptor.NoRollbackRuleAttribute#NoRollbackRuleAttribute(Class clazz)}. 184 * @see #noRollbackForClassName 185 * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute#rollbackOn(Throwable) 186 */ 187 Class<? extends Throwable>[] noRollbackFor() default {}; 188 189 /** 190 * Defines zero (0) or more exception names (for exceptions which must be a 191 * subclass of {@link Throwable}) indicating which exception types must <b>not</b> 192 * cause a transaction rollback. 193 * <p>See the description of {@link #rollbackForClassName} for further 194 * information on how the specified names are treated. 195 * <p>Similar to {@link org.springframework.transaction.interceptor.NoRollbackRuleAttribute#NoRollbackRuleAttribute(String exceptionName)}. 196 * @see #noRollbackFor 197 * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute#rollbackOn(Throwable) 198 */ 199 String[] noRollbackForClassName() default {}; 200 201}