1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.transaction;
  6. import javax.transaction.xa.XAResource;
  7. import java.lang.IllegalStateException;
  8. import java.lang.SecurityException;
  9. /**
  10. * The Transaction interface allows operations to be performed against
  11. * the transaction in the target Transactioin object. A Transaction
  12. * object is created corresponding to each global transaction creation.
  13. * The Transaction object can be used for resource enlistment,
  14. * synchronization registration, transaction completion and status
  15. * query operations.
  16. */
  17. public interface Transaction {
  18. /**
  19. * Complete the transaction represented by this Transaction object
  20. *
  21. * @exception RollbackException Thrown to indicate that
  22. * the transaction has been rolled back rather than committed.
  23. *
  24. * @exception HeuristicMixedException Thrown to indicate that a heuristic
  25. * decision was made and that some relevant updates have been committed
  26. * while others have been rolled back.
  27. *
  28. * @exception HeuristicRollbackException Thrown to indicate that a
  29. * heuristic decision was made and that some relevant updates have been
  30. * rolled back.
  31. *
  32. * @exception SecurityException Thrown to indicate that the thread is
  33. * not allowed to commit the transaction.
  34. *
  35. * @exception IllegalStateException Thrown if the current thread is
  36. * not associated with a transaction.
  37. *
  38. * @exception SystemException Thrown if the transaction manager
  39. * encounters an unexpected error condition
  40. */
  41. public void commit() throws RollbackException,
  42. HeuristicMixedException, HeuristicRollbackException,
  43. SecurityException, SystemException;
  44. /**
  45. * Delist the resource specified from the current transaction
  46. * associated with the calling thread.
  47. *
  48. * @param xaRes The XAResource object representing the resource to delist
  49. *
  50. * @param flag One of the values of TMSUCCESS, TMSUSPEND, or TMFAIL.
  51. *
  52. * @exception IllegalStateException Thrown if the transaction in the
  53. * target object is inactive.
  54. *
  55. * @exception SystemException Thrown if the transaction manager
  56. * encounters an unexpected error condition
  57. *
  58. */
  59. public boolean delistResource(XAResource xaRes, int flag)
  60. throws IllegalStateException, SystemException;
  61. /**
  62. * Enlist the resource specified with the current transaction
  63. * context of the calling thread
  64. *
  65. * @param xaRes The XAResource object representing the resource to delist
  66. *
  67. * @return <i>true</i> if the resource was enlisted successfully; otherwise
  68. * <i>false</i>.
  69. *
  70. * @exception RollbackException Thrown to indicate that
  71. * the transaction has been marked for rollback only.
  72. *
  73. * @exception IllegalStateException Thrown if the transaction in the
  74. * target object is in prepared state or the transaction is inactive.
  75. *
  76. * @exception SystemException Thrown if the transaction manager
  77. * encounters an unexpected error condition
  78. *
  79. */
  80. public boolean enlistResource(XAResource xaRes)
  81. throws RollbackException, IllegalStateException,
  82. SystemException;
  83. /**
  84. * Obtain the status of the transaction associated with the current thread.
  85. *
  86. * @return The transaction status. If no transaction is associated with
  87. * the current thread, this method returns the Status.NoTransaction
  88. * value.
  89. *
  90. * @exception SystemException Thrown if the transaction manager
  91. * encounters an unexpected error condition
  92. *
  93. */
  94. public int getStatus() throws SystemException;
  95. /**
  96. * Register a synchronization object for the transaction currently
  97. * associated with the calling thread. The transction manager invokes
  98. * the beforeCompletion method prior to starting the transaction
  99. * commit process. After the transaction is completed, the transaction
  100. * manager invokes the afterCompletion method.
  101. *
  102. * @param sync The Synchronization object for the transaction associated
  103. * with the target object
  104. *
  105. * @exception RollbackException Thrown to indicate that
  106. * the transaction has been marked for rollback only.
  107. *
  108. * @exception IllegalStateException Thrown if the transaction in the
  109. * target object is in prepared state or the transaction is inactive.
  110. *
  111. * @exception SystemException Thrown if the transaction manager
  112. * encounters an unexpected error condition
  113. *
  114. */
  115. public void registerSynchronization(Synchronization sync)
  116. throws RollbackException, IllegalStateException,
  117. SystemException;
  118. /**
  119. * Rollback the transaction represented by this Transaction object.
  120. *
  121. * @exception IllegalStateException Thrown if the transaction in the
  122. * target object is in prepared state or the transaction is inactive.
  123. *
  124. * @exception SystemException Thrown if the transaction manager
  125. * encounters an unexpected error condition
  126. *
  127. */
  128. public void rollback() throws IllegalStateException, SystemException;
  129. /**
  130. * Modify the transaction associated with the current thread such that
  131. * the only possible outcome of the transaction is to roll back the
  132. * transaction.
  133. *
  134. * @exception IllegalStateException Thrown if the current thread is
  135. * not associated with any transaction.
  136. *
  137. * @exception SystemException Thrown if the transaction manager
  138. * encounters an unexpected error condition
  139. *
  140. */
  141. public void setRollbackOnly() throws IllegalStateException,
  142. SystemException;
  143. }