001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: import javax.transaction.xa.XAResource;
025:
026: /** The <CODE>XASession</CODE> interface extends the capability of
027: * <CODE>Session</CODE> by adding access to a JMS provider's support for the
028: * Java Transaction API (JTA) (optional). This support takes the form of a
029: * <CODE>javax.transaction.xa.XAResource</CODE> object. The functionality of
030: * this object closely resembles that defined by the standard X/Open XA
031: * Resource interface.
032: *
033: * <P>An application server controls the transactional assignment of an
034: * <CODE>XASession</CODE> by obtaining its <CODE>XAResource</CODE>. It uses
035: * the <CODE>XAResource</CODE> to assign the session to a transaction, prepare
036: * and commit work on the transaction, and so on.
037: *
038: * <P>An <CODE>XAResource</CODE> provides some fairly sophisticated facilities
039: * for interleaving work on multiple transactions, recovering a list of
040: * transactions in progress, and so on. A JTA aware JMS provider must fully
041: * implement this functionality. This could be done by using the services
042: * of a database that supports XA, or a JMS provider may choose to implement
043: * this functionality from scratch.
044: *
045: * <P>A client of the application server is given what it thinks is a
046: * regular JMS <CODE>Session</CODE>. Behind the scenes, the application server
047: * controls the transaction management of the underlying
048: * <CODE>XASession</CODE>.
049: *
050: * <P>The <CODE>XASession</CODE> interface is optional. JMS providers
051: * are not required to support this interface. This interface is for
052: * use by JMS providers to support transactional environments.
053: * Client programs are strongly encouraged to use the transactional support
054: * available in their environment, rather than use these XA
055: * interfaces directly.
056: *
057: * @see javax.jms.Session
058: */
059:
060: public interface XASession extends Session {
061:
062: /** Gets the session associated with this <CODE>XASession</CODE>.
063: *
064: * @return the session object
065: *
066: * @exception JMSException if an internal error occurs.
067: *
068: * @since 1.1
069: */
070:
071: Session getSession() throws JMSException;
072:
073: /** Returns an XA resource to the caller.
074: *
075: * @return an XA resource to the caller
076: */
077:
078: XAResource getXAResource();
079:
080: /** Indicates whether the session is in transacted mode.
081: *
082: * @return true
083: *
084: * @exception JMSException if the JMS provider fails to return the
085: * transaction mode due to some internal error.
086: */
087:
088: boolean getTransacted() throws JMSException;
089:
090: /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
091: * not be called for an <CODE>XASession</CODE> object.
092: *
093: * @exception TransactionInProgressException if the method is called on
094: * an <CODE>XASession</CODE>.
095: *
096: */
097:
098: void commit() throws JMSException;
099:
100: /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
101: * not be called for an <CODE>XASession</CODE> object.
102: *
103: * @exception TransactionInProgressException if the method is called on
104: * an <CODE>XASession</CODE>.
105: *
106: */
107:
108: void rollback() throws JMSException;
109: }
|