All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.transaction.xa.XAResource Maven / Gradle / Ivy

Go to download

The javax.transaction package. It is appropriate for inclusion in a classpath, and may be added to a Java 2 installation.

The newest version!
/*
 * The contents of this file are subject to the terms 
 * of the Common Development and Distribution License 
 * (the License).  You may not use this file except in
 * compliance with the License.
 * 
 * You can obtain a copy of the license at 
 * https://glassfish.dev.java.net/public/CDDLv1.0.html or
 * glassfish/bootstrap/legal/CDDLv1.0.txt.
 * See the License for the specific language governing 
 * permissions and limitations under the License.
 * 
 * When distributing Covered Code, include this CDDL 
 * Header Notice in each file and include the License file 
 * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
 * If applicable, add the following below the CDDL Header, 
 * with the fields enclosed by brackets [] replaced by
 * you own identifying information: 
 * "Portions Copyrighted [year] [name of copyright owner]"
 * 
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 */

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). * *

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

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 * start method * to associate the global transaction with the resource, and it uses the * end 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. * *

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.

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

If the resource manager did not commit the transaction and the * parameter 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. * *

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 * start method with TMRESUME specified.

* *

If TMFAIL is specified, the portion of work has failed. * The resource manager may mark the transaction as rollback-only

* *

If TMSUCCESS is specified, the portion of work has completed * successfully.

* * @param xid A global transaction identifier that is the same as * the identifier used previously in the start method. * * @param flags One of TMSUCCESS, TMFAIL, or TMSUSPEND. * * @exception XAException An error has occurred. Possible XAException * values are XAER_RMERR, XAER_RMFAIL, 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 XAResource.setTransactionTimeout * 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 setTransactionTimeout * 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 xares. * * @param xares An XAResource object whose resource manager instance * is to be compared with the resource manager instance of the * target object. * * @return true if it's the same RM instance; otherwise * false. * * @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. Possible XAExceptions are * XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, * XAER_NOTA, XAER_INVAL, or XAER_PROTO. * *

If the transaction branch is already marked rollback-only 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 rollback(Xid xid) throws XAException; /**

Sets the current transaction timeout value for this XAResource * instance. Once set, this timeout value is effective until * setTransactionTimeout 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 * true; otherwise false. If a resource manager does not * support explicitly setting the transaction timeout value, this method * returns false. * * @param seconds The transaction timeout value in seconds. * * @return true if the transaction timeout value is set successfully; * otherwise false. * * @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 * xid. * * 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 xid. * * If neither TMJOIN nor TMRESUME is specified and the transaction * specified by xid 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; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy