001: /*
002: * @(#)XASession.java 1.18 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: import javax.transaction.xa.XAResource;
015:
016: /** The <CODE>XASession</CODE> interface extends the capability of
017: * <CODE>Session</CODE> by adding access to a JMS provider's support for the
018: * Java Transaction API (JTA) (optional). This support takes the form of a
019: * <CODE>javax.transaction.xa.XAResource</CODE> object. The functionality of
020: * this object closely resembles that defined by the standard X/Open XA
021: * Resource interface.
022: *
023: * <P>An application server controls the transactional assignment of an
024: * <CODE>XASession</CODE> by obtaining its <CODE>XAResource</CODE>. It uses
025: * the <CODE>XAResource</CODE> to assign the session to a transaction, prepare
026: * and commit work on the transaction, and so on.
027: *
028: * <P>An <CODE>XAResource</CODE> provides some fairly sophisticated facilities
029: * for interleaving work on multiple transactions, recovering a list of
030: * transactions in progress, and so on. A JTA aware JMS provider must fully
031: * implement this functionality. This could be done by using the services
032: * of a database that supports XA, or a JMS provider may choose to implement
033: * this functionality from scratch.
034: *
035: * <P>A client of the application server is given what it thinks is a
036: * regular JMS <CODE>Session</CODE>. Behind the scenes, the application server
037: * controls the transaction management of the underlying
038: * <CODE>XASession</CODE>.
039: *
040: * <P>The <CODE>XASession</CODE> interface is optional. JMS providers
041: * are not required to support this interface. This interface is for
042: * use by JMS providers to support transactional environments.
043: * Client programs are strongly encouraged to use the transactional support
044: * available in their environment, rather than use these XA
045: * interfaces directly.
046: *
047: * @version 1.1 February 2, 2002
048: * @author Mark Hapner
049: * @author Rich Burridge
050: * @author Kate Stout
051: *
052: * @see javax.jms.Session
053: */
054:
055: public interface XASession extends Session {
056:
057: /** Gets the session associated with this <CODE>XASession</CODE>.
058: *
059: * @return the session object
060: *
061: * @exception JMSException if an internal error occurs.
062: *
063: * @since 1.1
064: */
065:
066: Session getSession() throws JMSException;
067:
068: /** Returns an XA resource to the caller.
069: *
070: * @return an XA resource to the caller
071: */
072:
073: XAResource getXAResource();
074:
075: /** Indicates whether the session is in transacted mode.
076: *
077: * @return true
078: *
079: * @exception JMSException if the JMS provider fails to return the
080: * transaction mode due to some internal error.
081: */
082:
083: boolean getTransacted() throws JMSException;
084:
085: /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
086: * not be called for an <CODE>XASession</CODE> object.
087: *
088: * @exception TransactionInProgressException if the method is called on
089: * an <CODE>XASession</CODE>.
090: *
091: */
092:
093: void commit() throws JMSException;
094:
095: /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
096: * not be called for an <CODE>XASession</CODE> object.
097: *
098: * @exception TransactionInProgressException if the method is called on
099: * an <CODE>XASession</CODE>.
100: *
101: */
102:
103: void rollback() throws JMSException;
104: }
|