1 /*

     2  * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.transaction.xa;

    27 

    28 /**

    29  * The XAResource interface is a Java mapping of the industry standard

    30  * XA interface based on the X/Open CAE Specification (Distributed

    31  * Transaction Processing: The XA Specification).

    32  *

    33  * <p>The XA interface defines the contract between a Resource Manager

    34  * and a Transaction Manager in a distributed transaction processing

    35  * (DTP) environment. A JDBC driver or a JMS provider implements

    36  * this interface to support the association between a global transaction

    37  * and a database or message service connection.

    38  *

    39  * <p>The XAResource interface can be supported by any transactional

    40  * resource that is intended to be used by application programs in an

    41  * environment where transactions are controlled by an external

    42  * transaction manager. An example of such a resource is a database

    43  * management system. An application may access data through multiple

    44  * database connections. Each database connection is enlisted with

    45  * the transaction manager as a transactional resource. The transaction

    46  * manager obtains an XAResource for each connection participating

    47  * in a global transaction. The transaction manager uses the

    48  * <code>start</code> method

    49  * to associate the global transaction with the resource, and it uses the

    50  * <code>end</code> method to disassociate the transaction from

    51  * the resource. The resource

    52  * manager is responsible for associating the global transaction to all

    53  * work performed on its data between the start and end method invocations.

    54  *

    55  * <p>At transaction commit time, the resource managers are informed by

    56  * the transaction manager to prepare, commit, or rollback a transaction

    57  * according to the two-phase commit protocol.</p>

    58  *

    59  * @since 1.4

    60  */

    61 public interface XAResource {

    62 

    63     /**

    64      * Commits the global transaction specified by xid.

    65      *

    66      * @param xid A global transaction identifier

    67      *

    68      * @param onePhase If true, the resource manager should use a one-phase

    69      * commit protocol to commit the work done on behalf of xid.

    70      *

    71      * @exception XAException An error has occurred. Possible XAExceptions

    72      * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR,

    73      * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

    74      *

    75      * <P>If the resource manager did not commit the transaction and the

    76      *  paramether onePhase is set to true, the resource manager may throw

    77      *  one of the XA_RB* exceptions. Upon return, the resource manager has

    78      *  rolled back the branch's work and has released all held resources.

    79      */

    80     void commit(Xid xid, boolean onePhase) throws XAException;

    81 

    82     /**

    83      * Ends the work performed on behalf of a transaction branch.

    84      * The resource manager disassociates the XA resource from the

    85      * transaction branch specified and lets the transaction

    86      * complete.

    87      *

    88      * <p>If TMSUSPEND is specified in the flags, the transaction branch

    89      * is temporarily suspended in an incomplete state. The transaction

    90      * context is in a suspended state and must be resumed via the

    91      * <code>start</code> method with TMRESUME specified.</p>

    92      *

    93      * <p>If TMFAIL is specified, the portion of work has failed.

    94      * The resource manager may mark the transaction as rollback-only</p>

    95      *

    96      * <p>If TMSUCCESS is specified, the portion of work has completed

    97      * successfully.</p>

    98      *

    99      * @param xid A global transaction identifier that is the same as

   100      * the identifier used previously in the <code>start</code> method.

   101      *

   102      * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND.

   103      *

   104      * @exception XAException An error has occurred. Possible XAException

   105      * values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL,

   106      * XAER_PROTO, or XA_RB*.

   107      */

   108     void end(Xid xid, int flags) throws XAException;

   109 

   110     /**

   111      * Tells the resource manager to forget about a heuristically

   112      * completed transaction branch.

   113      *

   114      * @param xid A global transaction identifier.

   115      *

   116      * @exception XAException An error has occurred. Possible exception

   117      * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or

   118      * XAER_PROTO.

   119      */

   120     void forget(Xid xid) throws XAException;

   121 

   122     /**

   123      * Obtains the current transaction timeout value set for this

   124      * XAResource instance. If <CODE>XAResource.setTransactionTimeout</CODE>

   125      * was not used prior to invoking this method, the return value

   126      * is the default timeout set for the resource manager; otherwise,

   127      * the value used in the previous <CODE>setTransactionTimeout</CODE>

   128      * call is returned.

   129      *

   130      * @return the transaction timeout value in seconds.

   131      *

   132      * @exception XAException An error has occurred. Possible exception

   133      * values are XAER_RMERR and XAER_RMFAIL.

   134      */

   135     int getTransactionTimeout() throws XAException;

   136 

   137     /**

   138      * This method is called to determine if the resource manager

   139      * instance represented by the target object is the same as the

   140      * resouce manager instance represented by the parameter <i>xares</i>.

   141      *

   142      * @param xares An XAResource object whose resource manager instance

   143      *      is to be compared with the resource manager instance of the

   144      *      target object.

   145      *

   146      * @return <i>true</i> if it's the same RM instance; otherwise

   147      *       <i>false</i>.

   148      *

   149      * @exception XAException An error has occurred. Possible exception

   150      * values are XAER_RMERR and XAER_RMFAIL.

   151      */

   152     boolean isSameRM(XAResource xares) throws XAException;

   153 

   154     /**

   155      * Ask the resource manager to prepare for a transaction commit

   156      * of the transaction specified in xid.

   157      *

   158      * @param xid A global transaction identifier.

   159      *

   160      * @exception XAException An error has occurred. Possible exception

   161      * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,

   162      * or XAER_PROTO.

   163      *

   164      * @return A value indicating the resource manager's vote on the

   165      * outcome of the transaction. The possible values are: XA_RDONLY

   166      * or XA_OK. If the resource manager wants to roll back the

   167      * transaction, it should do so by raising an appropriate XAException

   168      * in the prepare method.

   169      */

   170     int prepare(Xid xid) throws XAException;

   171 

   172     /**

   173      * Obtains a list of prepared transaction branches from a resource

   174      * manager. The transaction manager calls this method during recovery

   175      * to obtain the list of transaction branches that are currently in

   176      * prepared or heuristically completed states.

   177      *

   178      * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS

   179      * must be used when no other flags are set in the parameter.

   180      *

   181      * @exception XAException An error has occurred. Possible values are

   182      * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

   183      *

   184      * @return The resource manager returns zero or more XIDs of the

   185      * transaction branches that are currently in a prepared or

   186      * heuristically completed state. If an error occurs during the

   187      * operation, the resource manager should throw the appropriate

   188      * XAException.

   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.

   199      */

   200     void rollback(Xid xid) throws XAException;

   201 

   202     /**

   203      * Sets the current transaction timeout value for this <CODE>XAResource</CODE>

   204      * instance. Once set, this timeout value is effective until

   205      * <code>setTransactionTimeout</code> is invoked again with a different

   206      * value. To reset the timeout value to the default value used by the resource

   207      * manager, set the value to zero.

   208      *

   209      * If the timeout operation is performed successfully, the method returns

   210      * <i>true</i>; otherwise <i>false</i>. If a resource manager does not

   211      * support explicitly setting the transaction timeout value, this method

   212      * returns <i>false</i>.

   213      *

   214      * @param seconds The transaction timeout value in seconds.

   215      *

   216      * @return <i>true</i> if the transaction timeout value is set successfully;

   217      *       otherwise <i>false</i>.

   218      *

   219      * @exception XAException An error has occurred. Possible exception values

   220      * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

   221      */

   222     boolean setTransactionTimeout(int seconds) throws XAException;

   223 

   224     /**

   225      * Starts work on behalf of a transaction branch specified in

   226      * <code>xid</code>.

   227      *

   228      * If TMJOIN is specified, the start applies to joining a transaction

   229      * previously seen by the resource manager. If TMRESUME is specified,

   230      * the start applies to resuming a suspended transaction specified in the

   231      * parameter <code>xid</code>.

   232      *

   233      * If neither TMJOIN nor TMRESUME is specified and the transaction

   234      * specified by <code>xid</code> has previously been seen by the resource

   235      * manager, the resource manager throws the XAException exception with

   236      * XAER_DUPID error code.

   237      *

   238      * @param xid A global transaction identifier to be associated

   239      * with the resource.

   240      *

   241      * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME.

   242      *

   243      * @exception XAException An error has occurred. Possible exceptions

   244      * are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE,

   245      * XAER_NOTA, XAER_INVAL, or XAER_PROTO.

   246      */

   247     void start(Xid xid, int flags) throws XAException;

   248 

   249     /**

   250      * Ends a recovery scan.

   251      */

   252     public final static int TMENDRSCAN =   0x00800000;

   253 

   254     /**

   255      * Disassociates the caller and marks the transaction branch

   256      * rollback-only.

   257      */

   258     public final static int TMFAIL =       0x20000000;

   259 

   260     /**

   261      * Caller is joining existing transaction branch.

   262      */

   263     public final static int TMJOIN =       0x00200000;

   264 

   265     /**

   266      * Use TMNOFLAGS to indicate no flags value is selected.

   267      */

   268     public final static int TMNOFLAGS =     0x00000000;

   269 

   270     /**

   271      * Caller is using one-phase optimization.

   272      */

   273     public final static int TMONEPHASE =   0x40000000;

   274 

   275     /**

   276      * Caller is resuming association with a suspended

   277      * transaction branch.

   278      */

   279     public final static int TMRESUME =     0x08000000;

   280 

   281     /**

   282       * Starts a recovery scan.

   283       */

   284     public final static int TMSTARTRSCAN = 0x01000000;

   285 

   286     /**

   287      * Disassociates caller from a transaction branch.

   288      */

   289     public final static int TMSUCCESS =    0x04000000;

   290 

   291     /**

   292      * Caller is suspending (not ending) its association with

   293      * a transaction branch.

   294      */

   295     public final static int TMSUSPEND =    0x02000000;

   296 

   297     /**

   298      * The transaction branch has been read-only and has been committed.

   299      */

   300     public final static int XA_RDONLY = 0x00000003;

   301 

   302     /**

   303      * The transaction work has been prepared normally.

   304      */

   305     public final static int XA_OK = 0;

   306 }