com.sun.messaging

## Class BasicConnectionFactory

- java.lang.Object
- - com.sun.messaging.AdministeredObject
  - - com.sun.messaging.BasicConnectionFactory

- All Implemented Interfaces:
    Serializable, ConnectionFactory
  Direct Known Subclasses:
    ConnectionFactory

      public class BasicConnectionFactory
      extends AdministeredObject
      implements ConnectionFactory

  A `BasicConnectionFactory` encapsulates Sun MQ specific configuration information for Sun MQ `ConnectionFactory` objects and is used to create Connections with a Sun MQ Java Message Service (JMS) provider.
  See Also:
    `javax.jms.ConnectionFactory`, `com.sun.messaging.ConnectionConfiguration`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from class com.sun.messaging.AdministeredObject

      `AO_PROPERTY_TYPE_BOOLEAN, AO_PROPERTY_TYPE_INTEGER, AO_PROPERTY_TYPE_LIST, AO_PROPERTY_TYPE_LONG, AO_PROPERTY_TYPE_PROPERTYOWNER, AO_PROPERTY_TYPE_STRING, cachedConfigurationMap, configuration, configurationLabels, configurationTypes, cr, storedVersion, VERSION`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `BasicConnectionFactory()` Constructs a BasicConnectionFactory with the default configuration.
    `protected` | `BasicConnectionFactory(String defaultsBase)` Constructs a BasicConnectionFactory with the specified configuration.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Connection` | `createConnection()` Creates a Connection with the default user identity.
    `Connection` | `createConnection(String username, String password)` Creates a Connection with a specified user identity.
    `JMSContext` | `createContext()` Creates a JMSContext with the default user identity and an unspecified sessionMode.
    `JMSContext` | `createContext(int sessionMode)` Creates a JMSContext with the default user identity and the specified session mode.
    `JMSContext` | `createContext(String userName, String password)` Creates a JMSContext with the specified user identity and an unspecified sessionMode.
    `JMSContext` | `createContext(String userName, String password, int sessionMode)` Creates a JMSContext with the specified user identity and the specified session mode.
    `String` | `getConnectionType()` Returns the type of connections created by this `BasicConnectionFactory`.
    `protected static com.sun.messaging.jmq.jmsclient.ContainerType` | `getContainerType()`
    `void` | `setConnectionType(String type)` Sets the type of connections created by this `BasicConnectionFactory`.
    `void` | `setDefaultConfiguration()` Sets the minimum `BasicConnectionFactory` configuration defaults required to connect to the Sun MQ Message Service.
    `String` | `toString()` Returns a pretty printed version of the provider specific information for this ConnectionFactory object.

    - ### Methods inherited from class com.sun.messaging.AdministeredObject

      `dump, enumeratePropertyNames, getConfiguration, getCurrentConfiguration, getLabelForGroup, getPropertiesForGroup, getProperty, getPropertyForListValue, getPropertyGroups, getPropertyLabel, getPropertyListOtherName, getPropertyListValues, getPropertyType, getPropertyValueForListValue, getStoredVersion, getVERSION, isPropertyDeprecated, isPropertyHidden, isReadOnly, isStoredVersionCompatible, setProperty, setReadOnly`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### BasicConnectionFactory

          public BasicConnectionFactory()

      Constructs a BasicConnectionFactory with the default configuration.

    - #### BasicConnectionFactory

          protected BasicConnectionFactory(String defaultsBase)

      Constructs a BasicConnectionFactory with the specified configuration.

  - ### Method Detail

    - #### createConnection

          public Connection createConnection()
                                      throws JMSException

      Creates a Connection with the default user identity. The default user identity is defined by the `ConnectionFactory` properties `imqDefaultUsername` and `imqDefaultPassword`
      Specified by:
        `createConnection` in interface `ConnectionFactory`
      Returns:
        a newly created Connection.
      Throws:
        `JMSException` - if a JMS error occurs.
      See Also:
        `ConnectionConfiguration.imqDefaultUsername`, `ConnectionConfiguration.imqDefaultPassword`

    - #### createConnection

          public Connection createConnection(String username,
                                    String password)
                                      throws JMSException

      Creates a Connection with a specified user identity.
      Specified by:
        `createConnection` in interface `ConnectionFactory`
      Parameters:
        `username` - the caller's user name
        `password` - the caller's password
      Returns:
        a newly created connection.
      Throws:
        `JMSException` - if a JMS error occurs.

    - #### createContext

          public JMSContext createContext()

      Description copied from interface: `ConnectionFactory`
      Creates a JMSContext with the default user identity and an unspecified sessionMode.

      A connection and session are created for use by the new JMSContext. The connection is created in stopped mode but will be automatically started when a JMSConsumer is created.

      The behaviour of the session that is created depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the behaviour of the session also depends on whether or not there is an active JTA transaction in progress.

      In a Java SE environment or in the Java EE application client container:

      - The session will be non-transacted and received messages will be acknowledged automatically using an acknowledgement mode of `JMSContext.AUTO_ACKNOWLEDGE` For a definition of the meaning of this acknowledgement mode see the link below.

      In a Java EE web or EJB container, when there is an active JTA transaction in progress:

      - The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the `JMSContext`'s `commit` or `rollback` methods.

      In the Java EE web or EJB container, when there is no active JTA transaction in progress:

      - The session will be non-transacted and received messages will be acknowledged automatically using an acknowledgement mode of `JMSContext.AUTO_ACKNOWLEDGE` For a definition of the meaning of this acknowledgement mode see the link below.
      Specified by:
        `createContext` in interface `ConnectionFactory`
      Returns:
        a newly created JMSContext
      See Also:
        `JMSContext.AUTO_ACKNOWLEDGE`, `ConnectionFactory.createContext(int)`, `ConnectionFactory.createContext(java.lang.String, java.lang.String)`, `ConnectionFactory.createContext(java.lang.String, java.lang.String, int)`, `JMSContext.createContext(int)`

    - #### createContext

          public JMSContext createContext(String userName,
                                 String password)

      Description copied from interface: `ConnectionFactory`
      Creates a JMSContext with the specified user identity and an unspecified sessionMode.

      A connection and session are created for use by the new JMSContext. The connection is created in stopped mode but will be automatically started when a JMSConsumer.

      The behaviour of the session that is created depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the behaviour of the session also depends on whether or not there is an active JTA transaction in progress.

      In a Java SE environment or in the Java EE application client container:

      - The session will be non-transacted and received messages will be acknowledged automatically using an acknowledgement mode of `JMSContext.AUTO_ACKNOWLEDGE` For a definition of the meaning of this acknowledgement mode see the link below.

      In a Java EE web or EJB container, when there is an active JTA transaction in progress:

      - The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the `JMSContext`'s `commit` or `rollback` methods.

      In the Java EE web or EJB container, when there is no active JTA transaction in progress:

      - The session will be non-transacted and received messages will be acknowledged automatically using an acknowledgement mode of `JMSContext.AUTO_ACKNOWLEDGE` For a definition of the meaning of this acknowledgement mode see the link below.
      Specified by:
        `createContext` in interface `ConnectionFactory`
      Parameters:
        `userName` - the caller's user name
        `password` - the caller's password
      Returns:
        a newly created JMSContext
      See Also:
        `JMSContext.AUTO_ACKNOWLEDGE`, `ConnectionFactory.createContext()`, `ConnectionFactory.createContext(int)`, `ConnectionFactory.createContext(java.lang.String, java.lang.String, int)`, `JMSContext.createContext(int)`

    - #### createContext

          public JMSContext createContext(String userName,
                                 String password,
                                 int sessionMode)

      Description copied from interface: `ConnectionFactory`
      Creates a JMSContext with the specified user identity and the specified session mode.

      A connection and session are created for use by the new JMSContext. The JMSContext is created in stopped mode but will be automatically started when a JMSConsumer is created.

      The effect of setting the `sessionMode` argument depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the `sessionMode` argument also depends on whether or not there is an active JTA transaction in progress.

      In a Java SE environment or in the Java EE application client container:

      - If `sessionMode` is set to `JMSContext.SESSION_TRANSACTED` then the session will use a local transaction which may subsequently be committed or rolled back by calling the `JMSContext`'s `commit` or `rollback` methods.
      - If `sessionMode` is set to any of `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` or `JMSContext.DUPS_OK_ACKNOWLEDGE`. then the session will be non-transacted and messages received by this session will be acknowledged according to the value of `sessionMode`. For a definition of the meaning of these acknowledgement modes see the links below.

      In a Java EE web or EJB container, when there is an active JTA transaction in progress:

      - The argument `sessionMode` is ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the `JMSContext`'s `commit` or `rollback` methods. Since the argument is ignored, developers are recommended to use `createSession()`, which has no arguments, instead of this method.

      In the Java EE web or EJB container, when there is no active JTA transaction in progress:

      - The argument `acknowledgeMode` must be set to either of `JMSContext.AUTO_ACKNOWLEDGE` or `JMSContext.DUPS_OK_ACKNOWLEDGE`. The session will be non-transacted and messages received by this session will be acknowledged automatically according to the value of `acknowledgeMode`. For a definition of the meaning of these acknowledgement modes see the links below. The values `JMSContext.SESSION_TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` may not be used.
      Specified by:
        `createContext` in interface `ConnectionFactory`
      Parameters:
        `userName` - the caller's user name
        `password` - the caller's password
        `sessionMode` - indicates which of four possible session modes will be used.
        - If this method is called in a Java SE environment or in the Java EE application client container, the permitted values are `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`.
        - If this method is called in the Java EE web or EJB container when there is an active JTA transaction in progress then this argument is ignored.
        - If this method is called in the Java EE web or EJB container when there is no active JTA transaction in progress, the permitted values are `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. In this case the values `JMSContext.TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` are not permitted.
      Returns:
        a newly created JMSContext
      See Also:
        `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE`, `JMSContext.DUPS_OK_ACKNOWLEDGE`, `ConnectionFactory.createContext()`, `ConnectionFactory.createContext(int)`, `ConnectionFactory.createContext(java.lang.String, java.lang.String)`, `JMSContext.createContext(int)`

    - #### createContext

          public JMSContext createContext(int sessionMode)

      Description copied from interface: `ConnectionFactory`
      Creates a JMSContext with the default user identity and the specified session mode.

      A connection and session are created for use by the new JMSContext. The JMSContext is created in stopped mode but will be automatically started when a JMSConsumer is created.

      The effect of setting the `sessionMode` argument depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the `sessionMode` argument also depends on whether or not there is an active JTA transaction in progress.

      In a Java SE environment or in the Java EE application client container:

      - If `sessionMode` is set to `JMSContext.SESSION_TRANSACTED` then the session will use a local transaction which may subsequently be committed or rolled back by calling the `JMSContext`'s `commit` or `rollback` methods.
      - If `sessionMode` is set to any of `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` or `JMSContext.DUPS_OK_ACKNOWLEDGE`. then the session will be non-transacted and messages received by this session will be acknowledged according to the value of `sessionMode`. For a definition of the meaning of these acknowledgement modes see the links below.

      In a Java EE web or EJB container, when there is an active JTA transaction in progress:

      - The argument `sessionMode` is ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the `JMSContext`'s `commit` or `rollback` methods. Since the argument is ignored, developers are recommended to use `createSession()`, which has no arguments, instead of this method.

      In the Java EE web or EJB container, when there is no active JTA transaction in progress:

      - The argument `acknowledgeMode` must be set to either of `JMSContext.AUTO_ACKNOWLEDGE` or `JMSContext.DUPS_OK_ACKNOWLEDGE`. The session will be non-transacted and messages received by this session will be acknowledged automatically according to the value of `acknowledgeMode`. For a definition of the meaning of these acknowledgement modes see the links below. The values `JMSContext.SESSION_TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` may not be used.
      Specified by:
        `createContext` in interface `ConnectionFactory`
      Parameters:
        `sessionMode` - indicates which of four possible session modes will be used.
        - If this method is called in a Java SE environment or in the Java EE application client container, the permitted values are `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`.
        - If this method is called in the Java EE web or EJB container when there is an active JTA transaction in progress then this argument is ignored.
        - If this method is called in the Java EE web or EJB container when there is no active JTA transaction in progress, the permitted values are `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. In this case the values `JMSContext.TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` are not permitted.
      Returns:
        a newly created JMSContext
      See Also:
        `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE`, `JMSContext.DUPS_OK_ACKNOWLEDGE`, `ConnectionFactory.createContext()`, `ConnectionFactory.createContext(java.lang.String, java.lang.String)`, `ConnectionFactory.createContext(java.lang.String, java.lang.String, int)`, `JMSContext.createContext(int)`

    - #### getContainerType

          protected static com.sun.messaging.jmq.jmsclient.ContainerType getContainerType()

    - #### setConnectionType

          public final void setConnectionType(String type)

      Sets the type of connections created by this `BasicConnectionFactory`.
      Parameters:
        `type` - The type of connections created by this `BasicConnectionFactory`.

    - #### getConnectionType

          public final String getConnectionType()

      Returns the type of connections created by this `BasicConnectionFactory`.
      Returns:
        The type of connections created by this `BasicConnectionFactory`.

    - #### toString

          public String toString()

      Returns a pretty printed version of the provider specific information for this ConnectionFactory object.
      Overrides:
        `toString` in class `AdministeredObject`
      Returns:
        the pretty printed string.

    - #### setDefaultConfiguration

          public void setDefaultConfiguration()

      Sets the minimum `BasicConnectionFactory` configuration defaults required to connect to the Sun MQ Message Service.
      Specified by:
        `setDefaultConfiguration` in class `AdministeredObject`

Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.