001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.transaction.xa;
023:
024: /**
025: * The XAResource interface is a Java mapping of the industry standard XA
026: * interface based on the X/Open CAE Specification (Distributed Transaction
027: * Processing: The XA Specification).
028: * <p>
029: * The XA interface defines the contract between a Resource Manager and a
030: * Transaction Manager in a distributed transaction processing (DTP)
031: * environment.
032: * An XA resource such as a JDBC driver or a JMS provider implements this
033: * interface to support association between a global transaction and a
034: * database or message service connection.
035: * <p>
036: * The XAResource interface can be supported by any transactional resource
037: * that is intended to be used by application programs in an environment
038: * where transactions are controlled by an external transaction manager.
039: * An example of such a resource is a database management system.
040: * An application may access data through multiple database connections.
041: * Each database connection is enlisted with the transaction manager as a
042: * transactional resource. The transaction manager obtains an XAResource for
043: * each connection participating in a global transaction. The transaction
044: * manager uses the {@link #start(Xid, int) start} method to associate the
045: * global transaction with the resource, and it uses the
046: * {@link #end(Xid, int) end} method to disassociate the transaction from
047: * the resource.
048: * The resource manager is responsible for associating the global
049: * transaction to all work performed on its data between the start and
050: * end method invocation.
051: * <p>
052: * At transaction commit time, the resource managers are informed by the
053: * transaction manager to prepare, commit, or rollback a transaction
054: * according to the two-phase commit protocol.
055: * <p>
056: * Behind the resources that implement this interface the resource manager
057: * exists. The resource manager does not have a public interface or direct
058: * references, and can manage several resources.
059: * To see if two resources are managed by the same resource manager, the
060: * {@link #isSameRM(XAResource)} method can be used.
061: *
062: * @version $Revision: 57196 $
063: */
064: public interface XAResource {
065: /**
066: * Flag value indicating that no flags are set.
067: */
068: public static final int TMNOFLAGS = 0;
069:
070: /**
071: * JTA specifies this constant and states that it indicates that the
072: * caller is using one-phase optimization, but this constant seems
073: * not to be used by JTA.
074: */
075: public static final int TMONEPHASE = 1073741824;
076:
077: /**
078: * Flag value for the {@link #start(Xid, int) start} method indicating
079: * that the resource should associate with a transaction previously seen
080: * by this resource manager.
081: */
082: public static final int TMJOIN = 2097152;
083:
084: /**
085: * Flag value for the {@link #start(Xid, int) start} method indicating
086: * that the resource should associate with a transaction where the
087: * association was suspended.
088: */
089: public static final int TMRESUME = 134217728;
090:
091: /**
092: * Flag value for the {@link #end(Xid, int) end} method indicating that
093: * the transaction should be disassociated, and that the work has
094: * completed sucessfully.
095: */
096: public static final int TMSUCCESS = 67108864;
097:
098: /**
099: * Flag value for the {@link #end(Xid, int) end} method indicating that
100: * the transaction should be disassociated, and that the work has
101: * failed
102: */
103: public static final int TMFAIL = 536870912;
104:
105: /**
106: * Flag value for the {@link #end(Xid, int) end} method indicating that
107: * the resource should temporarily suspend the association with the
108: * transaction.
109: */
110: public static final int TMSUSPEND = 33554432;
111:
112: /**
113: * Value returned from the {@link #prepare(Xid) prepare} method to
114: * indicate that the resource was not changed in this transaction.
115: */
116: public static final int XA_RDONLY = 3;
117:
118: /**
119: * Value returned from the {@link #prepare(Xid) prepare} method to
120: * indicate that the resource has successfully prepared to commit
121: * the transaction.
122: */
123: public static final int XA_OK = 0;
124:
125: /**
126: * Flag value for the {@link #recover(int) recover} method indicating
127: * that the resource manager should start a new recovery scan.
128: */
129: public static final int TMSTARTRSCAN = 16777216;
130:
131: /**
132: * Flag value for the {@link #recover(int) recover} method indicating
133: * that the resource manager should end the current recovery scan.
134: */
135: public static final int TMENDRSCAN = 8388608;
136:
137: /**
138: * Called to associate the resource with a transaction.
139: *
140: * If the flags argument is {@link #TMNOFLAGS}, the transaction must not
141: * previously have been seen by this resource manager, or an
142: * {@link XAException} with error code XAER_DUPID will be thrown.
143: *
144: * If the flags argument is {@link #TMJOIN}, the resource will join a
145: * transaction previously seen by tis resource manager.
146: *
147: * If the flags argument is {@link #TMRESUME} the resource will
148: * resume the transaction association that was suspended with
149: * end(TMSUSPEND).
150: *
151: * @param xid The id of the transaction to associate with.
152: * @param flags Must be either {@link #TMNOFLAGS}, {@link #TMJOIN}
153: * or {@link #TMRESUME}.
154: * @throws XAException If an error occurred.
155: */
156: public void start(Xid xid, int flags) throws XAException;
157:
158: /**
159: * Called to disassociate the resource from a transaction.
160: *
161: * If the flags argument is {@link #TMSUCCESS}, the portion of work
162: * was done sucessfully.
163: *
164: * If the flags argument is {@link #TMFAIL}, the portion of work
165: * failed. The resource manager may mark the transaction for
166: * rollback only to avoid the transaction being committed.
167: *
168: * If the flags argument is {@link #TMSUSPEND} the resource will
169: * temporarily suspend the transaction association. The transaction
170: * must later be re-associated by giving the {@link #TMRESUME} flag
171: * to the {@link #start(Xid,int) start} method.
172: *
173: * @param xid The id of the transaction to disassociate from.
174: * @param flags Must be either {@link #TMSUCCESS}, {@link #TMFAIL}
175: * or {@link #TMSUSPEND}.
176: * @throws XAException If an error occurred.
177: */
178: public void end(Xid xid, int flags) throws XAException;
179:
180: /**
181: * Prepare to commit the work done on this resource in the given
182: * transaction.
183: *
184: * This method cannot return a status indicating that the transaction
185: * should be rolled back. If the resource wants the transaction to
186: * be rolled back, it should throw an <code>XAException</code> at the
187: * caller.
188: *
189: * @param xid The id of the transaction to prepare to commit work for.
190: * @return Either {@link #XA_OK} or {@link #XA_RDONLY}.
191: * @throws XAException If an error occurred.
192: */
193: public int prepare(Xid xid) throws XAException;
194:
195: /**
196: * Commit the work done on this resource in the given transaction.
197: *
198: * If the <code>onePhase</code> argument is true, one-phase
199: * optimization is being used, and the {@link #prepare(Xid) prepare}
200: * method must not have been called for this transaction.
201: * Otherwise, this is the second phase of the two-phase commit protocol.
202: *
203: * @param xid The id of the transaction to commit work for.
204: * @param onePhase If true, the transaction manager is using one-phase
205: * optimization.
206: * @throws XAException If an error occurred.
207: */
208: public void commit(Xid xid, boolean onePhase) throws XAException;
209:
210: /**
211: * Roll back the work done on this resource in the given transaction.
212: *
213: * @param xid The id of the transaction to commit work for.
214: * @throws XAException If an error occurred.
215: */
216: public void rollback(Xid xid) throws XAException;
217:
218: /**
219: * Tells the resource manager to forget about a heuristic decision.
220: *
221: * @param xid The id of the transaction that was ended with a heuristic
222: * decision.
223: * @throws XAException If an error occurred.
224: */
225: public void forget(Xid xid) throws XAException;
226:
227: /**
228: * Return a list of transactions that are in a prepared or heuristically
229: * state.
230: *
231: * This method looks not only at the resource it is invoked on, but
232: * also on all other resources managed by the same resource manager.
233: * It is intended to be used by the application server when recovering
234: * after a server crash.
235: * <p>
236: * A recovery scan is done with one or more calls to this method.
237: * At the first call, {@link #TMSTARTRSCAN} must be in the
238: * <code>flag</code> argument to indicate that the scan should be started.
239: * During the recovery scan, the resource manager maintains an internal
240: * cursor that keeps track of the progress of the recovery scan.
241: * To end the recovery scan, the {@link #TMENDRSCAN} must be passed
242: * in the <code>flag</code> argument.
243: *
244: * @param flag Must be either {@link #TMNOFLAGS}, {@link #TMSTARTRSCAN},
245: * {@link #TMENDRSCAN} or <code>TMSTARTRSCAN|TMENDRSCAN</code>.
246: * @return An array of zero or more transaction ids.
247: * @throws XAException If an error occurred.
248: */
249: public Xid[] recover(int flag) throws XAException;
250:
251: /**
252: * Tells the caller if this resource has the same resource manager
253: * as the argument resource.
254: *
255: * The transaction manager needs this method to be able to decide
256: * if the {@link #start(Xid,int) start} method should be given the
257: * {@link #TMJOIN} flag.
258: *
259: * @throws XAException If an error occurred.
260: */
261: public boolean isSameRM(XAResource xaRes) throws XAException;
262:
263: /**
264: * Get the current transaction timeout value for this resource.
265: *
266: * @return The current timeout value, in seconds.
267: * @throws XAException If an error occurred.
268: */
269: public int getTransactionTimeout() throws XAException;
270:
271: /**
272: * Set the transaction timeout value for this resource.
273: *
274: * If the <code>seconds</code> argument is <code>0</code>, the
275: * timeout value is set to the default timeout value of the resource
276: * manager.
277: *
278: * Not all resource managers support setting the timeout value.
279: * If the resource manager does not support setting the timeout
280: * value, it should return false.
281: *
282: * @param seconds The timeout value, in seconds.
283: * @return True if the timeout value could be set, otherwise false.
284: * @throws XAException If an error occurred.
285: */
286: public boolean setTransactionTimeout(int seconds)
287: throws XAException;
288: }
|