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