1 /*
2 * Copyright (c) 2013, 2018 Oracle and/or its affiliates. All rights reserved.
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v. 2.0, which is available at
6 * http://www.eclipse.org/legal/epl-2.0.
7 *
8 * This Source Code may also be made available under the following Secondary
9 * Licenses when the conditions for such availability set forth in the
10 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11 * version 2 with the GNU Classpath Exception, which is available at
12 * https://www.gnu.org/software/classpath/license.html.
13 *
14 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15 */
16
17 package javax.transaction;
18
19 import javax.enterprise.util.Nonbinding;
20 import javax.interceptor.InterceptorBinding;
21 import java.lang.annotation.*;
22
23 /**
24 * <p>The javax.transaction.Transactional annotation provides the application
25 * the ability to declaratively control transaction boundaries on CDI managed beans, as
26 * well as classes defined as managed beans by the Jakarta EE specification, at both the class
27 * and method level where method level annotations override those at the class level.</p>
28 * <p>See the Jakarta Enterprise Beans specification for restrictions on the use of @Transactional with Jakarta Enterprise Beans.</p>
29 * <p>This support is provided via an implementation of CDI interceptors that conduct the
30 * necessary suspending, resuming, etc. The Transactional interceptor interposes on business method
31 * invocations only and not on lifecycle events. Lifecycle methods are invoked in an unspecified
32 * transaction context.</p>
33 * <p>If an attempt is made to call any method of the UserTransaction interface from within the
34 * scope of a bean or method annotated with @Transactional and a Transactional.TxType other than
35 * NOT_SUPPORTED or NEVER, an IllegalStateException must be thrown. The use of the UserTransaction
36 * is allowed within life cycle events. The use of the TransactionSynchronizationRegistry is allowed
37 * regardless of any @Transactional annotation.</p>
38 * <p>The Transactional interceptors must have a priority of
39 * Interceptor.Priority.PLATFORM_BEFORE+200.
40 * Refer to the Interceptors specification for more details.</p>
41 * <p>The TxType element of the annotation indicates whether a bean method is to be executed within
42 * a transaction context. TxType.REQUIRED is the default. </p>
43 *
44 * <p>By default checked exceptions do not result in the transactional interceptor marking the
45 * transaction for rollback and instances of RuntimeException and its subclasses do. This default
46 * behavior can be modified by specifying exceptions that result in the interceptor marking the
47 * transaction for rollback and/or exceptions that do not result in rollback.</p>
48 * <p>The rollbackOn element can be set to indicate exceptions that must cause the interceptor to mark
49 * the transaction for rollback.</p>
50 * <p>Conversely, the dontRollbackOn element can be set to indicate
51 * exceptions that must not cause the interceptor to mark the transaction for rollback.</p>
52 * <p>When a class is specified for either of these elements, the designated behavior applies to subclasses
53 * of that class as well. If both elements are specified, dontRollbackOn takes precedence.</p>
54 *
55 * @since JTA 1.2
56 */
57 @Inherited
58 @InterceptorBinding
59 @Target({ElementType.TYPE, ElementType.METHOD})
60 @Retention(value = RetentionPolicy.RUNTIME)
61 public @interface Transactional {
62
63 /**
64 * The TxType element of the Transactional annotation indicates whether a bean method
65 * is to be executed within a transaction context.
66 */
67 TxType value() default TxType.REQUIRED;
68
69 /**
70 * The TxType element of the annotation indicates whether a bean method is to be
71 * executed within a transaction context where the values provide the following
72 * corresponding behavior.
73 */
74 public enum TxType {
75 /**
76 * <p>If called outside a transaction context, the interceptor must begin a new
77 * Jakarta Transactions transaction, the managed bean method execution must then continue
78 * inside this transaction context, and the transaction must be completed by
79 * the interceptor.</p>
80 * <p>If called inside a transaction context, the managed bean
81 * method execution must then continue inside this transaction context.</p>
82 */
83 REQUIRED,
84
85 /**
86 * <p>If called outside a transaction context, the interceptor must begin a new
87 * Jakarta Transactions transaction, the managed bean method execution must then continue
88 * inside this transaction context, and the transaction must be completed by
89 * the interceptor.</p>
90 * <p>If called inside a transaction context, the current transaction context must
91 * be suspended, a new Jakarta Transactions transaction will begin, the managed bean method
92 * execution must then continue inside this transaction context, the transaction
93 * must be completed, and the previously suspended transaction must be resumed.</p>
94 */
95 REQUIRES_NEW,
96
97 /**
98 * <p>If called outside a transaction context, a TransactionalException with a
99 * nested TransactionRequiredException must be thrown.</p>
100 * <p>If called inside a transaction context, managed bean method execution will
101 * then continue under that context.</p>
102 */
103 MANDATORY,
104
105 /**
106 * <p>If called outside a transaction context, managed bean method execution
107 * must then continue outside a transaction context.</p>
108 * <p>If called inside a transaction context, the managed bean method execution
109 * must then continue inside this transaction context.</p>
110 */
111 SUPPORTS,
112
113 /**
114 * <p>If called outside a transaction context, managed bean method execution
115 * must then continue outside a transaction context.</p>
116 * <p>If called inside a transaction context, the current transaction context must
117 * be suspended, the managed bean method execution must then continue
118 * outside a transaction context, and the previously suspended transaction
119 * must be resumed by the interceptor that suspended it after the method
120 * execution has completed.</p>
121 */
122 NOT_SUPPORTED,
123
124 /**
125 * <p>If called outside a transaction context, managed bean method execution
126 * must then continue outside a transaction context.</p>
127 * <p>If called inside a transaction context, a TransactionalException with
128 * a nested InvalidTransactionException must be thrown.</p>
129 */
130 NEVER
131 }
132
133 /**
134 * The rollbackOn element can be set to indicate exceptions that must cause
135 * the interceptor to mark the transaction for rollback. Conversely, the dontRollbackOn
136 * element can be set to indicate exceptions that must not cause the interceptor to mark
137 * the transaction for rollback. When a class is specified for either of these elements,
138 * the designated behavior applies to subclasses of that class as well. If both elements
139 * are specified, dontRollbackOn takes precedence.
140 * @return Class[] of Exceptions
141 */
142 @Nonbinding
143 public Class[] rollbackOn() default {};
144
145 /**
146 * The dontRollbackOn element can be set to indicate exceptions that must not cause
147 * the interceptor to mark the transaction for rollback. Conversely, the rollbackOn element
148 * can be set to indicate exceptions that must cause the interceptor to mark the transaction
149 * for rollback. When a class is specified for either of these elements,
150 * the designated behavior applies to subclasses of that class as well. If both elements
151 * are specified, dontRollbackOn takes precedence.
152 * @return Class[] of Exceptions
153 */
154 @Nonbinding
155 public Class[] dontRollbackOn() default {};
156
157 }
158