User: sparre
Date: 01/09/24 09:39:32
Modified: src/main/javax/transaction HeuristicCommitException.java
HeuristicMixedException.java
HeuristicRollbackException.java
InvalidTransactionException.java
NotSupportedException.java RollbackException.java
Status.java Synchronization.java
SystemException.java Transaction.java
TransactionManager.java
TransactionRequiredException.java
TransactionRolledbackException.java
UserTransaction.java
Log:
Added some javadocs.
Revision Changes Path
1.2 +21 -10
jboss-j2ee/src/main/javax/transaction/HeuristicCommitException.java
Index: HeuristicCommitException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/HeuristicCommitException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- HeuristicCommitException.java 2001/03/31 01:12:29 1.1
+++ HeuristicCommitException.java 2001/09/24 16:39:32 1.2
@@ -6,23 +6,34 @@
*/
package javax.transaction;
-/** This exception is thrown by the rollback operation on a resource to report
-that a heuristic decision was made and that all relevant updates have been
committed.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception is meant to be thrown by the rollback operation on
+ * a resource to report that a heuristic decision was made and that all
+ * relevant updates have been committed.
+ * <p>
+ * But though defined in JTA this exception is used nowhere in JTA, and
+ * it seems impossible to report a heuristic commit decision with the JTA
+ * API in a portable way.
+ *
+ * @version $Revision: 1.2 $
+ */
public class HeuristicCommitException extends Exception
{
- /** Creates new <code>HeuristicMixedException</code> without detail message.
- */
+ /**
+ * Creates a new <code>HeuristicMixedException</code> without a
+ * detail message.
+ */
public HeuristicCommitException()
{
}
- /** Constructs an <code>HeuristicCommitException</code> with the specified
detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>HeuristicCommitException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public HeuristicCommitException(String msg)
{
super(msg);
1.2 +17 -10
jboss-j2ee/src/main/javax/transaction/HeuristicMixedException.java
Index: HeuristicMixedException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/HeuristicMixedException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- HeuristicMixedException.java 2001/03/31 01:12:29 1.1
+++ HeuristicMixedException.java 2001/09/24 16:39:32 1.2
@@ -6,23 +6,30 @@
*/
package javax.transaction;
-/** This exception is thrown to report that a heuristic decision was made and
-that some relevant updates have been committed and others have been rolled back.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception is thrown to report that a heuristic decision was made and
+ * that some some parts of the transaction have been committed while other
+ * parts have been rolled back.
+ *
+ * @version $Revision: 1.2 $
+ */
public class HeuristicMixedException extends Exception
{
- /** Creates new <code>HeuristicMixedException</code> without detail message.
- */
+ /**
+ * Creates a new <code>HeuristicMixedException</code> without a
+ * detail message.
+ */
public HeuristicMixedException()
{
}
- /** Constructs an <code>HeuristicMixedException</code> with the specified
detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>HeuristicMixedException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public HeuristicMixedException(String msg)
{
super(msg);
1.2 +17 -10
jboss-j2ee/src/main/javax/transaction/HeuristicRollbackException.java
Index: HeuristicRollbackException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/HeuristicRollbackException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- HeuristicRollbackException.java 2001/03/31 01:12:29 1.1
+++ HeuristicRollbackException.java 2001/09/24 16:39:32 1.2
@@ -6,23 +6,30 @@
*/
package javax.transaction;
-/** This exception is thrown by the commit operation to report that a heuristic
-decision was made and that all relevant updates have been rolled back.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception is thrown by the commit operation to report that a
+ * heuristic decision was made and that all relevant updates have been
+ * rolled back.
+ *
+ * @version $Revision: 1.2 $
+ */
public class HeuristicRollbackException extends Exception
{
- /** Creates new <code>HeuristicRollbackException</code> without detail message.
- */
+ /**
+ * Creates a new <code>HeuristicRollbackException</code> without a
+ * detail message.
+ */
public HeuristicRollbackException()
{
}
- /** Constructs an <code>HeuristicRollbackException</code> with the specified
detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>HeuristicRollbackException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public HeuristicRollbackException(String msg)
{
super(msg);
1.2 +20 -11
jboss-j2ee/src/main/javax/transaction/InvalidTransactionException.java
Index: InvalidTransactionException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/InvalidTransactionException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- InvalidTransactionException.java 2001/03/31 01:12:29 1.1
+++ InvalidTransactionException.java 2001/09/24 16:39:32 1.2
@@ -8,24 +8,33 @@
import java.rmi.RemoteException;
-/** This exception indicates that the request carried an invalid transaction
-context. For example, this exception could be raised if an error occurred
-when trying to register a resource.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception indicates an invalid transaction.
+ * <p>
+ * It is thrown from the {@link TransactionManager#resume(Transaction)}
+ * method if the argument is not a valid transaction.
+ * It may also be thrown from an EJB container invocation is the invocation
+ * request carries an invalid transaction propagation context.
+ *
+ * @version $Revision: 1.2 $
+ */
public class InvalidTransactionException extends RemoteException
{
- /** Creates new <code>InvalidTransactionException</code> without detail message.
- */
+ /**
+ * Creates a new <code>InvalidTransactionException</code> without a
+ * detail message.
+ */
public InvalidTransactionException()
{
}
- /** Constructs an <code>InvalidTransactionException</code> with the specified
detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>InvalidTransactionException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public InvalidTransactionException(String msg)
{
super(msg);
1.2 +21 -13 jboss-j2ee/src/main/javax/transaction/NotSupportedException.java
Index: NotSupportedException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/NotSupportedException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- NotSupportedException.java 2001/03/31 01:12:29 1.1
+++ NotSupportedException.java 2001/09/24 16:39:32 1.2
@@ -6,26 +6,34 @@
*/
package javax.transaction;
-/** NotSupportedException exception indicates that the request cannot be
-executed because the operation is not a supported feature. For example, the
-Transaction Manager throws this exception when a calling thread attempts to
-start a new transaction when the thread is already associated with a
-transaction because nested transaction is not supported.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The NotSupportedException exception indicates that an operation is not
+ * supported.
+ *
+ * For example, the {@link TransactionManager#begin()} and
+ * {@link UserTransaction#begin()} methods throw this exception if the
+ * calling thread is already associated with a transaction, and nested
+ * transactions are not supported.
+ *
+ * @version $Revision: 1.2 $
+ */
public class NotSupportedException extends Exception
{
- /** Creates new <code>NotSupportedException</code> without detail message.
- */
+ /**
+ * Creates a new <code>NotSupportedException</code> without a
+ * detail message.
+ */
public NotSupportedException()
{
}
- /** Constructs an <code>NotSupportedException</code> with the specified detail
message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>NotSupportedException</code> with the specified
+ * detail message.
+ *
+ * @param msg the detail message.
+ */
public NotSupportedException(String msg)
{
super(msg);
1.2 +36 -12 jboss-j2ee/src/main/javax/transaction/RollbackException.java
Index: RollbackException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/RollbackException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- RollbackException.java 2001/03/31 01:12:29 1.1
+++ RollbackException.java 2001/09/24 16:39:32 1.2
@@ -6,25 +6,49 @@
*/
package javax.transaction;
-/** RollbackException exception is thrown when the transaction has been marked
-for rollback only or the transaction has been rolled back instead of committed.
-This is a local exception thrown by methods in the UserTransaction, Transaction,
-and TransactionManager interfaces.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The RollbackException exception indicates that either the transaction
+ * has been rolled back or an operation cannot complete because the
+ * transaction is marked for rollback only.
+ * <p>
+ * It is thrown under two circumstances:
+ * <ul>
+ * <li>
+ * At transaction commit time, if the transaction has been marked for
+ * rollback only. In this case, the <code>commit</code> method will roll
+ * back the transaction and throw this exception to indicate that the
+ * transaction could not be committed.
+ * </li>
+ * <li>
+ * At other times, if an operation cannot be completed because the
+ * transaction is marked for rollback only.
+ * The {@link Transaction#enlistResource(javax.transaction.xa.XAResource)
enlistResource}
+ * and {@link Transaction#registerSynchronization(Synchronization)
registerSynchronization}
+ * methods in the {@link Transaction} interface throw this exception to
+ * indicate that the operation cannot be completed because the transaction
+ * is marked for rollback only. In this case, the state of the transaction
+ * remains unchanged.
+ * </li>
+ * </ul>
+ *
+ * @version $Revision: 1.2 $
+ */
public class RollbackException extends Exception
{
- /** Creates new <code>RollbackException</code> without detail message.
- */
+ /**
+ * Creates a new <code>RollbackException</code> without a detail message.
+ */
public RollbackException()
{
}
- /** Constructs an <code>RollbackException</code> with the specified detail
message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>RollbackException</code> with the specified
+ * detail message.
+ *
+ * @param msg the detail message.
+ */
public RollbackException(String msg)
{
super(msg);
1.2 +59 -4 jboss-j2ee/src/main/javax/transaction/Status.java
Index: Status.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/Status.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Status.java 2001/03/31 01:12:29 1.1
+++ Status.java 2001/09/24 16:39:32 1.2
@@ -6,20 +6,75 @@
*/
package javax.transaction;
-/** The Status interface defines the static variable for transaction status code.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The Status interface defines the constants for transaction status codes.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface Status
{
+ /**
+ * Status code indicating an active transaction.
+ */
public static final int STATUS_ACTIVE = 0;
+
+ /**
+ * Status code indicating a transaction that has been marked for
+ * rollback only.
+ */
public static final int STATUS_MARKED_ROLLBACK = 1;
+
+ /**
+ * Status code indicating a transaction that has completed the first
+ * phase of the two-phase commit protocol, but not yet begun the
+ * second phase.
+ * Probably the transaction is waiting for instruction from a superior
+ * coordinator on how to proceed.
+ */
public static final int STATUS_PREPARED = 2;
+
+ /**
+ * Status code indicating a transaction that has been committed.
+ * Probably heuristics still exists, or the transaction would no
+ * longer exist.
+ */
public static final int STATUS_COMMITTED = 3;
+
+ /**
+ * Status code indicating a transaction that has been rolled back.
+ * Probably heuristics still exists, or the transaction would no
+ * longer exist.
+ */
public static final int STATUS_ROLLEDBACK = 4;
+
+ /**
+ * Status code indicating that the transaction status could not be
+ * determined.
+ */
public static final int STATUS_UNKNOWN = 5;
+
+ /**
+ * Status code indicating that no transaction exists.
+ */
public static final int STATUS_NO_TRANSACTION = 6;
+
+ /**
+ * Status code indicating a transaction that has begun the first
+ * phase of the two-phase commit protocol, not not yet completed
+ * this phase.
+ */
public static final int STATUS_PREPARING = 7;
+
+ /**
+ * Status code indicating a transaction that has begun the second
+ * phase of the two-phase commit protocol, but not yet completed
+ * this phase.
+ */
public static final int STATUS_COMMITTING = 8;
+
+ /**
+ * Status code indicating a transaction that is in the process of
+ * rolling back.
+ */
public static final int STATUS_ROLLING_BACK = 9;
}
1.2 +25 -8 jboss-j2ee/src/main/javax/transaction/Synchronization.java
Index: Synchronization.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/Synchronization.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Synchronization.java 2001/03/31 01:12:29 1.1
+++ Synchronization.java 2001/09/24 16:39:32 1.2
@@ -6,16 +6,33 @@
*/
package javax.transaction;
-/** The transaction manager supports a synchronization mechanism that allows
-the interested party to be notified before and after the transaction completes.
-Using the registerSynchronization method, the application server registers a
-Synchronization object for the transaction currently associated with the target
-Transaction object.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This is the callback interface that has to be implemented by objects
+ * interested in receiving notification before and after a transaction
+ * commits or rolls back.
+ *
+ * An interested party can give an instance implementing this interface
+ * as an argument to the
+ * {@link Transaction#registerSynchronization(Synchronization)
Transaction.registerSynchronization}
+ * method to receive callbacks before and after a transaction commits or
+ * rolls back.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface Synchronization
{
+ /**
+ * This method is invoked before the start of the commit or rollback
+ * process. The method invocation is done in the context of the
+ * transaction that is about to be committed or rolled back.
+ */
public void beforeCompletion();
+
+ /**
+ * This method is invoked after the transaction has committed or
+ * rolled back.
+ *
+ * @param status The status of the completed transaction.
+ */
public void afterCompletion(int status);
}
1.3 +26 -14 jboss-j2ee/src/main/javax/transaction/SystemException.java
Index: SystemException.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/SystemException.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SystemException.java 2001/06/22 00:33:32 1.2
+++ SystemException.java 2001/09/24 16:39:32 1.3
@@ -6,33 +6,45 @@
*/
package javax.transaction;
-/** The SystemException is thrown by the transaction manager to indicate that
-it has encountered an unexpected error condition that prevents future
-transaction services from proceeding.
-
-@version $Revision: 1.2 $
-*/
+/**
+ * This exception is thrown to indicate that the transaction manager has
+ * encountered an unexpected error condition that prevents future
+ * transaction services from proceeding.
+ *
+ * @version $Revision: 1.3 $
+ */
public class SystemException extends Exception
{
+ /**
+ * The error code of this exception. Values of this field are not
+ * specified by JTA.
+ */
public int errorCode;
- /** Creates new <code>SystemException</code> without detail message.
- */
+ /**
+ * Creates a new <code>SystemException</code> without a detail message.
+ */
public SystemException()
{
}
- /** Constructs an <code>SystemException</code> with the specified detail
message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>SystemException</code> with the specified
+ * detail message.
+ *
+ * @param msg the detail message.
+ */
public SystemException(String msg)
{
super(msg);
}
- /** Constructs an <code>SystemException</code> with the specified detail
message.
- @param errcode the error code for the exception
- */
+ /**
+ * Constructs an <code>SystemException</code> with the specified
+ * detail message.
+ *
+ * @param errcode the error code for the exception
+ */
public SystemException(int errcode)
{
this.errorCode = errcode;
1.2 +101 -12 jboss-j2ee/src/main/javax/transaction/Transaction.java
Index: Transaction.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/Transaction.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Transaction.java 2001/03/31 01:12:29 1.1
+++ Transaction.java 2001/09/24 16:39:32 1.2
@@ -9,26 +9,115 @@
import java.lang.SecurityException;
import javax.transaction.xa.XAResource;
-/** The Transaction interface allows operations to be performed against the
-transaction in the target Transactioin object. A Transaction object is created
-corresponding to each global transaction creation. The Transaction object can
-be used for resource enlistment, synchronization registration, transaction
-completion and status query operations.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The Transaction interface allows operations to be performed on
+ * transactions.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface Transaction
{
+ /**
+ * Attempt to commit this transaction.
+ *
+ * @throws RollbackException If the transaction was marked for rollback
+ * only, the transaction is rolled back and this exception is
+ * thrown.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ * @throws HeuristicMixedException If a heuristic decision was made and
+ * some some parts of the transaction have been committed while
+ * other parts have been rolled back.
+ * @throws HeuristicRollbackException If a heuristic decision to roll
+ * back the transaction was made.
+ * @throws SecurityException If the caller is not allowed to commit this
+ * transaction.
+ */
public void commit()
throws RollbackException, HeuristicMixedException,
HeuristicRollbackException, SecurityException, SystemException;
- public boolean delistResource(XAResource xaRes, int flag)
+
+ /**
+ * Rolls back this transaction.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where it cannot be rolled back. This could be because the
+ * transaction is no longer active, or because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public void rollback()
throws IllegalStateException, SystemException;
+
+ /**
+ * Mark the transaction so that the only possible outcome is a rollback.
+ *
+ * @throws IllegalStateException If the transaction is not in an active
+ * state.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public void setRollbackOnly()
+ throws IllegalStateException, SystemException;
+
+ /**
+ * Get the status of the transaction.
+ *
+ * @return The status of the transaction. This is one of the
+ * {@link Status} constants.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public int getStatus() throws SystemException;
+
+ /**
+ * Enlist an XA resource with this transaction.
+ *
+ * @return <code>true</code> if the resource could be enlisted with
+ * this transaction, otherwise <code>false</code>.
+ *
+ * @throws RollbackException If the transaction is marked for rollback
+ * only.
+ * @throws IllegalStateException If the transaction is in a state
+ * where resources cannot be enlisted. This could be because the
+ * transaction is no longer active, or because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public boolean enlistResource(XAResource xaRes)
throws RollbackException, IllegalStateException, SystemException;
- public int getStatus() throws SystemException;
+
+ /**
+ * Delist an XA resource from this transaction.
+ *
+ * @return <code>true</code> if the resource could be delisted from
+ * this transaction, otherwise <code>false</code>.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where resources cannot be delisted. This could be because the
+ * transaction is no longer active.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public boolean delistResource(XAResource xaRes, int flag)
+ throws IllegalStateException, SystemException;
+
+ /**
+ * Register a {@link Synchronization} callback with this transaction.
+ *
+ * @throws RollbackException If the transaction is marked for rollback
+ * only.
+ * @throws IllegalStateException If the transaction is in a state
+ * where {@link Synchronization} callbacks cannot be registered.
+ * This could be because the transaction is no longer active,
+ * or because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void registerSynchronization(Synchronization sync)
throws RollbackException, IllegalStateException, SystemException;
- public void rollback() throws IllegalStateException, SystemException;
- public void setRollbackOnly() throws IllegalStateException, SystemException;
}
1.2 +136 -9 jboss-j2ee/src/main/javax/transaction/TransactionManager.java
Index: TransactionManager.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/TransactionManager.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TransactionManager.java 2001/03/31 01:12:29 1.1
+++ TransactionManager.java 2001/09/24 16:39:32 1.2
@@ -6,24 +6,151 @@
*/
package javax.transaction;
-/** The TransactionManager interface defines the methods that allow an
-application server to manage transaction boundaries.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * The TransactionManager interface defines the methods that allow an
+ * application server to manage transactions on behalf of the applications.
+ * <p>
+ * User applications should not use this interface directly, but use
+ * {@link UserTransaction} insted if they need to do their own transaction
+ * management.
+ * <p>
+ * Internally, the transaction manager associates transactions with threads,
+ * and the methods here operate on the transaction associated with the
+ * calling thread.
+ *
+ * @version $Revision: 1.2 $
+ */
public interface TransactionManager
{
+ /**
+ * Starts a new transaction, and associate it with the calling thread.
+ *
+ * @throws NotSupportedException If the calling thread is already
+ * associated with a transaction, and nested transactions are
+ * not supported.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void begin() throws NotSupportedException, SystemException;
+
+ /**
+ * Commit the transaction associated with the calling thread.
+ *
+ * @throws RollbackException If the transaction was marked for rollback
+ * only, the transaction is rolled back and this exception is
+ * thrown.
+ * @throws IllegalStateException If the calling thread is not associated
+ * with a transaction.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ * @throws HeuristicMixedException If a heuristic decision was made and
+ * some some parts of the transaction have been committed while
+ * other parts have been rolled back.
+ * @throws HeuristicRollbackException If a heuristic decision to roll
+ * back the transaction was made.
+ * @throws SecurityException If the caller is not allowed to commit this
+ * transaction.
+ */
public void commit() throws RollbackException, HeuristicMixedException,
HeuristicRollbackException, SecurityException,
IllegalStateException, SystemException;
- public int getStatus() throws SystemException;
- public Transaction getTransaction() throws SystemException;
- public void resume(Transaction tobj) throws InvalidTransactionException,
- IllegalStateException, SystemException;
+
+ /**
+ * Rolls back the transaction associated with the calling thread.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where it cannot be rolled back. This could be because the
+ * calling thread is not associated with a transaction, or
+ * because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SecurityException If the caller is not allowed to roll back
+ * this transaction.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void rollback() throws IllegalStateException, SecurityException,
SystemException;
+
+ /**
+ * Mark the transaction associated with the calling thread for rollback
+ * only.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where it cannot be rolled back. This could be because the
+ * calling thread is not associated with a transaction, or
+ * because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void setRollbackOnly() throws IllegalStateException, SystemException;
+
+ /**
+ * Get the status of the transaction associated with the calling thread.
+ *
+ * @return The status of the transaction. This is one of the
+ * {@link Status} constants. If no transaction is associated
+ * with the calling thread,
+ * {@link Status#STATUS_NO_TRANSACTION} is returned.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public int getStatus() throws SystemException;
+
+ /**
+ * Get the transaction associated with the calling thread.
+ *
+ * @return The transaction associated with the calling thread, or
+ * <code>null</code> if the calling thread is not associated
+ * with a transaction.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public Transaction getTransaction() throws SystemException;
+
+ /**
+ * Change the transaction timeout for transactions started by the calling
+ * thread with the {@link #begin()} method.
+ *
+ * @param seconds The new timeout value, in seconds. If this parameter
+ * is <code>0</code>, the timeout value is reset to the default
+ * value.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void setTransactionTimeout(int seconds) throws SystemException;
+
+ /**
+ * Suspend the association the calling thread has to a transaction,
+ * and return the suspended transaction.
+ * When returning from this method, the calling thread is no longer
+ * associated with a transaction.
+ *
+ * @return The transaction that the calling thread was associated with,
+ * or <code>null</code> if the calling thread was not associated
+ * with a transaction.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public Transaction suspend() throws SystemException;
+
+ /**
+ * Resume the association of the calling thread with the given
+ * transaction.
+ *
+ * @param tobj The transaction to be associated with the calling thread.
+ *
+ * @throws InvalidTransactionException If the argument does not represent
+ * a valid transaction.
+ * @throws IllegalStateException If the calling thread is already
+ * associated with a transaction.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public void resume(Transaction tobj) throws InvalidTransactionException,
+ IllegalStateException, SystemException;
}
1.2 +16 -10
jboss-j2ee/src/main/javax/transaction/TransactionRequiredException.java
Index: TransactionRequiredException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/TransactionRequiredException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TransactionRequiredException.java 2001/03/31 01:12:29 1.1
+++ TransactionRequiredException.java 2001/09/24 16:39:32 1.2
@@ -8,23 +8,29 @@
import java.rmi.RemoteException;
-/** This exception indicates that a request carried a null transaction context,
-but the target object requires an activate transaction.
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception indicates that a remote invocation request carried a null
+ * transaction context, but that an active transaction context was needed.
+ *
+ * @version $Revision: 1.2 $
+ */
public class TransactionRequiredException extends RemoteException
{
- /** Creates new <code>TransactionRequiredException</code> without detail
message.
- */
+ /**
+ * Creates a new <code>TransactionRequiredException</code> without a
+ * detail message.
+ */
public TransactionRequiredException()
{
}
- /** Constructs an <code>TransactionRequiredException</code> with the specified
detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>TransactionRequiredException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public TransactionRequiredException(String msg)
{
super(msg);
1.2 +19 -12
jboss-j2ee/src/main/javax/transaction/TransactionRolledbackException.java
Index: TransactionRolledbackException.java
===================================================================
RCS file:
/cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/TransactionRolledbackException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TransactionRolledbackException.java 2001/03/31 01:12:29 1.1
+++ TransactionRolledbackException.java 2001/09/24 16:39:32 1.2
@@ -8,25 +8,32 @@
import java.rmi.RemoteException;
-/** This exception indicates that the transaction associated with processing of
-the request has been rolled back, or marked to roll back. Thus the requested
-operation either could not be performed or was not performed because further
-computation on behalf of the transaction would be fruitless
-
-@version $Revision: 1.1 $
-*/
+/**
+ * This exception indicates that the transaction context carried in the
+ * remote invocation has been rolled back, or was marked for roll back only.
+ *
+ * This indicates to the client that further computation on behalf of this
+ * transaction would be fruitless.
+ *
+ * @version $Revision: 1.2 $
+ */
public class TransactionRolledbackException extends RemoteException
{
- /** Creates new <code>TransactionRolledbackException</code> without detail
message.
- */
+ /**
+ * Creates a new <code>TransactionRolledbackException</code> without
+ * a detail message.
+ */
public TransactionRolledbackException()
{
}
- /** Constructs an <code>TransactionRolledbackException</code> with the
specified detail message.
- @param msg the detail message.
- */
+ /**
+ * Constructs an <code>TransactionRolledbackException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public TransactionRolledbackException(String msg)
{
super(msg);
1.3 +85 -6 jboss-j2ee/src/main/javax/transaction/UserTransaction.java
Index: UserTransaction.java
===================================================================
RCS file: /cvsroot/jboss/jboss-j2ee/src/main/javax/transaction/UserTransaction.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- UserTransaction.java 2001/03/31 01:12:29 1.2
+++ UserTransaction.java 2001/09/24 16:39:32 1.3
@@ -6,20 +6,99 @@
*/
package javax.transaction;
-/** The UserTransaction interface defines the methods that allow an application
-to explicitly manage transaction boundaries.
-
-@version $Revision: 1.2 $
-*/
+/**
+ * This interface allows an application to explicitly manage transactions.
+ *
+ * @version $Revision: 1.3 $
+ */
public interface UserTransaction
{
+ /**
+ * Starts a new transaction, and associate it with the calling thread.
+ *
+ * @throws NotSupportedException If the calling thread is already
+ * associated with a transaction, and nested transactions are
+ * not supported.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void begin() throws NotSupportedException, SystemException;
+
+ /**
+ * Commit the transaction associated with the calling thread.
+ *
+ * @throws RollbackException If the transaction was marked for rollback
+ * only, the transaction is rolled back and this exception is
+ * thrown.
+ * @throws IllegalStateException If the calling thread is not associated
+ * with a transaction.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ * @throws HeuristicMixedException If a heuristic decision was made and
+ * some some parts of the transaction have been committed while
+ * other parts have been rolled back.
+ * @throws HeuristicRollbackException If a heuristic decision to roll
+ * back the transaction was made.
+ * @throws SecurityException If the caller is not allowed to commit this
+ * transaction.
+ */
public void commit() throws RollbackException, HeuristicMixedException,
HeuristicRollbackException, SecurityException,
IllegalStateException, SystemException;
- public int getStatus() throws SystemException;
+
+ /**
+ * Rolls back the transaction associated with the calling thread.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where it cannot be rolled back. This could be because the
+ * calling thread is not associated with a transaction, or
+ * because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SecurityException If the caller is not allowed to roll back
+ * this transaction.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void rollback() throws IllegalStateException, SecurityException,
SystemException;
+
+ /**
+ * Mark the transaction associated with the calling thread for rollback
+ * only.
+ *
+ * @throws IllegalStateException If the transaction is in a state
+ * where it cannot be rolled back. This could be because the
+ * calling thread is not associated with a transaction, or
+ * because it is in the
+ * {@link Status#STATUS_PREPARED prepared state}.
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void setRollbackOnly() throws IllegalStateException, SystemException;
+
+ /**
+ * Get the status of the transaction associated with the calling thread.
+ *
+ * @return The status of the transaction. This is one of the
+ * {@link Status} constants. If no transaction is associated
+ * with the calling thread,
+ * {@link Status#STATUS_NO_TRANSACTION} is returned.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
+ public int getStatus() throws SystemException;
+
+ /**
+ * Change the transaction timeout for transactions started by the calling
+ * thread with the {@link #begin()} method.
+ *
+ * @param seconds The new timeout value, in seconds. If this parameter
+ * is <code>0</code>, the timeout value is reset to the default
+ * value.
+ *
+ * @throws SystemException If the transaction service fails in an
+ * unexpected way.
+ */
public void setTransactionTimeout(int seconds) throws SystemException;
}
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
