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