KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jms > XAConnectionFactory


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
25 package javax.jms;
26
27 /** The <CODE>XAConnectionFactory</CODE> interface is a base interface for the
28   * <CODE>XAQueueConnectionFactory</CODE> and
29   * <CODE>XATopicConnectionFactory</CODE> interfaces.
30   *
31   * <P>Some application servers provide support for grouping JTS capable
32   * resource use into a distributed transaction (optional). To include JMS API transactions
33   * in a JTS transaction, an application server requires a JTS aware JMS
34   * provider. A JMS provider exposes its JTS support using an
35   * <CODE>XAConnectionFactory</CODE> object, which an application server uses
36   * to create <CODE>XAConnection</CODE> objects.
37   *
38   * <P><CODE>XAConnectionFactory</CODE> objects are JMS administered objects,
39   * just like <CODE>ConnectionFactory</CODE> objects. It is expected that
40   * application servers will find them using the Java Naming and Directory
41   * Interface (JNDI) API.
42   *
43   *<P>The <CODE>XAConnectionFactory</CODE> interface is optional. JMS providers
44   * are not required to support this interface. This interface is for
45   * use by JMS providers to support transactional environments.
46   * Client programs are strongly encouraged to use the transactional support
47   * available in their environment, rather than use these XA
48   * interfaces directly.
49   *
50   * @version 1.1 April 4, 2002
51   * @author Mark Hapner
52   * @author Rich Burridge
53   * @author Kate Stout
54   *
55   * @see javax.jms.XAQueueConnectionFactory
56   * @see javax.jms.XATopicConnectionFactory
57   */

58
59 public interface XAConnectionFactory {
60     
61      /** Creates an <CODE>XAConnection</CODE> with the default user identity.
62       * The connection is created in stopped mode. No messages
63       * will be delivered until the <code>Connection.start</code> method
64       * is explicitly called.
65       *
66       * @return a newly created <CODE>XAConnection</CODE>
67       *
68       * @exception JMSException if the JMS provider fails to create an XA
69       * connection due to some internal error.
70       * @exception JMSSecurityException if client authentication fails due to
71       * an invalid user name or password.
72       *
73       * @since 1.1
74       */

75
76     XAConnection JavaDoc
77     createXAConnection() throws JMSException JavaDoc;
78
79
80     /** Creates an XA connection with the specified user identity.
81       * The connection is created in stopped mode. No messages
82       * will be delivered until the <code>Connection.start</code> method
83       * is explicitly called.
84       *
85       * @param userName the caller's user name
86       * @param password the caller's password
87       *
88       * @return a newly created XA connection
89       *
90       * @exception JMSException if the JMS provider fails to create an XA
91       * connection due to some internal error.
92       * @exception JMSSecurityException if client authentication fails due to
93       * an invalid user name or password.
94       *
95       * @since 1.1
96       */

97
98     XAConnection JavaDoc
99     createXAConnection(String JavaDoc userName, String JavaDoc password)
100                          throws JMSException JavaDoc;
101 }
102
Popular Tags