001: /*
002: * @(#)ConnectionFactory.java 1.11 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: /** A <CODE>ConnectionFactory</CODE> object encapsulates a set of connection
015: * configuration
016: * parameters that has been defined by an administrator. A client uses
017: * it to create a connection with a JMS provider.
018: *
019: * <P>A <CODE>ConnectionFactory</CODE> object is a JMS administered object and
020: * supports concurrent use.
021: *
022: * <P>JMS administered objects are objects containing configuration
023: * information that are created by an administrator and later used by
024: * JMS clients. They make it practical to administer the JMS API in the
025: * enterprise.
026: *
027: * <P>Although the interfaces for administered objects do not explicitly
028: * depend on the Java Naming and Directory Interface (JNDI) API, the JMS API
029: * establishes the convention that JMS clients find administered objects by
030: * looking them up in a JNDI namespace.
031: *
032: * <P>An administrator can place an administered object anywhere in a
033: * namespace. The JMS API does not define a naming policy.
034: *
035: * <P>It is expected that JMS providers will provide the tools an
036: * administrator needs to create and configure administered objects in a
037: * JNDI namespace. JMS provider implementations of administered objects
038: * should be both <CODE>javax.jndi.Referenceable</CODE> and
039: * <CODE>java.io.Serializable</CODE> so that they can be stored in all
040: * JNDI naming contexts. In addition, it is recommended that these
041: * implementations follow the JavaBeans<SUP><FONT SIZE="-2">TM</FONT></SUP>
042: * design patterns.
043: *
044: * <P>This strategy provides several benefits:
045: *
046: * <UL>
047: * <LI>It hides provider-specific details from JMS clients.
048: * <LI>It abstracts administrative information into objects in the Java
049: * programming language ("Java objects")
050: * that are easily organized and administered from a common
051: * management console.
052: * <LI>Since there will be JNDI providers for all popular naming
053: * services, this means that JMS providers can deliver one implementation
054: * of administered objects that will run everywhere.
055: * </UL>
056: *
057: * <P>An administered object should not hold on to any remote resources.
058: * Its lookup should not use remote resources other than those used by the
059: * JNDI API itself.
060: *
061: * <P>Clients should think of administered objects as local Java objects.
062: * Looking them up should not have any hidden side effects or use surprising
063: * amounts of local resources.
064: *
065: * @version 1.1 - February 1, 2002
066: * @author Mark Hapner
067: * @author Rich Burridge
068: * @author Kate Stout
069: *
070: * @see javax.jms.Connection
071: * @see javax.jms.QueueConnectionFactory
072: * @see javax.jms.TopicConnectionFactory
073: */
074:
075: public interface ConnectionFactory {
076: /** Creates a connection with the default user identity.
077: * The connection is created in stopped mode. No messages
078: * will be delivered until the <code>Connection.start</code> method
079: * is explicitly called.
080: *
081: * @return a newly created connection
082: *
083: * @exception JMSException if the JMS provider fails to create the
084: * connection due to some internal error.
085: * @exception JMSSecurityException if client authentication fails due to
086: * an invalid user name or password.
087: * @since 1.1
088: */
089:
090: Connection createConnection() throws JMSException;
091:
092: /** Creates a connection with the specified user identity.
093: * The connection is created in stopped mode. No messages
094: * will be delivered until the <code>Connection.start</code> method
095: * is explicitly called.
096: *
097: * @param userName the caller's user name
098: * @param password the caller's password
099: *
100: * @return a newly created connection
101: *
102: * @exception JMSException if the JMS provider fails to create the
103: * connection due to some internal error.
104: * @exception JMSSecurityException if client authentication fails due to
105: * an invalid user name or password.
106: * @since 1.1
107: */
108:
109: Connection createConnection(String userName, String password)
110: throws JMSException;
111: }
|