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