User: sparre
Date: 01/09/19 16:29:04
Modified: src/main/javax/transaction/xa XAException.java
XAResource.java Xid.java
Added: src/main/javax/transaction/xa package.html
Log:
Some XA javadocs
Revision Changes Path
1.6 +149 -17 jboss-j2ee/src/main/javax/transaction/xa/XAException.java
Index: XAException.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/xa/XAException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- XAException.java 2001/05/19 08:23:10 1.5
+++ XAException.java 2001/09/19 23:29:03 1.6
@@ -6,68 +6,200 @@
*/
package javax.transaction.xa;
-/** The XAException is thown by the Resource Manager (RM) to inform the
-Transaction Manager of error encountered for the transaction involved.
-
-@version $Revision: 1.5 $
-*/
+/**
+ * The XAException is thrown by resource managers in case of problems.
+ *
+ * @version $Revision: 1.6 $
+ */
public class XAException extends java.lang.Exception {
+ /**
+ * The error code.
+ */
public int errorCode = 0;
- /** Creates new <code>XAException</code> without detail message.
- */
+ /**
+ * Creates new <code>XAException</code> without detail message.
+ */
public XAException() {
}
- /** Constructs an <code>XAException</code> with the specified detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>XAException</code> with the specified detail
+ * message.
+ *
+ * @param msg the detail message.
+ */
public XAException(String msg) {
super(msg);
}
- /** Constructs an <code>XAException</code> for the specified error code.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>XAException</code> for the specified error code.
+ *
+ * @param errorCode the error code.
+ */
public XAException(int errorCode) {
super();
this.errorCode = errorCode;
}
// STATIC VARIABLES ---------------------------------
+
+ // changed numbers to match SUNs by pkendall for interoperability
- /** changed numbers to match SUNs by pkendall for interoperability */
+ // added by kimptoc - needed for jbossmq to compile...
+ // others added by jwalters for completeness
- /** added by kimptoc - needed for jbossmq to compile... */
- /** others added by jwalters for completeness */
+ /**
+ * Error code indicating that an asynchronous operation is outstanding.
+ */
public static final int XAER_ASYNC = -2;
+
+ /**
+ * Error code indicating that a resource manager error has occurred.
+ */
public static final int XAER_RMERR = -3;
+
+ /**
+ * Error code indicating that an {@link Xid} is not valid.
+ */
public static final int XAER_NOTA = -4;
+
+ /**
+ * Error code indicating that invalid arguments were passed.
+ */
public static final int XAER_INVAL = -5;
+
+ /**
+ * Error code indicating a protocol error. This happens if a method
+ * is invoked on a resource when it is not in the correct state for it.
+ */
public static final int XAER_PROTO = -6;
+
+ /**
+ * Error code indicating that the resource manager has failed and is
+ * not available.
+ */
public static final int XAER_RMFAIL = -7;
+
+ /**
+ * Error code indicating that a Xid given as an argument is already
+ * known to the resource manager.
+ */
public static final int XAER_DUPID = -8;
+
+ /**
+ * Error code indicating that the resource manager is doing work
+ * outside the global transaction.
+ */
public static final int XAER_OUTSIDE = -9;
+
+ // added by jwalters - needed for jboss
- /** added by jwalters - needed for jboss */
+ /**
+ * Error code indicating that the transaction branch was read-only,
+ * and has already been committed.
+ */
public static final int XA_RDONLY = 3;
+
+ /**
+ * Error code indicating that the method invoked returned without having
+ * any effect, and that it may be invoked again.
+ * Note that this constant is not defined in JTA 1.0.1, but appears in
+ * J2EE(TM) as shipped by SUN.
+ */
public static final int XA_RETRY = 4;
+
+ /**
+ * Error code indicating that a heuristic mixed decision was made.
+ * This indicates that parts of the transaction were committed,
+ * while other parts were rolled back.
+ */
public static final int XA_HEURMIX = 5;
+
+ /**
+ * Error code indicating that a heuristic rollback decision was made.
+ */
public static final int XA_HEURRB = 6;
+
+ /**
+ * Error code indicating that a heuristic commit decision was made.
+ */
public static final int XA_HEURCOM = 7;
+
+ /**
+ * Error code indicating that a heuristic decision may have been made.
+ * The outcome of all parts of the transaction is not known, but the
+ * outcome of the known parts are either all committed, or all rolled
+ * back.
+ */
public static final int XA_HEURHAZ = 8;
+
+ /**
+ * Error code indicating that the transaction resumption must happen
+ * where the suspension occurred.
+ */
public static final int XA_NOMIGRATE = 9;
+ /**
+ * This is not an error code, but the same as the rollback error code
+ * with the lowest number.
+ */
public static final int XA_RBBASE = 100;
+
+ /**
+ * Rollback error code indicating that the rollback happened for
+ * an unspecified reason.
+ */
public static final int XA_RBROLLBACK = 100;
+
+ /**
+ * Rollback error code indicating that the rollback happened due to a
+ * communications failure.
+ */
public static final int XA_RBCOMMFAIL = 101;
+
+ /**
+ * Rollback error code indicating that the rollback happened because
+ * deadlock was detected.
+ */
public static final int XA_RBDEADLOCK = 102;
+
+ /**
+ * Rollback error code indicating that the rollback happened because
+ * an internal integrity check failed.
+ */
public static final int XA_RBINTEGRITY = 103;
+
+ /**
+ * Rollback error code indicating that the rollback happened for some
+ * reason not fitting any of the other rollback error codes.
+ */
public static final int XA_RBOTHER = 104;
+
+ /**
+ * Rollback error code indicating that the rollback happened due to
+ * a protocol error in the resource manager.
+ */
public static final int XA_RBPROTO = 105;
+
+ /**
+ * Rollback error code indicating that the rollback happened because
+ * of a timeout.
+ */
public static final int XA_RBTIMEOUT = 106;
+
+ /**
+ * Rollback error code indicating that the rollback happened due to a
+ * transient failure. The transaction branch may be retried.
+ */
public static final int XA_RBTRANSIENT = 107;
+
+ /**
+ * This is not an error code, but the same as the rollback error code
+ * with the highest number.
+ */
public static final int XA_RBEND = 107;
}
1.2 +251 -39 jboss-j2ee/src/main/javax/transaction/xa/XAResource.java
Index: XAResource.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/xa/XAResource.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XAResource.java 2001/03/31 01:12:30 1.1
+++ XAResource.java 2001/09/19 23:29:03 1.2
@@ -6,57 +6,269 @@
*/
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 the this interface to support
-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 invocation.
-
-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.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * 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.
+ * An XA resource such as a JDBC driver or a JMS provider implements this
+ * interface to support 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 {@link #start(Xid, int) start} method to associate the
+ * global transaction with the resource, and it uses the
+ * {@link #end(Xid, int) 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 invocation.
+ * <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>
+ * Behind the resources that implement this interface the resource manager
+ * exists. The resource manager does not have a public interface or direct
+ * references, and can manage several resources.
+ * To see if two resources are managed by the same resource manager, the
+ * {@link #isSameRM(XAResource)} method can be used.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface XAResource
{
- public static final int TMENDRSCAN = 8388608;
- public static final int TMFAIL = 536870912;
- public static final int TMJOIN = 2097152;
+ /**
+ * Flag value indicating that no flags are set.
+ */
public static final int TMNOFLAGS = 0;
+
+ /**
+ * JTA specifies this constant and states that it indicates that the
+ * caller is using one-phase optimization, but this constant seems
+ * not to be used by JTA.
+ */
public static final int TMONEPHASE = 1073741824;
+
+ /**
+ * Flag value for the {@link #start(Xid, int) start} method indicating
+ * that the resource should associate with a transaction previously seen
+ * by this resource manager.
+ */
+ public static final int TMJOIN = 2097152;
+
+ /**
+ * Flag value for the {@link #start(Xid, int) start} method indicating
+ * that the resource should associate with a transaction where the
+ * association was suspended.
+ */
public static final int TMRESUME = 134217728;
- public static final int TMSTARTRSCAN = 16777216;
+
+ /**
+ * Flag value for the {@link #end(Xid, int) end} method indicating that
+ * the transaction should be disassociated, and that the work has
+ * completed sucessfully.
+ */
public static final int TMSUCCESS = 67108864;
+
+ /**
+ * Flag value for the {@link #end(Xid, int) end} method indicating that
+ * the transaction should be disassociated, and that the work has
+ * failed
+ */
+ public static final int TMFAIL = 536870912;
+
+ /**
+ * Flag value for the {@link #end(Xid, int) end} method indicating that
+ * the resource should temporarily suspend the association with the
+ * transaction.
+ */
public static final int TMSUSPEND = 33554432;
+
+ /**
+ * Value returned from the {@link #prepare(Xid) prepare} method to
+ * indicate that the resource was not changed in this transaction.
+ */
public static final int XA_RDONLY = 3;
+
+ /**
+ * Value returned from the {@link #prepare(Xid) prepare} method to
+ * indicate that the resource has successfully prepared to commit
+ * the transaction.
+ */
public static final int XA_OK = 0;
- public void commit(Xid xid, boolean onePhase) throws XAException;
+ /**
+ * Flag value for the {@link #recover(int) recover} method indicating
+ * that the resource manager should start a new recovery scan.
+ */
+ public static final int TMSTARTRSCAN = 16777216;
+
+ /**
+ * Flag value for the {@link #recover(int) recover} method indicating
+ * that the resource manager should end the current recovery scan.
+ */
+ public static final int TMENDRSCAN = 8388608;
+
+
+ /**
+ * Called to associate the resource with a transaction.
+ *
+ * If the flags argument is {@link #TMNOFLAGS}, the transaction must not
+ * previously have been seen by this resource manager, or an
+ * {@link XAException} with error code XAER_DUPID will be thrown.
+ *
+ * If the flags argument is {@link #TMJOIN}, the resource will join a
+ * transaction previously seen by tis resource manager.
+ *
+ * If the flags argument is {@link #TMRESUME} the resource will
+ * resume the transaction association that was suspended with
+ * end(TMSUSPEND).
+ *
+ * @param xid The id of the transaction to associate with.
+ * @param flags Must be either {@link #TMNOFLAGS}, {@link #TMJOIN}
+ * or {@link #TMRESUME}.
+ * @throws XAException If an error occurred.
+ */
+ public void start(Xid xid, int flags) throws XAException;
+
+ /**
+ * Called to disassociate the resource from a transaction.
+ *
+ * If the flags argument is {@link #TMSUCCESS}, the portion of work
+ * was done sucessfully.
+ *
+ * If the flags argument is {@link #TMFAIL}, the portion of work
+ * failed. The resource manager may mark the transaction for
+ * rollback only to avoid the transaction being committed.
+ *
+ * If the flags argument is {@link #TMSUSPEND} the resource will
+ * temporarily suspend the transaction association. The transaction
+ * must later be re-associated by giving the {@link #TMRESUME} flag
+ * to the {@link #start(Xid,int) start} method.
+ *
+ * @param xid The id of the transaction to disassociate from.
+ * @param flags Must be either {@link #TMSUCCESS}, {@link #TMFAIL}
+ * or {@link #TMSUSPEND}.
+ * @throws XAException If an error occurred.
+ */
public void end(Xid xid, int flags) throws XAException;
- public void forget(Xid xid) throws XAException;
- public int getTransactionTimeout() throws XAException;
- public boolean isSameRM(XAResource xaRes) throws XAException;
+
+ /**
+ * Prepare to commit the work done on this resource in the given
+ * transaction.
+ *
+ * This method cannot return a status indicating that the transaction
+ * should be rolled back. If the resource wants the transaction to
+ * be rolled back, it should throw an <code>XAException</code> at the
+ * caller.
+ *
+ * @param xid The id of the transaction to prepare to commit work for.
+ * @return Either {@link #XA_OK} or {@link #XA_RDONLY}.
+ * @throws XAException If an error occurred.
+ */
public int prepare(Xid xid) throws XAException;
- public Xid[] recover(int flag) throws XAException;
+
+ /**
+ * Commit the work done on this resource in the given transaction.
+ *
+ * If the <code>onePhase</code> argument is true, one-phase
+ * optimization is being used, and the {@link #prepare(Xid) prepare}
+ * method must not have been called for this transaction.
+ * Otherwise, this is the second phase of the two-phase commit protocol.
+ *
+ * @param xid The id of the transaction to commit work for.
+ * @param onePhase If true, the transaction manager is using one-phase
+ * optimization.
+ * @throws XAException If an error occurred.
+ */
+ public void commit(Xid xid, boolean onePhase) throws XAException;
+
+ /**
+ * Roll back the work done on this resource in the given transaction.
+ *
+ * @param xid The id of the transaction to commit work for.
+ * @throws XAException If an error occurred.
+ */
public void rollback(Xid xid) throws XAException;
+
+ /**
+ * Tells the resource manager to forget about a heuristic decision.
+ *
+ * @param xid The id of the transaction that was ended with a heuristic
+ * decision.
+ * @throws XAException If an error occurred.
+ */
+ public void forget(Xid xid) throws XAException;
+
+ /**
+ * Return a list of transactions that are in a prepared or heuristically
+ * state.
+ *
+ * This method looks not only at the resource it is invoked on, but
+ * also on all other resources managed by the same resource manager.
+ * It is intended to be used by the application server when recovering
+ * after a server crash.
+ * <p>
+ * A recovery scan is done with one or more calls to this method.
+ * At the first call, {@link #TMSTARTRSCAN} must be in the
+ * <code>flag</code> argument to indicate that the scan should be started.
+ * During the recovery scan, the resource manager maintains an internal
+ * cursor that keeps track of the progress of the recovery scan.
+ * To end the recovery scan, the {@link #TMENDRSCAN} must be passed
+ * in the <code>flag</code> argument.
+ *
+ * @param flag Must be either {@link #TMNOFLAGS}, {@link #TMSTARTRSCAN},
+ * {@link #TMENDRSCAN} or <code>TMSTARTRSCAN|TMENDRSCAN</code>.
+ * @return An array of zero or more transaction ids.
+ * @throws XAException If an error occurred.
+ */
+ public Xid[] recover(int flag) throws XAException;
+
+ /**
+ * Tells the caller if this resource has the same resource manager
+ * as the argument resource.
+ *
+ * The transaction manager needs this method to be able to decide
+ * if the {@link #start(Xid,int) start} method should be given the
+ * {@link #TMJOIN} flag.
+ *
+ * @throws XAException If an error occurred.
+ */
+ public boolean isSameRM(XAResource xaRes) throws XAException;
+
+ /**
+ * Get the current transaction timeout value for this resource.
+ *
+ * @return The current timeout value, in seconds.
+ * @throws XAException If an error occurred.
+ */
+ public int getTransactionTimeout() throws XAException;
+
+ /**
+ * Set the transaction timeout value for this resource.
+ *
+ * If the <code>seconds</code> argument is <code>0</code>, the
+ * timeout value is set to the default timeout value of the resource
+ * manager.
+ *
+ * Not all resource managers support setting the timeout value.
+ * If the resource manager does not support setting the timeout
+ * value, it should return false.
+ *
+ * @param seconds The timeout value, in seconds.
+ * @return True if the timeout value could be set, otherwise false.
+ * @throws XAException If an error occurred.
+ */
public boolean setTransactionTimeout(int seconds) throws XAException;
- public void start(Xid xid, int flags) throws XAException;
}
1.2 +61 -10 jboss-j2ee/src/main/javax/transaction/xa/Xid.java
Index: Xid.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/xa/Xid.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Xid.java 2001/03/31 01:12:30 1.1
+++ Xid.java 2001/09/19 23:29:03 1.2
@@ -6,22 +6,73 @@
*/
package javax.transaction.xa;
-/** The Xid interface is a Java mapping of the X/Open transaction identifier
-XID structure. This interface specifies three accessor methods to retrieve a
-global transaction?s format ID, global transaction ID, and branch qualifier.
-The Xid interface is used by the transaction manager and the resource managers.
-This interface is not visible to the application programs.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The Xid interface is a Java mapping of the X/Open transaction identifier
+ * XID structure.
+ * <p>
+ * A transaction id is an aggregate of three parts:
+ * <ul>
+ * <li> The format identifier indicates the transaction family and tells
+ * how the other two parts should be interpreted.
+ * </li>
+ * <li> The global transaction id denotes, with the format specifier, the
+ * id of the global transaction.
+ * </li>
+ * <li> The branch qualifier denotes a particular branch of the global
+ * transaction.
+ * </li>
+ * </ul>
+ * <p>
+ * The Xid interface is used by the application server, the transaction manager
+ * and the resource managers, and is not used in application programs.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface Xid
{
+ /**
+ * The maximum possible size of a global transaction id.
+ * This is the largest possible array returned by the
+ * {@link #getGlobalTransactionId() getGlobalTransactionId} method.
+ */
public static final int MAXGTRIDSIZE = 64;
+
+ /**
+ * The maximum possible size of a transaction branch qualifier.
+ * This is the largest possible array returned by the
+ * {@link #getBranchQualifier() getBranchQualifier} method.
+ */
public static final int MAXBQUALSIZE = 64;
+ /**
+ * Get the format identifier.
+ *
+ * @return An integer denoting the family of this transaction, and
+ * telling how the two other parts can be interpreted.
+ */
public int getFormatId();
+
+ /**
+ * Get the global transaction id of this transaction.
+ *
+ * Please note that JTA does not define if this method returns
+ * a copy or a reference to an internal byte array. For maximum
+ * portability, do not modify the returned array.
+ *
+ * @return A byte array that together with the format ID
+ * defines the globally unique ID of this transaction.
+ */
public byte[] getGlobalTransactionId();
+
+ /**
+ * Get the transaction branch qualifier of this transaction.
+ *
+ * Please note that JTA does not define if this method returns
+ * a copy or a reference to an internal byte array. For maximum
+ * portability, do not modify the returned array.
+ *
+ * @return A byte array that identifies the branch of this
+ * transaction.
+ */
public byte[] getBranchQualifier();
}
-
-
1.1 jboss-j2ee/src/main/javax/transaction/xa/package.html
Index: package.html
===================================================================
<body>
<!--
JBoss, the OpenSource J2EE webOS
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This library 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
Lesser General Public License for more details.
-->
This package contains the classes and interfaces that define the interaction
between the transaction manager and the resources it manages.
<p>
Classes and interfaces here are conforming to the
<a href="http://java.sun.com/products/jta/";>Java Transaction API
(JTA) 1.0.1 specification</a>.
<p>
The interaction is modelled after the X/Open CAE Specification
(Distributed Transaction Processing: The XA Specification).
The <a
href="http://www.omg.org/technology/documents/formal/transaction_service.htm";>CORBA
CosTransactions specification</a> is freely available, and gives
a pretty good overview of the XA protocol.
</body>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
