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 /** <p>The XAResource interface is a Java mapping of the industry standard

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

    30   * Transaction Processing: The XA Specification).

    31   *

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

    33   * and a Transaction Manager in a distributed transaction processing

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

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

    36   * and a database or message service connection.

    37   *

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

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

    40   * environment where transactions are controlled by an external

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

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

    43   * database connections. Each database connection is enlisted with

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

    45   * manager obtains an XAResource for each connection participating

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

    47   * <code>start</code> method

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

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

    50   * the resource. The resource

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

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

    53   *

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

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

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

    57   *

    58   */

    59 

    60 public interface XAResource

    61 {

    62     /** Commits the global transaction specified by xid.

    63       *

    64       * @param xid A global transaction identifier

    65       *

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

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

    68       *

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

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

    71       * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

    72       *

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

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

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

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

    77       */

    78 

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

    80 

    81 

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

    83       * The resource manager disassociates the XA resource from the

    84       * transaction branch specified and lets the transaction

    85       * complete.

    86       *

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

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

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

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

    91       *

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

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

    94       *

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

    96       * successfully.</p>

    97       *

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

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

   100       *

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

   102       *

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

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

   105       * XAER_PROTO, or XA_RB*.

   106       */

   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 

   121     void forget(Xid xid) throws XAException;

   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     /** This method is called to determine if the resource manager

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

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

   140       *

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

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

   143       *      target object.

   144       *

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

   146       *       <i>false</i>.

   147       *

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

   149       * values are XAER_RMERR and XAER_RMFAIL.

   150       *

   151       */

   152     boolean isSameRM(XAResource xares) throws XAException;

   153 

   154     /** Ask the resource manager to prepare for a transaction commit

   155       * of the transaction specified in xid.

   156       *

   157       * @param xid A global transaction identifier.

   158       *

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

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

   161       * or XAER_PROTO.

   162       *

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

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

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

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

   167       * in the prepare method.

   168       */

   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       */

   191 

   192     Xid[] recover(int flag) throws XAException;

   193 

   194 

   195     /** Informs the resource manager to roll back work done on behalf

   196       * of a transaction branch.

   197       *

   198       * @param xid A global transaction identifier.

   199       *

   200       * @exception XAException An error has occurred.

   201       */

   202 

   203     void rollback(Xid xid) throws XAException;

   204 

   205 

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

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

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

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

   210       * manager, set the value to zero.

   211       *

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

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

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

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

   216       *

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

   218       *

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

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

   221       *

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

   223       * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

   224       */

   225     boolean setTransactionTimeout(int seconds) throws XAException;

   226 

   227 

   228     /** Starts work on behalf of a transaction branch specified in

   229       * <code>xid</code>.

   230       *

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

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

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

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

   235       *

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

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

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

   239       * XAER_DUPID error code.

   240       *

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

   242       * with the resource.

   243       *

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

   245       *

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

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

   248       * XAER_NOTA, XAER_INVAL, or XAER_PROTO.

   249       *

   250       */

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

   252 

   253 

   254     /**

   255       * Ends a recovery scan.

   256       */

   257     public final static int TMENDRSCAN =   0x00800000;

   258 

   259     /**

   260       * Disassociates the caller and marks the transaction branch

   261       * rollback-only.

   262       */

   263     public final static int TMFAIL =       0x20000000;

   264 

   265     /**

   266       * Caller is joining existing transaction branch.

   267       */

   268     public final static int TMJOIN =       0x00200000;

   269 

   270     /**

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

   272       */

   273     public final static int TMNOFLAGS =     0x00000000;

   274 

   275     /**

   276       * Caller is using one-phase optimization.

   277       */

   278     public final static int TMONEPHASE =   0x40000000;

   279 

   280     /**

   281       * Caller is resuming association with a suspended

   282       * transaction branch.

   283       */

   284     public final static int TMRESUME =     0x08000000;

   285 

   286     /**

   287       * Starts a recovery scan.

   288       */

   289     public final static int TMSTARTRSCAN = 0x01000000;

   290 

   291 

   292     /**

   293       * Disassociates caller from a transaction branch.

   294       */

   295     public final static int TMSUCCESS =    0x04000000;

   296 

   297 

   298     /**

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

   300       * a transaction branch.

   301       */

   302     public final static int TMSUSPEND =    0x02000000;

   303 

   304     /**

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

   306      */

   307     public final static int XA_RDONLY = 0x00000003;

   308 

   309     /**

   310      * The transaction work has been prepared normally.

   311      */

   312     public final static int XA_OK = 0;

   313 

   314 }