| /* |
| * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.transaction.xa; |
| |
| /** <p>The XAResource interface is a Java mapping of the industry standard |
| * XA interface based on the X/Open CAE Specification (Distributed |
| * Transaction Processing: The XA Specification). |
| * |
| * <p>The XA interface defines the contract between a Resource Manager |
| * and a Transaction Manager in a distributed transaction processing |
| * (DTP) environment. A JDBC driver or a JMS provider implements |
| * this interface to support the association between a global transaction |
| * and a database or message service connection. |
| * |
| * <p>The XAResource interface can be supported by any transactional |
| * resource that is intended to be used by application programs in an |
| * environment where transactions are controlled by an external |
| * transaction manager. An example of such a resource is a database |
| * management system. An application may access data through multiple |
| * database connections. Each database connection is enlisted with |
| * the transaction manager as a transactional resource. The transaction |
| * manager obtains an XAResource for each connection participating |
| * in a global transaction. The transaction manager uses the |
| * <code>start</code> method |
| * to associate the global transaction with the resource, and it uses the |
| * <code>end</code> method to disassociate the transaction from |
| * the resource. The resource |
| * manager is responsible for associating the global transaction to all |
| * work performed on its data between the start and end method invocations. |
| * |
| * <p>At transaction commit time, the resource managers are informed by |
| * the transaction manager to prepare, commit, or rollback a transaction |
| * according to the two-phase commit protocol.</p> |
| * |
| */ |
| |
| public interface XAResource |
| { |
| /** Commits the global transaction specified by xid. |
| * |
| * @param xid A global transaction identifier |
| * |
| * @param onePhase If true, the resource manager should use a one-phase |
| * commit protocol to commit the work done on behalf of xid. |
| * |
| * @exception XAException An error has occurred. Possible XAExceptions |
| * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, |
| * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO. |
| * |
| * <P>If the resource manager did not commit the transaction and the |
| * paramether onePhase is set to true, the resource manager may throw |
| * one of the XA_RB* exceptions. Upon return, the resource manager has |
| * rolled back the branch's work and has released all held resources. |
| */ |
| |
| void commit(Xid xid, boolean onePhase) throws XAException; |
| |
| |
| /** Ends the work performed on behalf of a transaction branch. |
| * The resource manager disassociates the XA resource from the |
| * transaction branch specified and lets the transaction |
| * complete. |
| * |
| * <p>If TMSUSPEND is specified in the flags, the transaction branch |
| * is temporarily suspended in an incomplete state. The transaction |
| * context is in a suspended state and must be resumed via the |
| * <code>start</code> method with TMRESUME specified.</p> |
| * |
| * <p>If TMFAIL is specified, the portion of work has failed. |
| * The resource manager may mark the transaction as rollback-only</p> |
| * |
| * <p>If TMSUCCESS is specified, the portion of work has completed |
| * successfully.</p> |
| * |
| * @param xid A global transaction identifier that is the same as |
| * the identifier used previously in the <code>start</code> method. |
| * |
| * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND. |
| * |
| * @exception XAException An error has occurred. Possible XAException |
| * values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, |
| * XAER_PROTO, or XA_RB*. |
| */ |
| |
| void end(Xid xid, int flags) throws XAException; |
| |
| |
| /** Tells the resource manager to forget about a heuristically |
| * completed transaction branch. |
| * |
| * @param xid A global transaction identifier. |
| * |
| * @exception XAException An error has occurred. Possible exception |
| * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or |
| * XAER_PROTO. |
| */ |
| |
| void forget(Xid xid) throws XAException; |
| |
| /** Obtains the current transaction timeout value set for this |
| * XAResource instance. If <CODE>XAResource.setTransactionTimeout</CODE> |
| * was not used prior to invoking this method, the return value |
| * is the default timeout set for the resource manager; otherwise, |
| * the value used in the previous <CODE>setTransactionTimeout</CODE> |
| * call is returned. |
| * |
| * @return the transaction timeout value in seconds. |
| * |
| * @exception XAException An error has occurred. Possible exception |
| * values are XAER_RMERR and XAER_RMFAIL. |
| */ |
| int getTransactionTimeout() throws XAException; |
| |
| /** This method is called to determine if the resource manager |
| * instance represented by the target object is the same as the |
| * resouce manager instance represented by the parameter <i>xares</i>. |
| * |
| * @param xares An XAResource object whose resource manager instance |
| * is to be compared with the resource manager instance of the |
| * target object. |
| * |
| * @return <i>true</i> if it's the same RM instance; otherwise |
| * <i>false</i>. |
| * |
| * @exception XAException An error has occurred. Possible exception |
| * values are XAER_RMERR and XAER_RMFAIL. |
| * |
| */ |
| boolean isSameRM(XAResource xares) throws XAException; |
| |
| /** Ask the resource manager to prepare for a transaction commit |
| * of the transaction specified in xid. |
| * |
| * @param xid A global transaction identifier. |
| * |
| * @exception XAException An error has occurred. Possible exception |
| * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, |
| * or XAER_PROTO. |
| * |
| * @return A value indicating the resource manager's vote on the |
| * outcome of the transaction. The possible values are: XA_RDONLY |
| * or XA_OK. If the resource manager wants to roll back the |
| * transaction, it should do so by raising an appropriate XAException |
| * in the prepare method. |
| */ |
| |
| int prepare(Xid xid) throws XAException; |
| |
| |
| /** Obtains a list of prepared transaction branches from a resource |
| * manager. The transaction manager calls this method during recovery |
| * to obtain the list of transaction branches that are currently in |
| * prepared or heuristically completed states. |
| * |
| * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS |
| * must be used when no other flags are set in the parameter. |
| * |
| * @exception XAException An error has occurred. Possible values are |
| * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO. |
| * |
| * @return The resource manager returns zero or more XIDs of the |
| * transaction branches that are currently in a prepared or |
| * heuristically completed state. If an error occurs during the |
| * operation, the resource manager should throw the appropriate |
| * XAException. |
| * |
| */ |
| |
| Xid[] recover(int flag) throws XAException; |
| |
| |
| /** Informs the resource manager to roll back work done on behalf |
| * of a transaction branch. |
| * |
| * @param xid A global transaction identifier. |
| * |
| * @exception XAException An error has occurred. |
| */ |
| |
| void rollback(Xid xid) throws XAException; |
| |
| |
| /** <P>Sets the current transaction timeout value for this <CODE>XAResource</CODE> |
| * instance. Once set, this timeout value is effective until |
| * <code>setTransactionTimeout</code> is invoked again with a different |
| * value. To reset the timeout value to the default value used by the resource |
| * manager, set the value to zero. |
| * |
| * If the timeout operation is performed successfully, the method returns |
| * <i>true</i>; otherwise <i>false</i>. If a resource manager does not |
| * support explicitly setting the transaction timeout value, this method |
| * returns <i>false</i>. |
| * |
| * @param seconds The transaction timeout value in seconds. |
| * |
| * @return <i>true</i> if the transaction timeout value is set successfully; |
| * otherwise <i>false</i>. |
| * |
| * @exception XAException An error has occurred. Possible exception values |
| * are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL. |
| */ |
| boolean setTransactionTimeout(int seconds) throws XAException; |
| |
| |
| /** Starts work on behalf of a transaction branch specified in |
| * <code>xid</code>. |
| * |
| * If TMJOIN is specified, the start applies to joining a transaction |
| * previously seen by the resource manager. If TMRESUME is specified, |
| * the start applies to resuming a suspended transaction specified in the |
| * parameter <code>xid</code>. |
| * |
| * If neither TMJOIN nor TMRESUME is specified and the transaction |
| * specified by <code>xid</code> has previously been seen by the resource |
| * manager, the resource manager throws the XAException exception with |
| * XAER_DUPID error code. |
| * |
| * @param xid A global transaction identifier to be associated |
| * with the resource. |
| * |
| * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME. |
| * |
| * @exception XAException An error has occurred. Possible exceptions |
| * are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, |
| * XAER_NOTA, XAER_INVAL, or XAER_PROTO. |
| * |
| */ |
| void start(Xid xid, int flags) throws XAException; |
| |
| |
| /** |
| * Ends a recovery scan. |
| */ |
| public final static int TMENDRSCAN = 0x00800000; |
| |
| /** |
| * Disassociates the caller and marks the transaction branch |
| * rollback-only. |
| */ |
| public final static int TMFAIL = 0x20000000; |
| |
| /** |
| * Caller is joining existing transaction branch. |
| */ |
| public final static int TMJOIN = 0x00200000; |
| |
| /** |
| * Use TMNOFLAGS to indicate no flags value is selected. |
| */ |
| public final static int TMNOFLAGS = 0x00000000; |
| |
| /** |
| * Caller is using one-phase optimization. |
| */ |
| public final static int TMONEPHASE = 0x40000000; |
| |
| /** |
| * Caller is resuming association with a suspended |
| * transaction branch. |
| */ |
| public final static int TMRESUME = 0x08000000; |
| |
| /** |
| * Starts a recovery scan. |
| */ |
| public final static int TMSTARTRSCAN = 0x01000000; |
| |
| |
| /** |
| * Disassociates caller from a transaction branch. |
| */ |
| public final static int TMSUCCESS = 0x04000000; |
| |
| |
| /** |
| * Caller is suspending (not ending) its association with |
| * a transaction branch. |
| */ |
| public final static int TMSUSPEND = 0x02000000; |
| |
| /** |
| * The transaction branch has been read-only and has been committed. |
| */ |
| public final static int XA_RDONLY = 0x00000003; |
| |
| /** |
| * The transaction work has been prepared normally. |
| */ |
| public final static int XA_OK = 0; |
| |
| } |
