/*

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

/**

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

    /**

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

}