1 /*
2 * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.transaction.xa;
27
28 /**
29 * The XAResource interface is a Java mapping of the industry standard
30 * XA interface based on the X/Open CAE Specification (Distributed
31 * Transaction Processing: The XA Specification).
32 *
33 * <p>The XA interface defines the contract between a Resource Manager
34 * and a Transaction Manager in a distributed transaction processing
35 * (DTP) environment. A JDBC driver or a JMS provider implements
36 * this interface to support the association between a global transaction
37 * and a database or message service connection.
38 *
39 * <p>The XAResource interface can be supported by any transactional
40 * resource that is intended to be used by application programs in an
41 * environment where transactions are controlled by an external
42 * transaction manager. An example of such a resource is a database
43 * management system. An application may access data through multiple
44 * database connections. Each database connection is enlisted with
45 * the transaction manager as a transactional resource. The transaction
46 * manager obtains an XAResource for each connection participating
47 * in a global transaction. The transaction manager uses the
48 * <code>start</code> method
49 * to associate the global transaction with the resource, and it uses the
50 * <code>end</code> method to disassociate the transaction from
51 * the resource. The resource
52 * manager is responsible for associating the global transaction to all
53 * work performed on its data between the start and end method invocations.
54 *
55 * <p>At transaction commit time, the resource managers are informed by
56 * the transaction manager to prepare, commit, or rollback a transaction
57 * according to the two-phase commit protocol.</p>
58 *
59 * @since 1.4
60 */
61 public interface XAResource {
62
63 /**
64 * Commits the global transaction specified by xid.
65 *
66 * @param xid A global transaction identifier
67 *
68 * @param onePhase If true, the resource manager should use a one-phase
69 * commit protocol to commit the work done on behalf of xid.
70 *
71 * @exception XAException An error has occurred. Possible XAExceptions
72 * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR,
73 * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
74 *
75 * <P>If the resource manager did not commit the transaction and the
76 * paramether onePhase is set to true, the resource manager may throw
77 * one of the XA_RB* exceptions. Upon return, the resource manager has
78 * rolled back the branch's work and has released all held resources.
79 */
80 void commit(Xid xid, boolean onePhase) throws XAException;
81
82 /**
83 * Ends the work performed on behalf of a transaction branch.
84 * The resource manager disassociates the XA resource from the
85 * transaction branch specified and lets the transaction
86 * complete.
87 *
88 * <p>If TMSUSPEND is specified in the flags, the transaction branch
89 * is temporarily suspended in an incomplete state. The transaction
90 * context is in a suspended state and must be resumed via the
91 * <code>start</code> method with TMRESUME specified.</p>
92 *
93 * <p>If TMFAIL is specified, the portion of work has failed.
94 * The resource manager may mark the transaction as rollback-only</p>
95 *
96 * <p>If TMSUCCESS is specified, the portion of work has completed
97 * successfully.</p>
98 *
99 * @param xid A global transaction identifier that is the same as
100 * the identifier used previously in the <code>start</code> method.
101 *
102 * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND.
103 *
104 * @exception XAException An error has occurred. Possible XAException
105 * values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL,
106 * XAER_PROTO, or XA_RB*.
107 */
108 void end(Xid xid, int flags) throws XAException;
109
110 /**
111 * Tells the resource manager to forget about a heuristically
112 * completed transaction branch.
113 *
114 * @param xid A global transaction identifier.
115 *
116 * @exception XAException An error has occurred. Possible exception
117 * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or
118 * XAER_PROTO.
119 */
120 void forget(Xid xid) throws XAException;
121
122 /**
123 * Obtains the current transaction timeout value set for this
124 * XAResource instance. If <CODE>XAResource.setTransactionTimeout</CODE>
125 * was not used prior to invoking this method, the return value
126 * is the default timeout set for the resource manager; otherwise,
127 * the value used in the previous <CODE>setTransactionTimeout</CODE>
128 * call is returned.
129 *
130 * @return the transaction timeout value in seconds.
131 *
132 * @exception XAException An error has occurred. Possible exception
133 * values are XAER_RMERR and XAER_RMFAIL.
134 */
135 int getTransactionTimeout() throws XAException;
136
137 /**
138 * This method is called to determine if the resource manager
139 * instance represented by the target object is the same as the
140 * resouce manager instance represented by the parameter <i>xares</i>.
141 *
142 * @param xares An XAResource object whose resource manager instance
143 * is to be compared with the resource manager instance of the
144 * target object.
145 *
146 * @return <i>true</i> if it's the same RM instance; otherwise
147 * <i>false</i>.
148 *
149 * @exception XAException An error has occurred. Possible exception
150 * values are XAER_RMERR and XAER_RMFAIL.
151 */
152 boolean isSameRM(XAResource xares) throws XAException;
153
154 /**
155 * Ask the resource manager to prepare for a transaction commit
156 * of the transaction specified in xid.
157 *
158 * @param xid A global transaction identifier.
159 *
160 * @exception XAException An error has occurred. Possible exception
161 * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
162 * or XAER_PROTO.
163 *
164 * @return A value indicating the resource manager's vote on the
165 * outcome of the transaction. The possible values are: XA_RDONLY
166 * or XA_OK. If the resource manager wants to roll back the
167 * transaction, it should do so by raising an appropriate XAException
168 * in the prepare method.
169 */
170 int prepare(Xid xid) throws XAException;
171
172 /**
173 * Obtains a list of prepared transaction branches from a resource
174 * manager. The transaction manager calls this method during recovery
175 * to obtain the list of transaction branches that are currently in
176 * prepared or heuristically completed states.
177 *
178 * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
179 * must be used when no other flags are set in the parameter.
180 *
181 * @exception XAException An error has occurred. Possible values are
182 * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
183 *
184 * @return The resource manager returns zero or more XIDs of the
185 * transaction branches that are currently in a prepared or
186 * heuristically completed state. If an error occurs during the
187 * operation, the resource manager should throw the appropriate
188 * XAException.
189 */
190 Xid[] recover(int flag) throws XAException;
191
192 /**
193 * Informs the resource manager to roll back work done on behalf
194 * of a transaction branch.
195 *
196 * @param xid A global transaction identifier.
197 *
198 * @exception XAException An error has occurred.
199 */
200 void rollback(Xid xid) throws XAException;
201
202 /**
203 * Sets the current transaction timeout value for this <CODE>XAResource</CODE>
204 * instance. Once set, this timeout value is effective until
205 * <code>setTransactionTimeout</code> is invoked again with a different
206 * value. To reset the timeout value to the default value used by the resource
207 * manager, set the value to zero.
208 *
209 * If the timeout operation is performed successfully, the method returns
210 * <i>true</i>; otherwise <i>false</i>. If a resource manager does not
211 * support explicitly setting the transaction timeout value, this method
212 * returns <i>false</i>.
213 *
214 * @param seconds The transaction timeout value in seconds.
215 *
216 * @return <i>true</i> if the transaction timeout value is set successfully;
217 * otherwise <i>false</i>.
218 *
219 * @exception XAException An error has occurred. Possible exception values
220 * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
221 */
222 boolean setTransactionTimeout(int seconds) throws XAException;
223
224 /**
225 * Starts work on behalf of a transaction branch specified in
226 * <code>xid</code>.
227 *
228 * If TMJOIN is specified, the start applies to joining a transaction
229 * previously seen by the resource manager. If TMRESUME is specified,
230 * the start applies to resuming a suspended transaction specified in the
231 * parameter <code>xid</code>.
232 *
233 * If neither TMJOIN nor TMRESUME is specified and the transaction
234 * specified by <code>xid</code> has previously been seen by the resource
235 * manager, the resource manager throws the XAException exception with
236 * XAER_DUPID error code.
237 *
238 * @param xid A global transaction identifier to be associated
239 * with the resource.
240 *
241 * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME.
242 *
243 * @exception XAException An error has occurred. Possible exceptions
244 * are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE,
245 * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
246 */
247 void start(Xid xid, int flags) throws XAException;
248
249 /**
250 * Ends a recovery scan.
251 */
252 public final static int TMENDRSCAN = 0x00800000;
253
254 /**
255 * Disassociates the caller and marks the transaction branch
256 * rollback-only.
257 */
258 public final static int TMFAIL = 0x20000000;
259
260 /**
261 * Caller is joining existing transaction branch.
262 */
263 public final static int TMJOIN = 0x00200000;
264
265 /**
266 * Use TMNOFLAGS to indicate no flags value is selected.
267 */
268 public final static int TMNOFLAGS = 0x00000000;
269
270 /**
271 * Caller is using one-phase optimization.
272 */
273 public final static int TMONEPHASE = 0x40000000;
274
275 /**
276 * Caller is resuming association with a suspended
277 * transaction branch.
278 */
279 public final static int TMRESUME = 0x08000000;
280
281 /**
282 * Starts a recovery scan.
283 */
284 public final static int TMSTARTRSCAN = 0x01000000;
285
286 /**
287 * Disassociates caller from a transaction branch.
288 */
289 public final static int TMSUCCESS = 0x04000000;
290
291 /**
292 * Caller is suspending (not ending) its association with
293 * a transaction branch.
294 */
295 public final static int TMSUSPEND = 0x02000000;
296
297 /**
298 * The transaction branch has been read-only and has been committed.
299 */
300 public final static int XA_RDONLY = 0x00000003;
301
302 /**
303 * The transaction work has been prepared normally.
304 */
305 public final static int XA_OK = 0;
306 }