01: /*
02: * @(#)XAConnectionFactory.java 1.10 02/04/09
03: *
04: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
05: *
06: * SUN PROPRIETARY/CONFIDENTIAL.
07: * This software is the proprietary information of Sun Microsystems, Inc.
08: * Use is subject to license terms.
09: *
10: */
11:
12: package javax.jms;
13:
14: /** The <CODE>XAConnectionFactory</CODE> interface is a base interface for the
15: * <CODE>XAQueueConnectionFactory</CODE> and
16: * <CODE>XATopicConnectionFactory</CODE> interfaces.
17: *
18: * <P>Some application servers provide support for grouping JTS capable
19: * resource use into a distributed transaction (optional). To include JMS API transactions
20: * in a JTS transaction, an application server requires a JTS aware JMS
21: * provider. A JMS provider exposes its JTS support using an
22: * <CODE>XAConnectionFactory</CODE> object, which an application server uses
23: * to create <CODE>XAConnection</CODE> objects.
24: *
25: * <P><CODE>XAConnectionFactory</CODE> objects are JMS administered objects,
26: * just like <CODE>ConnectionFactory</CODE> objects. It is expected that
27: * application servers will find them using the Java Naming and Directory
28: * Interface (JNDI) API.
29: *
30: *<P>The <CODE>XAConnectionFactory</CODE> interface is optional. JMS providers
31: * are not required to support this interface. This interface is for
32: * use by JMS providers to support transactional environments.
33: * Client programs are strongly encouraged to use the transactional support
34: * available in their environment, rather than use these XA
35: * interfaces directly.
36: *
37: * @version 1.1 April 4, 2002
38: * @author Mark Hapner
39: * @author Rich Burridge
40: * @author Kate Stout
41: *
42: * @see javax.jms.XAQueueConnectionFactory
43: * @see javax.jms.XATopicConnectionFactory
44: */
45:
46: public interface XAConnectionFactory {
47:
48: /** Creates an <CODE>XAConnection</CODE> with the default user identity.
49: * The connection is created in stopped mode. No messages
50: * will be delivered until the <code>Connection.start</code> method
51: * is explicitly called.
52: *
53: * @return a newly created <CODE>XAConnection</CODE>
54: *
55: * @exception JMSException if the JMS provider fails to create an XA
56: * connection due to some internal error.
57: * @exception JMSSecurityException if client authentication fails due to
58: * an invalid user name or password.
59: *
60: * @since 1.1
61: */
62:
63: XAConnection createXAConnection() throws JMSException;
64:
65: /** Creates an XA connection with the specified user identity.
66: * The connection is created in stopped mode. No messages
67: * will be delivered until the <code>Connection.start</code> method
68: * is explicitly called.
69: *
70: * @param userName the caller's user name
71: * @param password the caller's password
72: *
73: * @return a newly created XA connection
74: *
75: * @exception JMSException if the JMS provider fails to create an XA
76: * connection due to some internal error.
77: * @exception JMSSecurityException if client authentication fails due to
78: * an invalid user name or password.
79: *
80: * @since 1.1
81: */
82:
83: XAConnection createXAConnection(String userName, String password)
84: throws JMSException;
85: }
|