1 /*
2 * The contents of this file are subject to the terms
3 * of the Common Development and Distribution License
4 * (the License). You may not use this file except in
5 * compliance with the License.
6 *
7 * You can obtain a copy of the license at
8 * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9 * glassfish/bootstrap/legal/CDDLv1.0.txt.
10 * See the License for the specific language governing
11 * permissions and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL
14 * Header Notice in each file and include the License file
15 * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16 * If applicable, add the following below the CDDL Header,
17 * with the fields enclosed by brackets [] replaced by
18 * you own identifying information:
19 * "Portions Copyrighted [year] [name of copyright owner]"
20 *
21 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22 */
23
24 package javax.transaction;
25
26 import javax.transaction.xa.XAResource;
27 import java.lang.IllegalStateException;
28 import java.lang.SecurityException;
29
30 /**
31 * The Transaction interface allows operations to be performed against
32 * the transaction in the target Transaction object. A Transaction
33 * object is created corresponding to each global transaction creation.
34 * The Transaction object can be used for resource enlistment,
35 * synchronization registration, transaction completion, and status
36 * query operations.
37 */
38
39 public interface Transaction {
40
41 /**
42 * Complete the transaction represented by this Transaction object.
43 *
44 * @exception RollbackException Thrown to indicate that
45 * the transaction has been rolled back rather than committed.
46 *
47 * @exception HeuristicMixedException Thrown to indicate that a heuristic
48 * decision was made and that some relevant updates have been committed
49 * while others have been rolled back.
50 *
51 * @exception HeuristicRollbackException Thrown to indicate that a
52 * heuristic decision was made and that all relevant updates have been
53 * rolled back.
54 *
55 * @exception SecurityException Thrown to indicate that the thread is
56 * not allowed to commit the transaction.
57 *
58 * @exception IllegalStateException Thrown if the transaction in the
59 * target object is inactive.
60 *
61 * @exception SystemException Thrown if the transaction manager
62 * encounters an unexpected error condition.
63 */
64 public void commit() throws RollbackException,
65 HeuristicMixedException, HeuristicRollbackException,
66 SecurityException, IllegalStateException, SystemException;
67
68 /**
69 * Disassociate the resource specified from the transaction associated
70 * with the target Transaction object.
71 *
72 * @param xaRes The XAResource object associated with the resource
73 * (connection).
74 *
75 * @param flag One of the values of TMSUCCESS, TMSUSPEND, or TMFAIL.
76 *
77 * @exception IllegalStateException Thrown if the transaction in the
78 * target object is inactive.
79 *
80 * @exception SystemException Thrown if the transaction manager
81 * encounters an unexpected error condition.
82 *
83 * @return <i>true</i> if the resource was delisted successfully; otherwise
84 * <i>false</i>.
85 *
86 */
87 public boolean delistResource(XAResource xaRes, int flag)
88 throws IllegalStateException, SystemException;
89
90 /**
91 * Enlist the resource specified with the transaction associated with the
92 * target Transaction object.
93 *
94 * @param xaRes The XAResource object associated with the resource
95 * (connection).
96 *
97 * @return <i>true</i> if the resource was enlisted successfully; otherwise
98 * <i>false</i>.
99 *
100 * @exception RollbackException Thrown to indicate that
101 * the transaction has been marked for rollback only.
102 *
103 * @exception IllegalStateException Thrown if the transaction in the
104 * target object is in the prepared state or the transaction is
105 * inactive.
106 *
107 * @exception SystemException Thrown if the transaction manager
108 * encounters an unexpected error condition.
109 *
110 */
111 public boolean enlistResource(XAResource xaRes)
112 throws RollbackException, IllegalStateException,
113 SystemException;
114
115 /**
116 * Obtain the status of the transaction associated with the target
117 * Transaction object.
118 *
119 * @return The transaction status. If no transaction is associated with
120 * the target object, this method returns the
121 * Status.NoTransaction value.
122 *
123 * @exception SystemException Thrown if the transaction manager
124 * encounters an unexpected error condition.
125 *
126 */
127 public int getStatus() throws SystemException;
128
129 /**
130 * Register a synchronization object for the transaction currently
131 * associated with the target object. The transction manager invokes
132 * the beforeCompletion method prior to starting the two-phase transaction
133 * commit process. After the transaction is completed, the transaction
134 * manager invokes the afterCompletion method.
135 *
136 * @param sync The Synchronization object for the transaction associated
137 * with the target object.
138 *
139 * @exception RollbackException Thrown to indicate that
140 * the transaction has been marked for rollback only.
141 *
142 * @exception IllegalStateException Thrown if the transaction in the
143 * target object is in the prepared state or the transaction is
144 * inactive.
145 *
146 * @exception SystemException Thrown if the transaction manager
147 * encounters an unexpected error condition.
148 *
149 */
150 public void registerSynchronization(Synchronization sync)
151 throws RollbackException, IllegalStateException,
152 SystemException;
153
154 /**
155 * Rollback the transaction represented by this Transaction object.
156 *
157 * @exception IllegalStateException Thrown if the transaction in the
158 * target object is in the prepared state or the transaction is
159 * inactive.
160 *
161 * @exception SystemException Thrown if the transaction manager
162 * encounters an unexpected error condition.
163 *
164 */
165 public void rollback() throws IllegalStateException, SystemException;
166
167 /**
168 * Modify the transaction associated with the target object such that
169 * the only possible outcome of the transaction is to roll back the
170 * transaction.
171 *
172 * @exception IllegalStateException Thrown if the target object is
173 * not associated with any transaction.
174 *
175 * @exception SystemException Thrown if the transaction manager
176 * encounters an unexpected error condition.
177 *
178 */
179 public void setRollbackOnly() throws IllegalStateException,
180 SystemException;
181
182 }