XAResource


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.transaction.xa;
25  
26  /** <p>The XAResource interface is a Java mapping of the industry standard
27    * XA interface based on the X/Open CAE Specification (Distributed
28    * Transaction Processing: The XA Specification).
29    *
30    * <p>The XA interface defines the contract between a Resource Manager
31    * and a Transaction Manager in a distributed transaction processing
32    * (DTP) environment. A JDBC driver or a JMS provider implements
33    * this interface to support the association between a global transaction
34    * and a database or message service connection.
35    *
36    * <p>The XAResource interface can be supported by any transactional
37    * resource that is intended to be used by application programs in an
38    * environment where transactions are controlled by an external
39    * transaction manager. An example of such a resource is a database
40    * management system. An application may access data through multiple
41    * database connections. Each database connection is enlisted with
42    * the transaction manager as a transactional resource. The transaction
43    * manager obtains an XAResource for each connection participating
44    * in a global transaction. The transaction manager uses the
45    * <code>start</code> method
46    * to associate the global transaction with the resource, and it uses the
47    * <code>end</code> method to disassociate the transaction from
48    * the resource. The resource
49    * manager is responsible for associating the global transaction to all
50    * work performed on its data between the start and end method invocations.
51    *
52    * <p>At transaction commit time, the resource managers are informed by
53    * the transaction manager to prepare, commit, or rollback a transaction
54    * according to the two-phase commit protocol.</p>
55    *
56    */
57  
58  public interface XAResource
59  {
60      /** Commits the global transaction specified by xid.
61        *
62        * @param xid A global transaction identifier
63        *
64        * @param onePhase If true, the resource manager should use a one-phase
65        * commit protocol to commit the work done on behalf of xid.
66        *
67        * @exception XAException An error has occurred. Possible XAExceptions
68        * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR,
69        * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
70        *
71        * <P>If the resource manager did not commit the transaction and the
72        *  parameter onePhase is set to true, the resource manager may throw
73        *  one of the XA_RB* exceptions. Upon return, the resource manager has
74        *  rolled back the branch's work and has released all held resources.
75        */
76  
77      void commit(Xid   xid, boolean onePhase) throws XAException  ;
78  
79  
80      /** Ends the work performed on behalf of a transaction branch.
81        * The resource manager disassociates the XA resource from the
82        * transaction branch specified and lets the transaction
83        * complete.
84        *
85        * <p>If TMSUSPEND is specified in the flags, the transaction branch
86        * is temporarily suspended in an incomplete state. The transaction
87        * context is in a suspended state and must be resumed via the
88        * <code>start</code> method with TMRESUME specified.</p>
89        *
90        * <p>If TMFAIL is specified, the portion of work has failed.
91        * The resource manager may mark the transaction as rollback-only</p>
92        *
93        * <p>If TMSUCCESS is specified, the portion of work has completed
94        * successfully.</p>
95        *
96        * @param xid A global transaction identifier that is the same as
97        * the identifier used previously in the <code>start</code> method.
98        *
99        * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND.
100       *
101       * @exception XAException An error has occurred. Possible XAException
102       * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
103       * XAER_PROTO, or XA_RB*.
104       */
105 
106     void end(Xid   xid, int flags) throws XAException  ;
107 
108 
109     /** Tells the resource manager to forget about a heuristically
110       * completed transaction branch.
111       *
112       * @param xid A global transaction identifier.
113       *
114       * @exception XAException An error has occurred. Possible exception
115       * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or
116       * XAER_PROTO.
117       */
118 
119     void forget(Xid   xid) throws XAException  ;
120 
121     /** Obtains the current transaction timeout value set for this
122       * XAResource instance. If <CODE>XAResource.setTransactionTimeout</CODE>
123       * was not used prior to invoking this method, the return value
124       * is the default timeout set for the resource manager; otherwise,
125       * the value used in the previous <CODE>setTransactionTimeout</CODE>
126       * call is returned.
127       *
128       * @return the transaction timeout value in seconds.
129       *
130       * @exception XAException An error has occurred. Possible exception
131       * values are XAER_RMERR and XAER_RMFAIL.
132       */
133     int getTransactionTimeout() throws XAException  ;
134 
135     /** This method is called to determine if the resource manager
136       * instance represented by the target object is the same as the
137       * resouce manager instance represented by the parameter <i>xares</i>.
138       *
139       * @param xares An XAResource object whose resource manager instance
140       *      is to be compared with the resource manager instance of the
141       *      target object.
142       *
143       * @return <i>true</i> if it's the same RM instance; otherwise
144       *       <i>false</i>.
145       *
146       * @exception XAException An error has occurred. Possible exception
147       * values are XAER_RMERR and XAER_RMFAIL.
148       *
149       */
150     boolean isSameRM(XAResource   xares) throws XAException  ;
151 
152     /** Ask the resource manager to prepare for a transaction commit
153       * of the transaction specified in xid.
154       *
155       * @param xid A global transaction identifier.
156       *
157       * @exception XAException An error has occurred. Possible exception
158       * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
159       * or XAER_PROTO.
160       *
161       * @return A value indicating the resource manager's vote on the
162       * outcome of the transaction. The possible values are: XA_RDONLY
163       * or XA_OK. If the resource manager wants to roll back the
164       * transaction, it should do so by raising an appropriate XAException
165       * in the prepare method.
166       */
167 
168     int prepare(Xid   xid) throws XAException  ;
169 
170 
171     /** Obtains a list of prepared transaction branches from a resource
172       * manager. The transaction manager calls this method during recovery
173       * to obtain the list of transaction branches that are currently in
174       * prepared or heuristically completed states.
175       *
176       * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
177       * must be used when no other flags are set in the parameter.
178       *
179       * @exception XAException An error has occurred. Possible values are
180       * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
181       *
182       * @return The resource manager returns zero or more XIDs of the
183       * transaction branches that are currently in a prepared or
184       * heuristically completed state. If an error occurs during the
185       * operation, the resource manager should throw the appropriate
186       * XAException.
187       *
188       */
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. Possible XAExceptions are
199       * XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL,
200       * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
201       *
202       * <p>If the transaction branch is already marked rollback-only the
203       * resource manager may throw one of the XA_RB* exceptions. Upon return,
204       * the resource manager has rolled back the branch's work and has released
205       * all held resources.
206       */
207 
208     void rollback(Xid   xid) throws XAException  ;
209 
210 
211     /** <P>Sets the current transaction timeout value for this <CODE>XAResource</CODE>
212       * instance. Once set, this timeout value is effective until
213       * <code>setTransactionTimeout</code> is invoked again with a different
214       * value. To reset the timeout value to the default value used by the resource
215       * manager, set the value to zero.
216       *
217       * If the timeout operation is performed successfully, the method returns
218       * <i>true</i>; otherwise <i>false</i>. If a resource manager does not
219       * support explicitly setting the transaction timeout value, this method
220       * returns <i>false</i>.
221       *
222       * @param seconds The transaction timeout value in seconds.
223       *
224       * @return <i>true</i> if the transaction timeout value is set successfully;
225       *       otherwise <i>false</i>.
226       *
227       * @exception XAException An error has occurred. Possible exception values
228       * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
229       */
230     boolean setTransactionTimeout(int seconds) throws XAException  ;
231 
232 
233     /** Starts work on behalf of a transaction branch specified in
234       * <code>xid</code>.
235       *
236       * If TMJOIN is specified, the start applies to joining a transaction
237       * previously seen by the resource manager. If TMRESUME is specified,
238       * the start applies to resuming a suspended transaction specified in the
239       * parameter <code>xid</code>.
240       *
241       * If neither TMJOIN nor TMRESUME is specified and the transaction
242       * specified by <code>xid</code> has previously been seen by the resource
243       * manager, the resource manager throws the XAException exception with
244       * XAER_DUPID error code.
245       *
246       * @param xid A global transaction identifier to be associated
247       * with the resource.
248       *
249       * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME.
250       *
251       * @exception XAException An error has occurred. Possible exceptions
252       * are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE,
253       * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
254       *
255       */
256     void start(Xid   xid, int flags) throws XAException  ;
257 
258 
259     /**
260       * Ends a recovery scan.
261       */
262     public final static int TMENDRSCAN =   0x00800000;
263 
264     /**
265       * Disassociates the caller and marks the transaction branch
266       * rollback-only.
267       */
268     public final static int TMFAIL =       0x20000000;
269 
270     /**
271       * Caller is joining existing transaction branch.
272       */
273     public final static int TMJOIN =       0x00200000;
274 
275     /**
276       * Use TMNOFLAGS to indicate no flags value is selected.
277       */
278     public final static int TMNOFLAGS =     0x00000000;
279 
280     /**
281       * Caller is using one-phase optimization.
282       */
283     public final static int TMONEPHASE =   0x40000000;
284 
285     /**
286       * Caller is resuming association with a suspended
287       * transaction branch.
288       */
289     public final static int TMRESUME =     0x08000000;
290 
291     /**
292       * Starts a recovery scan.
293       */
294     public final static int TMSTARTRSCAN = 0x01000000;
295 
296 
297     /**
298       * Disassociates caller from a transaction branch.
299       */
300     public final static int TMSUCCESS =    0x04000000;
301 
302 
303     /**
304       * Caller is suspending (not ending) its association with
305       * a transaction branch.
306       */
307     public final static int TMSUSPEND =    0x02000000;
308 
309     /**
310      * The transaction branch has been read-only and has been committed.
311      */
312     public final static int XA_RDONLY = 0x00000003;
313 
314     /**
315      * The transaction work has been prepared normally.
316      */
317     public final static int XA_OK = 0;
318 
319 }
320
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags