KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jms > XASession


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 package javax.jms;
25
26 import javax.transaction.xa.XAResource JavaDoc;
27
28 /** The <CODE>XASession</CODE> interface extends the capability of
29   * <CODE>Session</CODE> by adding access to a JMS provider's support for the
30   * Java Transaction API (JTA) (optional). This support takes the form of a
31   * <CODE>javax.transaction.xa.XAResource</CODE> object. The functionality of
32   * this object closely resembles that defined by the standard X/Open XA
33   * Resource interface.
34   *
35   * <P>An application server controls the transactional assignment of an
36   * <CODE>XASession</CODE> by obtaining its <CODE>XAResource</CODE>. It uses
37   * the <CODE>XAResource</CODE> to assign the session to a transaction, prepare
38   * and commit work on the transaction, and so on.
39   *
40   * <P>An <CODE>XAResource</CODE> provides some fairly sophisticated facilities
41   * for interleaving work on multiple transactions, recovering a list of
42   * transactions in progress, and so on. A JTA aware JMS provider must fully
43   * implement this functionality. This could be done by using the services
44   * of a database that supports XA, or a JMS provider may choose to implement
45   * this functionality from scratch.
46   *
47   * <P>A client of the application server is given what it thinks is a
48   * regular JMS <CODE>Session</CODE>. Behind the scenes, the application server
49   * controls the transaction management of the underlying
50   * <CODE>XASession</CODE>.
51   *
52   * <P>The <CODE>XASession</CODE> interface is optional. JMS providers
53   * are not required to support this interface. This interface is for
54   * use by JMS providers to support transactional environments.
55   * Client programs are strongly encouraged to use the transactional support
56   * available in their environment, rather than use these XA
57   * interfaces directly.
58   *
59   * @version 1.1 February 2, 2002
60   * @author Mark Hapner
61   * @author Rich Burridge
62   * @author Kate Stout
63   *
64   * @see javax.jms.Session
65   */

66  
67 public interface XASession extends Session JavaDoc {
68
69    /** Gets the session associated with this <CODE>XASession</CODE>.
70       *
71       * @return the session object
72       *
73       * @exception JMSException if an internal error occurs.
74       *
75       * @since 1.1
76       */

77  
78         Session JavaDoc
79         getSession() throws JMSException JavaDoc;
80   
81     /** Returns an XA resource to the caller.
82       *
83       * @return an XA resource to the caller
84       */

85
86      XAResource JavaDoc
87      getXAResource();
88
89     /** Indicates whether the session is in transacted mode.
90       *
91       * @return true
92       *
93       * @exception JMSException if the JMS provider fails to return the
94       * transaction mode due to some internal error.
95       */

96
97     boolean
98     getTransacted() throws JMSException JavaDoc;
99
100
101     /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
102       * not be called for an <CODE>XASession</CODE> object.
103       *
104       * @exception TransactionInProgressException if the method is called on
105       * an <CODE>XASession</CODE>.
106       *
107       */

108
109     void
110     commit() throws JMSException JavaDoc;
111
112
113     /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
114       * not be called for an <CODE>XASession</CODE> object.
115       *
116       * @exception TransactionInProgressException if the method is called on
117       * an <CODE>XASession</CODE>.
118       *
119       */

120
121     void
122     rollback() throws JMSException JavaDoc;
123 }
124
Popular Tags