1. /*

  2.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  3.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  4.  */

  5. 

  6. package javax.jms;

  7. 

  8. import javax.transaction.xa.XAResource;

  9. 

  10. /** The <CODE>XASession</CODE> interface extends the capability of 

  11.   * <CODE>Session</CODE> by adding access to a JMS provider's support for the

  12.   * Java Transaction API (JTA) (optional). This support takes the form of a 

  13.   * <CODE>javax.transaction.xa.XAResource</CODE> object. The functionality of 

  14.   * this object closely resembles that defined by the standard X/Open XA 

  15.   * Resource interface.

  16.   *

  17.   * <P>An application server controls the transactional assignment of an 

  18.   * <CODE>XASession</CODE> by obtaining its <CODE>XAResource</CODE>. It uses 

  19.   * the <CODE>XAResource</CODE> to assign the session to a transaction, prepare 

  20.   * and commit work on the transaction, and so on.

  21.   *

  22.   * <P>An <CODE>XAResource</CODE> provides some fairly sophisticated facilities 

  23.   * for interleaving work on multiple transactions, recovering a list of 

  24.   * transactions in progress, and so on. A JTA aware JMS provider must fully 

  25.   * implement this functionality. This could be done by using the services 

  26.   * of a database that supports XA, or a JMS provider may choose to implement 

  27.   * this functionality from scratch.

  28.   *

  29.   * <P>A client of the application server is given what it thinks is a 

  30.   * regular JMS <CODE>Session</CODE>. Behind the scenes, the application server 

  31.   * controls the transaction management of the underlying 

  32.   * <CODE>XASession</CODE>.

  33.   * 

  34.   * @version     1.0 - 13 August 1998

  35.   * @author      Mark Hapner

  36.   * @author      Rich Burridge

  37.   *

  38.   * @see         javax.jms.Session

  39.   */ 

  40.  

  41. public interface XASession extends Session {

  42. 

  43.     /** Returns an XA resource to the caller.

  44.       *

  45.       * @return an XA resource to the caller

  46.       */

  47. 

  48.      XAResource

  49.      getXAResource();

  50. 

  51.     /** Indicates whether the session is in transacted mode.

  52.       *  

  53.       * @return true

  54.       *  

  55.       * @exception JMSException if the JMS provider fails to return the 

  56.       *                         transaction mode due to some internal error.

  57.       */ 

  58. 

  59.     boolean

  60.     getTransacted() throws JMSException;

  61. 

  62. 

  63.     /** Throws a <CODE>TransactionInProgressException</CODE>, since it should 

  64.       * not be called for an <CODE>XASession</CODE> object.

  65.       *

  66.       * @exception TransactionInProgressException if the method is called on 

  67.       *                         an <CODE>XASession</CODE>.

  68.       *                                     

  69.       */

  70. 

  71.     void

  72.     commit() throws JMSException;

  73. 

  74. 

  75.     /** Throws a <CODE>TransactionInProgressException</CODE>, since it should 

  76.       * not be called for an <CODE>XASession</CODE> object.

  77.       *

  78.       * @exception TransactionInProgressException if the method is called on 

  79.       *                         an <CODE>XASession</CODE>.

  80.       *                                     

  81.       */

  82. 

  83.     void

  84.     rollback() throws JMSException;

  85. }