1 /*
2 * Copyright 2009-2023 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 * https://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 package org.mybatis.guice.transactional;
17
18 import java.lang.annotation.ElementType;
19 import java.lang.annotation.Retention;
20 import java.lang.annotation.RetentionPolicy;
21 import java.lang.annotation.Target;
22
23 import org.apache.ibatis.session.ExecutorType;
24 import org.apache.ibatis.session.TransactionIsolationLevel;
25
26 /**
27 * Any method marked with this annotation will be considered for transactionality.
28 */
29 @Retention(RetentionPolicy.RUNTIME)
30 @Target({ ElementType.METHOD, ElementType.TYPE })
31 public @interface Transactional {
32
33 /**
34 * Returns the constant indicating the myBatis executor type.
35 *
36 * @return the constant indicating the myBatis executor type.
37 */
38 ExecutorType executorType() default ExecutorType.SIMPLE;
39
40 /**
41 * Returns the constant indicating the transaction isolation level.
42 *
43 * @return the constant indicating the transaction isolation level.
44 */
45 Isolation isolation() default Isolation.DEFAULT;
46
47 /**
48 * Returns the constant indicating the transaction isolation level.
49 *
50 * @return the constant indicating the transaction isolation level.
51 *
52 * @deprecated use {@link #isolation()} instead, setting this property has no effect.
53 */
54 @Deprecated
55 TransactionIsolationLevel isolationLevel() default TransactionIsolationLevel.NONE;
56
57 /**
58 * Flag to indicate that myBatis has to force the transaction {@code commit().}
59 *
60 * @return false by default, user defined otherwise.
61 */
62 boolean force() default false;
63
64 /**
65 * Flag to indicate the auto commit policy.
66 *
67 * @return false by default, user defined otherwise.
68 *
69 * @deprecated Users that intend auto commit can achieve it by simply not using {@literal @Transactional}
70 */
71 @Deprecated
72 boolean autoCommit() default false;
73
74 /**
75 * The exception re-thrown when an error occurs during the transaction.
76 *
77 * @return the exception re-thrown when an error occurs during the transaction.
78 */
79 Class<? extends Throwable> rethrowExceptionsAs() default Exception.class;
80
81 /**
82 * A custom error message when throwing the custom exception.
83 * <p>
84 * It supports java.util.Formatter place holders, intercepted method arguments will be used as message format
85 * arguments.
86 *
87 * @return a custom error message when throwing the custom exception.
88 *
89 * @see java.util.Formatter#format(String, Object...)
90 */
91 String exceptionMessage() default "";
92
93 /**
94 * If true, the transaction will never committed but rather rolled back, useful for testing purposes.
95 * <p>
96 * This parameter is false by default.
97 *
98 * @return if true, the transaction will never committed but rather rolled back, useful for testing purposes.
99 */
100 boolean rollbackOnly() default false;
101
102 //
103 // from jakarta.transaction.Transactional
104 //
105
106 /**
107 * The TxType element of the Transactional annotation indicates whether a bean method is to be executed within a
108 * transaction context.
109 *
110 * @return the tx type
111 */
112 TxType value() default TxType.REQUIRED;
113
114 /**
115 * The TxType element of the annotation indicates whether a bean method is to be executed within a transaction context
116 * where the values provide the following corresponding behavior.
117 */
118 public enum TxType {
119 /**
120 * <p>
121 * If called outside a transaction context, the interceptor must begin a new JTA transaction, the managed bean
122 * method execution must then continue inside this transaction context, and the transaction must be completed by the
123 * interceptor.
124 * </p>
125 * <p>
126 * If called inside a transaction context, the managed bean method execution must then continue inside this
127 * transaction context.
128 * </p>
129 */
130 REQUIRED,
131
132 /**
133 * <p>
134 * If called outside a transaction context, the interceptor must begin a new JTA transaction, the managed bean
135 * method execution must then continue inside this transaction context, and the transaction must be completed by the
136 * interceptor.
137 * </p>
138 * <p>
139 * If called inside a transaction context, the current transaction context must be suspended, a new JTA transaction
140 * will begin, the managed bean method execution must then continue inside this transaction context, the transaction
141 * must be completed, and the previously suspended transaction must be resumed.
142 * </p>
143 */
144 REQUIRES_NEW,
145
146 /**
147 * <p>
148 * If called outside a transaction context, a TransactionalException with a nested TransactionRequiredException must
149 * be thrown.
150 * </p>
151 * <p>
152 * If called inside a transaction context, managed bean method execution will then continue under that context.
153 * </p>
154 */
155 MANDATORY,
156
157 /**
158 * <p>
159 * If called outside a transaction context, managed bean method execution must then continue outside a transaction
160 * context.
161 * </p>
162 * <p>
163 * If called inside a transaction context, the managed bean method execution must then continue inside this
164 * transaction context.
165 * </p>
166 */
167 SUPPORTS,
168
169 /**
170 * <p>
171 * If called outside a transaction context, managed bean method execution must then continue outside a transaction
172 * context.
173 * </p>
174 * <p>
175 * If called inside a transaction context, the current transaction context must be suspended, the managed bean
176 * method execution must then continue outside a transaction context, and the previously suspended transaction must
177 * be resumed by the interceptor that suspended it after the method execution has completed.
178 * </p>
179 */
180 NOT_SUPPORTED,
181
182 /**
183 * <p>
184 * If called outside a transaction context, managed bean method execution must then continue outside a transaction
185 * context.
186 * </p>
187 * <p>
188 * If called inside a transaction context, a TransactionalException with a nested InvalidTransactionException must
189 * be thrown.
190 * </p>
191 */
192 NEVER
193 }
194
195 /**
196 * The rollbackOn element can be set to indicate exceptions that must cause the interceptor to mark the transaction
197 * for rollback. Conversely, the dontRollbackOn element can be set to indicate exceptions that must not cause the
198 * interceptor to mark the transaction for rollback. When a class is specified for either of these elements, the
199 * designated behavior applies to subclasses of that class as well. If both elements are specified, dontRollbackOn
200 * takes precedence.
201 *
202 * @return Class[] of Exceptions
203 */
204 // @Nonbinding
205 // public Class[] rollbackOn() default {};
206
207 /**
208 * The dontRollbackOn element can be set to indicate exceptions that must not cause the interceptor to mark the
209 * transaction for rollback. Conversely, the rollbackOn element can be set to indicate exceptions that must cause the
210 * interceptor to mark the transaction for rollback. When a class is specified for either of these elements, the
211 * designated behavior applies to subclasses of that class as well. If both elements are specified, dontRollbackOn
212 * takes precedence.
213 *
214 * @return Class[] of Exceptions
215 */
216 // @Nonbinding
217 // public Class[] dontRollbackOn() default {};
218
219 }