001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.transaction.xa;
027
028 /** <p>The XAResource interface is a Java mapping of the industry standard
029 * XA interface based on the X/Open CAE Specification (Distributed
030 * Transaction Processing: The XA Specification).
031 *
032 * <p>The XA interface defines the contract between a Resource Manager
033 * and a Transaction Manager in a distributed transaction processing
034 * (DTP) environment. A JDBC driver or a JMS provider implements
035 * this interface to support the association between a global transaction
036 * and a database or message service connection.
037 *
038 * <p>The XAResource interface can be supported by any transactional
039 * resource that is intended to be used by application programs in an
040 * environment where transactions are controlled by an external
041 * transaction manager. An example of such a resource is a database
042 * management system. An application may access data through multiple
043 * database connections. Each database connection is enlisted with
044 * the transaction manager as a transactional resource. The transaction
045 * manager obtains an XAResource for each connection participating
046 * in a global transaction. The transaction manager uses the
047 * <code>start</code> method
048 * to associate the global transaction with the resource, and it uses the
049 * <code>end</code> method to disassociate the transaction from
050 * the resource. The resource
051 * manager is responsible for associating the global transaction to all
052 * work performed on its data between the start and end method invocations.
053 *
054 * <p>At transaction commit time, the resource managers are informed by
055 * the transaction manager to prepare, commit, or rollback a transaction
056 * according to the two-phase commit protocol.</p>
057 *
058 */
059
060 public interface XAResource {
061 /** Commits the global transaction specified by xid.
062 *
063 * @param xid A global transaction identifier
064 *
065 * @param onePhase If true, the resource manager should use a one-phase
066 * commit protocol to commit the work done on behalf of xid.
067 *
068 * @exception XAException An error has occurred. Possible XAExceptions
069 * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR,
070 * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
071 *
072 * <P>If the resource manager did not commit the transaction and the
073 * paramether onePhase is set to true, the resource manager may throw
074 * one of the XA_RB* exceptions. Upon return, the resource manager has
075 * rolled back the branch's work and has released all held resources.
076 */
077
078 void commit(Xid xid, boolean onePhase) throws XAException;
079
080 /** Ends the work performed on behalf of a transaction branch.
081 * The resource manager disassociates the XA resource from the
082 * transaction branch specified and lets the transaction
083 * complete.
084 *
085 * <p>If TMSUSPEND is specified in the flags, the transaction branch
086 * is temporarily suspended in an incomplete state. The transaction
087 * context is in a suspended state and must be resumed via the
088 * <code>start</code> method with TMRESUME specified.</p>
089 *
090 * <p>If TMFAIL is specified, the portion of work has failed.
091 * The resource manager may mark the transaction as rollback-only</p>
092 *
093 * <p>If TMSUCCESS is specified, the portion of work has completed
094 * successfully.</p>
095 *
096 * @param xid A global transaction identifier that is the same as
097 * the identifier used previously in the <code>start</code> method.
098 *
099 * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND.
100 *
101 * @exception XAException An error has occurred. Possible XAException
102 * values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL,
103 * XAER_PROTO, or XA_RB*.
104 */
105
106 void end(Xid xid, int flags) throws XAException;
107
108 /** Tells the resource manager to forget about a heuristically
109 * completed transaction branch.
110 *
111 * @param xid A global transaction identifier.
112 *
113 * @exception XAException An error has occurred. Possible exception
114 * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or
115 * XAER_PROTO.
116 */
117
118 void forget(Xid xid) throws XAException;
119
120 /** Obtains the current transaction timeout value set for this
121 * XAResource instance. If <CODE>XAResource.setTransactionTimeout</CODE>
122 * was not used prior to invoking this method, the return value
123 * is the default timeout set for the resource manager; otherwise,
124 * the value used in the previous <CODE>setTransactionTimeout</CODE>
125 * call is returned.
126 *
127 * @return the transaction timeout value in seconds.
128 *
129 * @exception XAException An error has occurred. Possible exception
130 * values are XAER_RMERR and XAER_RMFAIL.
131 */
132 int getTransactionTimeout() throws XAException;
133
134 /** This method is called to determine if the resource manager
135 * instance represented by the target object is the same as the
136 * resouce manager instance represented by the parameter <i>xares</i>.
137 *
138 * @param xares An XAResource object whose resource manager instance
139 * is to be compared with the resource manager instance of the
140 * target object.
141 *
142 * @return <i>true</i> if it's the same RM instance; otherwise
143 * <i>false</i>.
144 *
145 * @exception XAException An error has occurred. Possible exception
146 * values are XAER_RMERR and XAER_RMFAIL.
147 *
148 */
149 boolean isSameRM(XAResource xares) throws XAException;
150
151 /** Ask the resource manager to prepare for a transaction commit
152 * of the transaction specified in xid.
153 *
154 * @param xid A global transaction identifier.
155 *
156 * @exception XAException An error has occurred. Possible exception
157 * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
158 * or XAER_PROTO.
159 *
160 * @return A value indicating the resource manager's vote on the
161 * outcome of the transaction. The possible values are: XA_RDONLY
162 * or XA_OK. If the resource manager wants to roll back the
163 * transaction, it should do so by raising an appropriate XAException
164 * in the prepare method.
165 */
166
167 int prepare(Xid xid) throws XAException;
168
169 /** Obtains a list of prepared transaction branches from a resource
170 * manager. The transaction manager calls this method during recovery
171 * to obtain the list of transaction branches that are currently in
172 * prepared or heuristically completed states.
173 *
174 * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
175 * must be used when no other flags are set in the parameter.
176 *
177 * @exception XAException An error has occurred. Possible values are
178 * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
179 *
180 * @return The resource manager returns zero or more XIDs of the
181 * transaction branches that are currently in a prepared or
182 * heuristically completed state. If an error occurs during the
183 * operation, the resource manager should throw the appropriate
184 * XAException.
185 *
186 */
187
188 Xid[] recover(int flag) throws XAException;
189
190 /** Informs the resource manager to roll back work done on behalf
191 * of a transaction branch.
192 *
193 * @param xid A global transaction identifier.
194 *
195 * @exception XAException An error has occurred.
196 */
197
198 void rollback(Xid xid) throws XAException;
199
200 /** <P>Sets the current transaction timeout value for this <CODE>XAResource</CODE>
201 * instance. Once set, this timeout value is effective until
202 * <code>setTransactionTimeout</code> is invoked again with a different
203 * value. To reset the timeout value to the default value used by the resource
204 * manager, set the value to zero.
205 *
206 * If the timeout operation is performed successfully, the method returns
207 * <i>true</i>; otherwise <i>false</i>. If a resource manager does not
208 * support explicitly setting the transaction timeout value, this method
209 * returns <i>false</i>.
210 *
211 * @param seconds The transaction timeout value in seconds.
212 *
213 * @return <i>true</i> if the transaction timeout value is set successfully;
214 * otherwise <i>false</i>.
215 *
216 * @exception XAException An error has occurred. Possible exception values
217 * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
218 */
219 boolean setTransactionTimeout(int seconds) throws XAException;
220
221 /** Starts work on behalf of a transaction branch specified in
222 * <code>xid</code>.
223 *
224 * If TMJOIN is specified, the start applies to joining a transaction
225 * previously seen by the resource manager. If TMRESUME is specified,
226 * the start applies to resuming a suspended transaction specified in the
227 * parameter <code>xid</code>.
228 *
229 * If neither TMJOIN nor TMRESUME is specified and the transaction
230 * specified by <code>xid</code> has previously been seen by the resource
231 * manager, the resource manager throws the XAException exception with
232 * XAER_DUPID error code.
233 *
234 * @param xid A global transaction identifier to be associated
235 * with the resource.
236 *
237 * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME.
238 *
239 * @exception XAException An error has occurred. Possible exceptions
240 * are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE,
241 * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
242 *
243 */
244 void start(Xid xid, int flags) throws XAException;
245
246 /**
247 * Ends a recovery scan.
248 */
249 public final static int TMENDRSCAN = 0x00800000;
250
251 /**
252 * Disassociates the caller and marks the transaction branch
253 * rollback-only.
254 */
255 public final static int TMFAIL = 0x20000000;
256
257 /**
258 * Caller is joining existing transaction branch.
259 */
260 public final static int TMJOIN = 0x00200000;
261
262 /**
263 * Use TMNOFLAGS to indicate no flags value is selected.
264 */
265 public final static int TMNOFLAGS = 0x00000000;
266
267 /**
268 * Caller is using one-phase optimization.
269 */
270 public final static int TMONEPHASE = 0x40000000;
271
272 /**
273 * Caller is resuming association with a suspended
274 * transaction branch.
275 */
276 public final static int TMRESUME = 0x08000000;
277
278 /**
279 * Starts a recovery scan.
280 */
281 public final static int TMSTARTRSCAN = 0x01000000;
282
283 /**
284 * Disassociates caller from a transaction branch.
285 */
286 public final static int TMSUCCESS = 0x04000000;
287
288 /**
289 * Caller is suspending (not ending) its association with
290 * a transaction branch.
291 */
292 public final static int TMSUSPEND = 0x02000000;
293
294 /**
295 * The transaction branch has been read-only and has been committed.
296 */
297 public final static int XA_RDONLY = 0x00000003;
298
299 /**
300 * The transaction work has been prepared normally.
301 */
302 public final static int XA_OK = 0;
303
304 }
|