001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.transaction.xa;
019:
020: /**
021: * An interface which provides a mapping of the X/Open CAE Specification (for
022: * Distributed Transaction processing) into Java. The XAResource interface is
023: * used as the interface between a Transaction Manager and a Resource Manager
024: * for handling distributed transaction processing.
025: * <p>
026: * Typically, a JDBC driver or a JMS driver will implement the XAResource
027: * interface to support Global Transactions on a database or on a message
028: * connection.
029: */
030: public interface XAResource {
031:
032: /**
033: * Flag to end a recovery scan
034: */
035: public static final int TMENDRSCAN = 0x800000;
036:
037: /**
038: * Flag to indicate that the caller is dissociation from a transaction
039: * branch and that it should be marked rollback only
040: */
041: public static final int TMFAIL = 0x20000000;
042:
043: /**
044: * Flag to indicate that the caller is joining sn existing transaction
045: * branch.
046: */
047: public static final int TMJOIN = 0x200000;
048:
049: /**
050: * Flag that indicates that no flags options are selected. (ie a null flag)
051: */
052: public static final int TMNOFLAGS = 0;
053:
054: /**
055: * Flag that indicates the caller is using one-phase commit optimization
056: */
057: public static final int TMONEPHASE = 0x40000000;
058:
059: /**
060: * Flag that indicates the caller is resuming association with a suspended
061: * transaction branch
062: */
063: public static final int TMRESUME = 0x8000000;
064:
065: /**
066: * Flag that indicates the start of a recovery scan
067: */
068: public static final int TMSTARTRSCAN = 0x1000000;
069:
070: /**
071: * Flag that indicates the caller is dissociating from a transaction branch
072: */
073: public static final int TMSUCCESS = 0x4000000;
074:
075: /**
076: * Flag that indicates that the caller is suspending (not terminating) its
077: * association with a transaction branch.
078: */
079: public static final int TMSUSPEND = 0x2000000;
080:
081: /**
082: * Flag that indicates that transaction work has been read only and has been
083: * committed normally
084: */
085: public static final int XA_RDONLY = 3;
086:
087: /**
088: * Flag that indicates that transaction work has been Prepared normally
089: */
090: public static final int XA_OK = 0;
091:
092: /**
093: * Commits a global transaction.
094: *
095: * @param xid
096: * the XID which identifies the global transaction
097: * @param onePhase
098: * true if the resource manager should use a one-phase commit
099: * protocol to commit the transaction
100: * @throws XAException
101: * if an error occurred.
102: * <p>
103: * Possible errors are identified by the errorcode in the
104: * XAException and include: XA_HEURHAZ, XA_HEURCOM, XA_HEURRB,
105: * XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
106: * or XAER_PROTO. In addition, one of the XA_RB* errors can
107: * occur if the transaction was not committed and
108: * <code>onePhase</code> was set to true. On completion of
109: * this method, the Resource Manager has rolled back the
110: * transaction and released resources held by the transaction.
111: */
112: public void commit(Xid xid, boolean onePhase) throws XAException;
113:
114: /**
115: * Ends the work done for a transaction branch. The Resource Manager
116: * disconnects the XA resource from the transaction branch and allows the
117: * transaction to complete.
118: *
119: * @param xid
120: * the XID which identifies the global transaction. Should have
121: * previously been used as the parameter to a <code>start</code>
122: * method.
123: * @param flags
124: * a flags integer - one of: XAResource.TMSUCCESS,
125: * XAResource.TMFAIL, or XAResource.TMSUSPEND.
126: * <p>
127: * TMSUCCESS means that this section of work completed
128: * successfully.
129: * <p>
130: * TMFAIL means that this section of work failed. The Resource
131: * Manager can mark the transaction for rollback only.
132: * <p>
133: * TMSUSPEND means that this section of work is suspended and not
134: * yet complete. The associated transaction context is also
135: * suspended and must be restarted with a call to
136: * {@link #start(Xid, int)} with the <code>TMRESUME</code>
137: * flag.
138: * @throws XAException
139: * if an error occurs. Possible error identified in the
140: * errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA,
141: * XAER_INVAL, XAER_PROTO, or XA_RB*.
142: */
143: public void end(Xid xid, int flags) throws XAException;
144:
145: /**
146: * Informs the Resource Manager that it can forget about a specified
147: * transaction branch.
148: *
149: * @param xid
150: * the XID which identifies the global transaction.
151: * @throws XAException
152: * if an error occurs. Possible error identified in the
153: * errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA,
154: * XAER_INVAL, or XAER_PROTO.
155: */
156: public void forget(Xid xid) throws XAException;
157:
158: /**
159: * Gets the transaction timeout value for this XAResource. The default
160: * timeout value is the default timeout value set for the Resource Manager.
161: *
162: * @return the transaction timeout value for this XAResource in seconds.
163: * @throws XAException
164: * if an error occurs. Possible error identified in the
165: * errorcode include: XAER_RMERR and XAER_RMFAIL.
166: */
167: public int getTransactionTimeout() throws XAException;
168:
169: /**
170: * Returns true if the ResourceManager for this XAResource is the same as
171: * the Resource Manager for a supplied XAResource.
172: *
173: * @param theXAResource
174: * an XAResource object
175: * @return true if the Resource Manager for this XAResource is the same as
176: * the Resource Manager for <code>theXAResource</code>.
177: * @throws XAException
178: * if an error occurs. Possible error identified in the
179: * errorcode include: XAER_RMERR and XAER_RMFAIL.
180: */
181: public boolean isSameRM(XAResource theXAResource)
182: throws XAException;
183:
184: /**
185: * Requests the Resource manager to prepare to commit a specified
186: * transaction.
187: *
188: * @param xid
189: * the XID which identifies the global transaction.
190: * @return an integer: XA_RDONLY or XA_OK. XA_OK implies that the
191: * transaction work has been prepared normally, XA_RDONLY implies
192: * that the transaction branch is read only and has been committed.
193: * If there is a failure which requires a rollback, an XAException
194: * is raised.
195: * @throws XAException
196: * if an error occurs. Possible error identified in the
197: * errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL,
198: * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
199: */
200: public int prepare(Xid xid) throws XAException;
201:
202: /**
203: * Get a list of prepared transaction branches.
204: * <p>
205: * Typically used by a transaction manager during recovery to find
206: * transaction branches that are in prepared or heuristically completed
207: * states.
208: *
209: * @param flag
210: * an integer. Must be one of: XAResource.TMSTARTRSCAN,
211: * XAResource.TMENDRSCAN, XAResource.TMNOFLAGS.
212: * @return an array of zero or more XIDs identifying the transaction
213: * branches in the prepared or heuristically completed states.
214: * @throws XAException
215: * if an error occurs. Possible error identified in the
216: * errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and
217: * XAER_PROTO.
218: */
219: public Xid[] recover(int flag) throws XAException;
220:
221: /**
222: * Requests the Resource Manager to rollback a specified transaction branch.
223: *
224: * @param xid
225: * the XID which identifies the transaction branch.
226: * @throws XAException
227: * if an error occurs.
228: */
229: public void rollback(Xid xid) throws XAException;
230:
231: /**
232: * Sets the transaction timeout value for this XAResource. If the value is
233: * set to 0, the default timeout value for the Resource Manager is used.
234: *
235: * @param seconds
236: * the new Timeout value in seconds
237: * @return true if the transaction timeout value has been updated, false
238: * otherwise.
239: * @throws XAException
240: * if an error occurs. Possible error identified in the
241: * errorcode include: XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
242: */
243: public boolean setTransactionTimeout(int seconds)
244: throws XAException;
245:
246: /**
247: * Starts work for a specified transaction branch.
248: *
249: * @param xid
250: * the XID which identifies the transaction branch.
251: * @param flags
252: * an integer. Must be one of XAResource.TMNOFLAGS,
253: * XAResource.TMJOIN, or XAResource.TMRESUME.
254: * <p>
255: * TMJOIN implies that the start applies to joining a transaction
256: * previously passed to the Resource Manager.
257: * <p>
258: * TMRESUME implies that the start applies to a suspended
259: * transaction that should be restarted.
260: * <p>
261: * If TMNOFLAGS is specified, then if the transaction has been
262: * previously seen by the Resource Manager, an XAException is
263: * raised with the code XAER_DUPID.
264: * @throws XAException
265: * if an error occurs. Possible error identified in the
266: * errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL,
267: * XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or
268: * XAER_PROTO.
269: */
270: public void start(Xid xid, int flags) throws XAException;
271: }
|