FileDocCategorySizeDatePackage
ConnectionManager.javaAPI DocGlassfish v2 API82514Fri May 04 22:35:02 BST 2007com.sun.jdo.spi.persistence.support.sqlstore.connection

ConnectionManager

public class ConnectionManager extends Object

This class represents a connection manager, which creates a JDBC driver manager and manages established database connections. This class lets you specify the following settings for JDBC connections:

  • JDBC driver type
  • data source name (JDBC URL)
  • user name
  • password
  • number of pooled connections (settable when running)
  • how often to try to get a connection after failing the first time and how long to retry (settable when running)
If you define a connection manager as a component, you can define these settings when you partition the application instead of when you write the application.

You can change only the following settings when the connection manager is running:

  • minimum and maximum number of pooled connections, although not whether pooling is on or off (setMinPool and setMaxPool)
  • how often to try to get a connection after failing the first time and how long to retry for a connection (setMsWait and setMsInterval)

You cannot set any other setting while the connection manager is running. To change other settings, shut down the connection manager using the shutDown method, then change the settings. Then, start the connection manager using the startUp method.

If you use a connection manager to manage your database connections, the connection manager can also extend a SynerJ transaction to include JDBC database transactions. In other words, if the JDBC database transactions occur within a SynerJ transaction, the JDBC database transactions are committed or rolled back when the SynerJ transaction committed or rolled back.

You can set up your connection manager to manage database connections in the following ways:

  • Start a new connection every time you request a connection. This approach is often referred to as client-based security, because the security for the connection is based on a particular database client and can be different for each client.
  • Maintain a pool of connections for a given user name and password, and return one of these connections when you request a connection using the getConnection method with no parameters. This approach is often referred to as application-based security, because the security information for the pool of connections is the same and is the same for all clients of the application.
  • Maintain a pool of connections for a given user name and password and start a new connection if you specify another user name and password with the getConnection method. This approach is a blend of client-based and application-based security.

You also have the choice of either defining the connection manager as a service object typed as a ConnectionManager object, or defining the connection manager by dynamically creating a ConnectionManager object in your code. If you define the connection manager as a service object, the SynerJ partitioning system can help you determine how to define partitions that contain the service object by being aware of where JDBC drivers are installed, for example. If you define the ConnectionManager object dynamically, then you need to keep such issues in mind when you define the partitions whose code defines the ConnectionManager objects; the partitioning system will not help you.

Starting a New Database Connection for Each Request (Client-based Security)

In this situation, the connection manager establishes a new connection each time you request a connection. By default, the connection manager does not establish and maintain a pool of connections. In this case, you can leave the maximum and minimum number of pooled connections set to 0. Each time you need a connection to the database, use the getConnection method. You can use the default user name, password, and database URL for the current connection manager by invoking the getConnection method with no parameters. The default settings are specified in one of the ConnectionManager constructors when you create the connection manager. You can also specify a user name, password, and database URL on the getConnection method.

Example of Using ConnectionManager without Pooling
import java.sql.*;
import com.sun.jdo.api.persistence.support.*;
Connection con = myTransaction.getConnection();
Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM T1");

Using a Pool of Database Connections (Application-based Security)

When you create a connection manager using the ConnectionManager class, you can have the connection manager establish a pool of connections for a given user name and password to allow a thread to using an existing connection instead of waiting for a new database connection to be created.

To create a connection manager with a pool of connections using a service object:

  1. Define a service object of the class ConnectionManager.
  2. In the Partition Workshop, set the component properties for the component instance represented by the service object to define the driver name and the default database URL, user name, and password. You can also define the values for the minimum connections and the maximum connections for the connection pool, as well as for how often and how long to try to get a connection after an initial failure to do so.

    If you set the values for the minimum and maximum connections to 0, then no pool of connections is established. Any value greater than 0 means that a pool of connections is established. The maximum value must be equal to or greater than the value of the minimum value. If you set the maximum and minimum as equal values, the number of connections established for the pool will be constant.

    The connection manager establishes the minimum number of connections when it starts up using the default database URL, user name, and password.

To get one of the pooled connections, you can use the getConnection method with no parameters. If all the existing connections are in use, the connection manager establishes another connection with the same database URL, user name, and password and adds it to the pool, up to the specified maximum number of connections.

When you have finished using a connection, you can use the close() method to return the connection to the pool of available connections. The connection manager periodically checks its pool of connections, and can reduce the number of established connections to the minimum number, if enough connections are not in use. At runtime, you can change the maximum and minimum number of connections, because the ConnectionManager is a component.

Using a Pool of Connections and Starting New Connections

You can have the connection manager establish and maintain a pool of connections and have the connection manager establish new connections on a request-by-request basis.

Example of Using ConnectionManager with Pooling
import com.sun.jdo.api.persistence.support.*;
void getT1Data() {
// The following connection is from the connection pool.
Connection myConn = myTransaction.getConnection();
Statement myStatement = myConn.createStatement();
ResultSet myResults = myStatement.executeQuery(
"SELECT * FROM T1);
// Free the connection; it is returned to the connection pool.
myConn.close();

// The connection manager creates a new connection for the
// following request.
Connection yourConn = myConnMgr.getConnection(
"data:oracle:thin:@CUSTOMERDB:1521:ORCL", "paul", "omni8");
Statement yourStatement = yourConn.createStatement();
ResultSet yourResults = yourStatement.executeQuery(
"SELECT Customer, Date, Amount FROM Orders");
.
.
.
}

Fields Summary
private String
driverName
Name of the driver; e.g. "oracle.jdbc.driver.OracleDriver"
private transient String
expandedDriverName
Expanded name of the driver
private String
url
Datasource url; e.g. "jdbc:oracle:oci7:@ABYSS_ORACLE"
private transient String
expandedUrl
Expanded datasource url
private String
userName
DBMS Username.
private transient String
expandedUserName
Expanded user name
private String
password
DBMS password.
private transient String
expandedPassword
Expanded DBMS password.
private int
minPool
The minimum size of the connection pool.
private int
maxPool
The maximum size of the connection pool.
private transient int
poolSize
The current size of the connection pool.
private transient boolean
pooling
True if connection pooling is enabled.
transient com.sun.jdo.spi.persistence.utility.DoubleLinkedList
freeList
The linked list of idle DB connections.
transient com.sun.jdo.spi.persistence.utility.DoubleLinkedList
busyList
The linked list of in-use DB connections.
private transient Hashtable
xactConnections
List of Connections associated with transactions, indexed by transaction object (javax.transaction.Transaction).
transient boolean
shutDownPending
Flag that a shutdown to this ConnectionManager object is pending.
private transient boolean
connectionBlocking
Flag that specifies we are using default connection blocking.
private int
msInterval
Millisecond time to wait between attempts to connect to the database.
private int
msWait
Millisecond time to block while attempting to connect to the database.
private static final int
DEFAULT_RETRY_INTERVAL
private transient boolean
initialized
Indicates whether this ConnectionManager is properly initialized.
private int
loginTimeout
Maximumn number of seconds this DataSource will wait while attempting to connection to a database.
private transient ConnectionImpl
freeConn
Free non-pooled connection to reduce time for getting a new connection.
private static com.sun.jdo.spi.persistence.utility.logging.Logger
logger
The logger
private static final ResourceBundle
messages
I18N message handler
static final String
SQL_SUCCESS
static final String
SQL_WARNING
static final String
SQL_CURSOR_OP
static final String
SQL_DISCONNECT
static final String
SQL_NULL_ELIM
static final String
SQL_R_TRUNC
static final String
SQL_INSUFF_ITEM
static final String
SQL_NOT_REVOKED
static final String
SQL_NOT_GRANTED
static final String
SQL_ZERO_BIT_PAD
static final String
SQL_COND_TOO_LONG
static final String
SQL_QUERY_TOO_LONG
static final String
SQL_NO_DATA
static final String
SQL_DYN_ERROR
static final String
SQL_USING_NO_PARAM
static final String
SQL_USING_NO_TARGET
static final String
SQL_CURSOR_NOEXE
static final String
SQL_USING_REQ
static final String
SQL_PREP_NO_CURSOR
static final String
SQL_RESTRIC_ATTR
static final String
SQL_USING_RESULTS
static final String
SQL_INVAL_DESC_CNT
static final String
SQL_INVAL_DESC_IDX
static final String
SQL_CONN
static final String
SQL_CLIENT_NO_CONN
static final String
SQL_CONN_IN_USE
static final String
SQL_NO_CONN
static final String
SQL_REJECT_CONN
static final String
SQL_CONN_FAIL
static final String
SQL_TRANS_UNK
static final String
SQL_NO_SUPPORT
static final String
SQL_NO_SUPPORT_MULTI
static final String
SQL_INVALID_VALUE
static final String
SQL_DATA
static final String
SQL_DATA_RTRUNC
static final String
SQL_DATA_NULL
static final String
SQL_OUT_OF_RANGE
static final String
SQL_DATA_EXCEPT
static final String
SQL_DATETIME_FMT
static final String
SQL_DATETIME_OVFLO
static final String
SQL_TIMEZONE
static final String
SQL_SUBSTR_ERROR
static final String
SQL_DIV_BY_ZERO
static final String
SQL_INTERVAL_OVFLO
static final String
SQL_INVAL_CHAR_CAST
static final String
SQL_INVAL_ESCAPE_CHAR
static final String
SQL_CHAR_NOT_REP
static final String
SQL_IND_OVERFLOW
static final String
SQL_INVAL_PARAM_VALUE
static final String
SQL_UNTERM_C_STR
static final String
SQL_INVAL_ESCAPE_SEQ
static final String
SQL_STR_LEN_MISMATCH
static final String
SQL_TRIM_ERROR
static final String
SQL_INTEG_CONSTRAINT
static final String
SQL_INVAL_CURSOR_STATE
static final String
SQL_INVAL_TRANS_STATE
static final String
SQL_INVAL_SQL_NAME
static final String
SQL_INVAL_AUTH
static final String
SQL_SYNTAX_DIRECT
static final String
SQL_DESC_EXIST
static final String
SQL_INVAL_CHAR_SET
static final String
SQL_INVAL_TRANS_TERM
static final String
SQL_INVAL_CONN_NAME
static final String
SQL_INVAL_SQL_DESC_NAME
static final String
SQL_INVAL_CURSOR_NAME
static final String
SQL_INVAL_COND_NUM
static final String
SQL_SYNTAX_DYNAMIC
static final String
SQL_AMBIG_CURSOR
static final String
SQL_INVAL_CATALOG
static final String
SQL_INVAL_SCHEMA_NAME
static final String
SQL_TRANS_ROLLBACK
static final String
SQL_TRANS_SERIAL_FAIL
static final String
SQL_TRANS_INTEG
static final String
SQL_TRANS_COMP_UNK
static final String
SQL_SYNTAX
static final String
SQL_CHECK_OPT
static final String
SQL_RMT_DB_ACCESS
Constructors Summary
public ConnectionManager()
Default constructor. Creates a new connection manager and loads the generic JDBC driver. You should typically use one of the other constructors, because you cannot change JDBC drivers after the connection manager has been created.

 // NOI18N


                                            
      
        super();
        this.driverName = null;
        this.expandedDriverName = null;
        this.url = null;
        this.expandedUrl = null;
        this.userName = null;
        this.expandedUserName = null;
        this.password = null;
        this.expandedPassword = null;
        this.minPool = 0;
        this.maxPool = 0;
        this.busyList = null;
        this.freeList = null;
        this.poolSize = 0;
        this.pooling = false;
        this.xactConnections = null;
        this.shutDownPending = false;
        this.connectionBlocking = false;
        this.msWait = 0;
        this.msInterval = 0;
        this.busyList = null;
        this.xactConnections = null;
        this.initialized = false;
public ConnectionManager(String driverName)
Creates a new connection manager and loads the named JDBC driver.

param
driverName name of JDBC driver.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered.

        this();
        try {
            this.setDriverName(driverName);
            startUp();
        } catch (SQLException se) {
            throw se;
        } catch (ClassNotFoundException e) {
            throw e;
        }
public ConnectionManager(String driverName, String url)
Creates a new connection manager, loads the named JDBC driver, and sets the default database URL for the new connection manager.

param
driverName the name of JDBC driver.
param
url the database URL for the data source.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
public ConnectionManager(String driverName, String url, String userName)
Creates a new connection manager, loads the named JDBC driver, and sets the default database URL and user name for the new connection manager.

param
driverName the name of JDBC driver.
param
url the default database URL for the data source.
param
userName the default user name for database connections.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            this.setUserName(userName);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
public ConnectionManager(String driverName, String url, String userName, String password)
Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, and password for the new connection manager.

param
driverName the name of JDBC driver.
param
url the default database URL for the data source.
param
userName the default user name for database connections.
param
password the default password for database connections.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            this.setUserName(userName);
            this.setPassword(password);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
public ConnectionManager(String driverName, String url, String userName, String password, int minPool, int maxPool)
Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, password and minimum and maximum connection pool sizes for the new connection manager.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

param
driverName the name of JDBC driver.
param
url the default database URL for the data source.
param
userName the default user name for database connections.
param
password the default password for database connections.
param
minPool the default minimum size of the connection pool.
param
maxPool the default maximum size of the connection pool.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            this.setUserName(userName);
            this.setPassword(password);
            this.setMinPool(minPool);
            this.setMaxPool(maxPool);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
public ConnectionManager(String driverName, String url, String userName, String password, int minPool, int maxPool, int msWait)
Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, and the length of time to wait for a database connection.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

If msWait is set to 0, the connection manager does not try again to create or return a database connection if the first try fails. For any other value, the connection manager waits 1000 milliseconds (ms) (1 second) before trying again. If the msWait value is less than 1000 ms, the connection manager waits 1000 ms before trying. The connection manager continues trying until the value specified by msWait is met or exceeded.

If you want to set the interval length yourself, you can use the ConnectionManager constructor that specifies the msInterval parameter or the setInterval method.

param
driverName the name of JDBC driver.
param
url the default database URL for the data source.
param
userName the default user name for database connections.
param
password the default password for database connections.
param
minPool the default minimum size of the connection pool.
param
maxPool the default maximum size of the connection pool.
param
msWait the total number of milliseconds to wait for a successful connection.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            this.setUserName(userName);
            this.setPassword(password);
            this.setMinPool(minPool);
            this.setMaxPool(maxPool);
            this.setMsWait(msWait);
            this.setMsInterval(DEFAULT_RETRY_INTERVAL);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
public ConnectionManager(String driverName, String url, String userName, String password, int minPool, int maxPool, int msWait, int msInterval)
Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, the length of time to wait for a database connection, and how frequently to try again to get a database connection.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

If msWait or msInterval is set to 0, the connection manager does not try again to create or return a database connection if the first try fails.

For any other values greater than 0, the The connection manager continues trying after every specified value for msInterval until the value specified by msWait is met or exceeded. If the value for msInterval is greater than the value for msWait, the connection manager tries again to return a connection once, then fails if it could get a connection.

param
driverName the name of JDBC driver.
param
url the default database URL for the data source.
param
userName the default user name for database connections.
param
password the default password for database connections.
param
minPool the default minimum size of the connection pool.
param
maxPool the default maximum size of the connection pool.
param
msWait the total number of milliseconds to wait to get a connection.
param
msInterval the number of milliseconds to wait before trying again to get a connection.
exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

        this();
        try {
            this.setDriverName(driverName);
            this.setURL(url);
            this.setUserName(userName);
            this.setPassword(password);
            this.setMinPool(minPool);
            this.setMaxPool(maxPool);
            this.setMsWait(msWait);
            this.setMsInterval(msInterval);
            startUp();
        } catch (SQLException se) {
            throw se;
        }
Methods Summary
synchronized voidassociateXact(com.sun.jdo.api.persistence.support.Transaction tran, ConnectionImpl conn)
Associate a Connection with a transaction.

param
tran The Transaction's object.
param
conn The Connection.

        if (tran != null)
            this.xactConnections.put((Object) tran, (Object) conn);
private synchronized ConnectionImplcheckXact()
Check whether a ConnectionImpl is already associated with the transaction on the current thread.

return
ConnectionImpl associated with the transaction on the current thread; null otherwise.

        Transaction tran = null;

        /* RESOLVE: Need to reimplement this???
		try
		{
			// Is this ForteJDBCConnet participating in a transaction?
			tran = ThreadContext.transactionContext().getTransaction();
		}
		catch (SystemException ex)
		{
			// There is no transaction.
			return null;
		}
		*/

        // Return Connection associated with this transaction - maybe null?
        if (tran == null)
            return null;
        return (ConnectionImpl) this.xactConnections.get(tran);
synchronized voiddisassociateXact(com.sun.jdo.api.persistence.support.Transaction tran, ConnectionImpl conn, boolean free)
Disassociate a Connection with a transaction.

param
tran The Transaction's object.
param
conn The ForteJDBCConnect hosting the transaction.
param
free The ConnectionImpl should be returned to freePool.
ForteInternal

        ConnectionImpl xactConn = null;

        if (tran != null)
            xactConn = (ConnectionImpl) this.xactConnections.remove((Object) tran);

        if (tran == null || xactConn.equals((Object) conn)) {
            if (free == true) {
                if (conn.connectionManager.shutDownPending == false) {
                    this.freeList.insertAtTail((Linkable) conn);
                } else {
                    conn.close();
                }
            }
        } else {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            //MsgCat.getStr(DbmsMsgCat.DB_ERR_XACT_MISMATCH)
                            "Internal Error: transaction mismatch" // NOI18N
                    ),
                            SQL_TRANS_UNK // 08007
                    );
            throw se;
        }
private java.lang.StringexpandAttribute(java.lang.String envname)
Expand an environment variable specified in attributes into their corresponding values; e.g, if url = ${MYURL}, expand ${MYURL} into its corresponding value.

param
envname environment variable name.
exceptions
SQLException We should come up with a better one.

        String attribute = null;
        /*RESOLVE:
		try
		{
			attribute = ForteProperties.expandVars(envname);
		}
		catch (EnvVariableException e)
		{
			SQLException se = new SQLException
			(
				StringScanner.createParamString
				(
				  I18NHelper.getMessage(messages,
                                             "connection.connectionmanager.badvalue"), // NOI18N
					envname
				),
				SQL_INVAL_PARAM_VALUE
			);
			throw se;
		}
		*/
        if (attribute != null) {
            return attribute;
        } else {
            return envname;
        }
private synchronized voidexpandPool(int connections)
Expand connection pool by connections size.

param
connections Number of connections to add to pool.
exception
SQLException if connection fails.
ForteInternal

        ConnectionImpl conn = null;

        if (this.shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_CONN_FAIL
                    );
            throw se;
        }

        for (int i = 0; i < connections; i++) {
            if (this.poolSize >= this.maxPool) {
                // There is no room for a new connection.
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.maxpool") // NOI18N
                        ),
                                SQL_CONN_FAIL
                        );
                throw se;
            } else // There is room in the pool, so get a new connection.
            {
                try {
                    conn = new ConnectionImpl
                            (
                                    DriverManager.getConnection
                            (
                                    this.expandedUrl,
                                    this.expandedUserName,
                                    this.expandedPassword
                            ),
                                    this.expandedUrl,
                                    this.expandedUserName,
                                    this
                            );
                    conn.setPooled(true);
                    this.freeList.insertAtTail((Linkable) conn);
                    this.poolSize++;
                } catch (SQLException e) {
                    throw e;
                }
            }
        }
protected voidfinalize()
Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true. All busy connections that are not participating in a transaction will be closed when a yieldConnection() is performed. If a connection is participating in a transaction, the connection will be closed after the transaction is commited or rolledback.

see
#yieldConnection

        try {
            shutDown();
        } catch (SQLException se) {
            ; // Ignore it.
        }
public synchronized java.sql.ConnectiongetConnection(java.lang.String userName, java.lang.String password)
Establishes a connection to the database at the default database URL using the specified user name and password.

param
userName the database user name.
param
password the database password.
return
A new database connection.
exception
SQLException if the connection fails.

        boolean debug = logger.isLoggable(Logger.FINEST);


        if (this.shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_CONN_FAIL
                    );
            throw se;
        }

        ConnectionImpl conn = this.checkXact();

        if (conn == null) {
            if (freeConn != null) {
                // We have one available - use it
                if (debug) {
                    logger.finest("sqlstore.connection.conncectiomgr.found",freeConn); // NOI18N
                }
                conn = freeConn;
                freeConn = null;
            } else {
                // No connection is available - get new
                try {
                    // By default, a new ConnectionImpl is non-pooled.
                    conn = new ConnectionImpl
                            (
                                    DriverManager.getConnection
                            (
                                    this.expandedUrl,
                                    this.expandAttribute(userName),
                                    this.expandAttribute(password)
                            ),
                                    this.expandedUrl,
                                    this.expandAttribute(userName),
                                    this
                            );
                    if (debug) {
                        logger.finest("sqlstore.connection.conncectiomgr.getnewconn",conn); // NOI18N
                    }
                } catch (SQLException se) {
                    throw se;
                }
            }
            conn.checkXact();
        } else {
            if (!conn.getUserName().equals(this.expandAttribute(userName))) {
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.getconnection.mismatch") // NOI18N
                        ),
                                SQL_NO_CONN		// 08003
                        );
                throw se;
            }
        }
        conn.setFreePending(false);
        conn.setPooled(false);
        this.busyList.insertAtTail((Linkable) conn);
        return ((Connection) conn);
public synchronized java.sql.ConnectiongetConnection(java.lang.String url, java.lang.String userName, java.lang.String password)
Establishes a connection to the specified database URL using the specified user name and password.

param
url the database URL for the database.
param
userName the database user name.
param
password the database password.
return
A new database connection.
exception
SQLException if the connection fails.

        boolean debug = logger.isLoggable(Logger.FINEST);

        if (this.shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_CONN_FAIL
                    );
            throw se;
        }

        ConnectionImpl conn = this.checkXact();

        if (conn == null) {
            if (freeConn != null) {
                // We have one available - use it
                if (debug) {
                    logger.finest("sqlstore.connection.conncectiomgr.found",freeConn); // NOI18N
                }
                conn = freeConn;
                freeConn = null;
            } else {
                // No connection is available - get new
                try {
                    // By default, a new ConnectionImpl is non-pooled.
                    conn = new ConnectionImpl
                            (
                                    DriverManager.getConnection
                            (
                                    this.expandAttribute(url),
                                    this.expandAttribute(userName),
                                    this.expandAttribute(password)
                            ),
                                    this.expandAttribute(url),
                                    this.expandAttribute(userName),
                                    this
                            );
                    if (debug) {
                        logger.finest("sqlstore.connection.conncectiomgr.getnewconn",conn); // NOI18N
                    }
                } catch (SQLException se) {
                    throw se;
                }
            }
            conn.checkXact();
        } else {
            if ((!conn.getURL().equals(this.expandAttribute(url))) ||
                    (!conn.getUserName().equals(this.expandAttribute(userName)))) {
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.getconnection.mismatch") // NOI18N
                        ),
                                SQL_NO_CONN	// 08003
                        );
                throw se;
            }
        }
        conn.setFreePending(false);
        conn.setPooled(false);
        this.busyList.insertAtTail((Linkable) conn);
        return ((Connection) conn);
public synchronized java.sql.ConnectiongetConnection()
Establishes a connection to the default database URL using the default user name and password.

If the current connection manager maintains a connection pool, this method returns a pooled connection instead of establishing a new connection. If all pooled connections are in use, and the total wait time (msWait) for the connection manager and the retry interval (msInterval) are not 0, then the connection manager tries to get a database connection after the retry interval. The connection manager continues to try until a pooled connection becomes available or until the total time equals or exceeds the wait time. If the wait time expires before the connection manager returns a database connection, this method throws a SQLException exception with SQLState = "08006".

If the current connection manager is not set to try again for connections (the wait time is 0) and no pooled connections are available, this method throws a SQLException exception with SQLState = "08006".

If the current connection manager is being shut down, this method throws a SQLException exception with SQLState = "08003".

return
A new or pooled database connection.
exception
SQLException if no database connection is available.

        if (this.shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_NO_CONN
                    );
            throw se;
        }

        ConnectionImpl conn = this.checkXact();

        if (conn != null) {
            // We already know about this transaction.
        } else if (!this.pooling)					// Get a non-pooled connection.
        {
            conn = (ConnectionImpl) this.getConnection(this.userName,
                    this.password);
            conn.setPooled(false);
            conn.checkXact();
        } else	// This is a pooled connection.
        {
            if (this.freeList.size <= 0)			// Is pool empty?
            {
                if (this.poolSize < this.maxPool)	// Can we expand the pool?
                {
                    try {
                        this.expandPool(1); // Add new connection to the pool.
                    } catch (SQLException se) {
                        throw se;
                    }
                } else if (this.connectionBlocking != true)	// Can't expand the pool.
                {
                    // If not blocking, give up.
                    SQLException se = new SQLException
                            (
                                    StringScanner.createParamString
                            (
                                    I18NHelper.getMessage(messages,
                                            "connection.connectionmanager.maxpool") // NOI18N
                            ),
                                    SQL_INVAL_PARAM_VALUE // 22023
                            );
                    throw se;
                } else								// We are blocking, so...
                {
                    try {
                        this.waitForConnection();	// wait for a connection.
                    } catch (SQLException se) {
                        throw se;
                    }
                }
            }
            conn = (ConnectionImpl) (this.freeList.removeFromHead());
            if (conn == null) {
                // Shouldn't happen.
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.badvalue") // NOI18N
                        ),
                                SQL_INVAL_PARAM_VALUE	// 22023
                        );
                throw se;
            }
            conn.setPooled(true);
            conn.checkXact();
            this.busyList.insertAtTail((Linkable) conn);
        }
        conn.setFreePending(false);
        return ((Connection) conn);
public synchronized java.lang.StringgetDriverName()
Gets the name of the JDBC driver.

return
Name of the JDBC driver.
see
#setDriverName

        return (this.driverName);
public intgetLoginTimeout()

        return loginTimeout;
public synchronized intgetMaxPool()
Gets the maximum number of pooled connections for the current connection manager. If this value is 0, the connection manager does not maintain a connection pool. When you request a connection with the getConnection method, the getConnection method always returns a new connection.

To change the maximum number of pooled connections, use the setMaxPool method.

return
The maximum number of pooled connections the current connection manager maintains.
see
#setMaxPool

        return (this.maxPool);
public synchronized intgetMinPool()
Gets the minimum number of pooled connections for the current connection manager. If this value is 0, the connection manager does not maintain a connection pool until a connection is requested using the getConnection method with no parameters.

To change the minimum number of pooled connections, use the setMinPool method.

return
The minimum number of pooled connections.
see
#getConnection
see
#setMinPool

        return (this.minPool);
public synchronized intgetMsInterval()
Gets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

return
The length of the interval between tries in milliseconds.
see
#getConnection
see
#setMsInterval

        return (this.msInterval);
public synchronized intgetMsWait()
Gets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

return
The wait time in milliseconds.
see
#getConnection
see
#setMsInterval

        return (this.msWait);
public synchronized java.lang.StringgetPassword()
Gets the default database password for the current connection manager. This default was set by the ConnectionManager constructor, and is used if you don't specify another password with a getConnection method. To change this default value, use the setPassword method.

return
The default database password.
see
#getConnection
see
#setPassword

        return (this.password);
public synchronized java.lang.StringgetURL()
Gets the default database URL for the data source. This default is only for the current connection manager and was set by the ConnectionManager constructor. This default is used if you don't specify another database URL with a getConnection method. To change this default value, use the setURL method.

return
The name of the default database URL.
see
#getConnection
see
#setURL

        return (this.url);
public synchronized java.lang.StringgetUserName()
Gets the default database user name for the current connection manager. This default was set by the ConnectionManager constructor, and is used if you don't specify another user name with a getConnection method. To change this default value, use the setUserName method.

return
The default database user name.
see
#getConnection
see
#setUserName

        return (this.userName);
protected synchronized voidreplaceFreeConnection(ConnectionImpl c)
Called by ConnectionImpl to save a connection when it is no longer used. Previous free connection can be released (closed) when a new one becomes available.

        boolean debug = logger.isLoggable(Logger.FINEST);

        if (debug) {
            logger.finest("sqlstore.connection.conncectiomgr.replacefreeconn",freeConn); // NOI18N
        }
        if (freeConn != null) {
            // Release (close) the old connection.
            freeConn.release();
        }
        freeConn = c;
public synchronized voidsetDriverName(java.lang.String driverName)
Sets the name of the JDBC driver.

param
driverName the name of the JDBC driver.
exception
SQLException if the driverName is NULL.
see
#getDriverName

        if (driverName == null) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.nulldriver") // NOI18N
                    ),
                            SQL_INVALID_VALUE // 21000
                    );
            throw se;
        }
        this.driverName = driverName;
public voidsetLoginTimeout(int seconds)

        loginTimeout = seconds;
public synchronized voidsetMaxPool(int maxPool)
Sets the maximum number of pooled connections for the current connection manager. The default maximum number of pooled connections is 0, which means that no connections are pooled.

The specified value of the maxPool parameter must be:

  • greater than or equal to 0.
  • greater than or equal to the current maximum number of pooled connections
  • greater than or equal to the minimum number of pooled connections
Otherwise, this method throws a SQLException.

param
maxPool the maximum number of pooled connections.
exception
SQLException if the connection manager is being shut down or if the maxPool value is not valid.
see
#getMaxPool
see
#getMinPool
see
#setMinPool

        if (shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_CONN_FAIL	// 08006
                    );
            throw se;
        }
        if (maxPool < 0) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.zero"), // NOI18N
                            Integer.toString(maxPool)
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        }
        if (pooling == true) {
            if (maxPool < this.maxPool) {
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.badnew"), // NOI18N
                                Integer.toString(maxPool),
                                Integer.toString(maxPool)
                        ),
                                SQL_INVAL_PARAM_VALUE	// 22023
                        );
                throw se;
            }
        }

        if (maxPool < this.minPool) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.poolsize") // NOI18N
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        }
        this.maxPool = maxPool;
public synchronized voidsetMinPool(int minPool)
Sets the minimum number of pooled connections for the current connection manager. The default minimum number of pooled connections is 0, which means that no connections are pooled until a pooled connection is requested.

The specified value of the minPool parameter must be:

  • greater than or equal to 0.
  • greater than or equal to the current minimum number of pooled connections
  • less than or equal to the maximum number of pooled connections
Otherwise, this method throws a SQLException.

param
minPool the minimum number of pooled connections.
exception
SQLException if the connection manager is being shut down or if the minPool value is not valid.
see
#getMaxPool
see
#getMinPool
see
#setMaxPool

        if (shutDownPending == true) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.isdown") // NOI18N
                    ),
                            SQL_CONN_FAIL // 08006
                    );

            throw se;
        }
        if (minPool < 0) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.zero") // NOI18N
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        }
        if (minPool < this.minPool) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.badnew"), // NOI18N
                            Integer.toString(minPool),
                            Integer.toString(minPool)
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        }
        if (pooling == true) {
            if (minPool > maxPool) {
                SQLException se = new SQLException
                        (
                                StringScanner.createParamString
                        (
                                I18NHelper.getMessage(messages,
                                        "connection.connectionmanager.poolsize") // NOI18N
                        ),
                                SQL_INVAL_PARAM_VALUE	// 22023
                        );
                throw se;
            }
        }
        this.minPool = minPool;
public synchronized voidsetMsInterval(int msInterval)
Sets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

The connection manager retries after the specified interval until the total wait time is equal to or greater than the set wait time. You can determine the total number of tries for a connection based on wait time and interval settings using the following formula, where msWait is the wait time, msInterval is the time between attempts to get a connection: 

tries = msWait/msInterval + 2
For example, if msWait is set to 2000 ms and msInterval is set to 1500 ms, then the connection manager will try to get a database connection 3 times before throwing an exception if it has failed.

If the wait time value is greater than 0 but less than the set value for the interval between retries, the connection manager waits the amount of time specified by the interval, tries once, then returns an exception if it still could not get a connection.

param
msInterval the interval between attempts to get a database connection, in milliseconds.
see
#getConnection
see
#getMsInterval
see
#getMsWait
see
#setMsWait

        if ((msInterval < 0) || (this.msWait < msInterval)) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.badnew"), // NOI18N
                            "MsInterval", // NOI18N
                            "MsWait" // NOI18N
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        } else {
            this.msInterval = msInterval;
        }
public synchronized voidsetMsWait(int msWait)
Sets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait. Setting this value to 0 means that the connection manager does not try again to get a database connection if it fails on the first try.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

The connection manager retries after the set interval until the total wait time is equal to or greater than the specified wait time. You can determine the total number of tries for a connection based on wait time and interval settings using the following formula, where msWait is the wait time, msInterval is the time between attempts to get a connection: 

tries = msWait/msInterval + 2
For example, if msWait is set to 2000 ms and msInterval is set to 1500 ms, then the connection manager will try to get a database connection 3 times before throwing an exception if it has failed.

If the wait time value is less than the set value for the interval between retries, but not zero, the connection manager waits the amount of time specified by the interval, tries once, then returns an exception if it still could not get a connection.

param
msWait the wait time in milliseconds.
see
#getConnection
see
#getMsInterval
see
#getMsWait
see
#setMsInterval

        if (msWait < 0) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.badvalue"), // NOI18N
                            Integer.toString(msWait)
                    ),
                            SQL_INVAL_PARAM_VALUE	// 22023
                    );
            throw se;
        } else if (msWait > 0) {
            this.msWait = msWait;
            this.connectionBlocking = true;
        } else {
            this.msWait = msWait;
            this.connectionBlocking = false;
        }
public synchronized voidsetPassword(java.lang.String password)
Sets the default database password for the current connection manager.

param
password the default password for the current connection manager.
see
#getPassword

        this.password = password;
public synchronized voidsetURL(java.lang.String url)
Sets the default database URL for the data source. This default is only for the current connection manager. To get a connection using a different data source than the default, use the getConnection method that specifies a database URL as a parameter.

param
url URL for this connection manager.
exception
SQLException if the URL is NULL.
see
#getConnection
see
#getURL

        if (url == null) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.nullurl") // NOI18N
                    ),
                            SQL_INVALID_VALUE // 21000
                    );
            throw se;
        }
        this.url = url;
public synchronized voidsetUserName(java.lang.String userName)
Sets the default database user name for the current connection manager.

param
userName the default user name for the current connection manager.
see
#getUserName

        this.userName = userName;
public synchronized voidshutDown()
Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true. All busy connections that are not participating in a transaction will be closed when a yieldConnection() is performed. If a connection is participating in a transaction, the connection will be closed after the transaction is commited or rolledback.

see
#yieldConnection

        this.shutDownPending = true;

        if (this.pooling == true) {
            ConnectionImpl conn;
            this.connectionBlocking = false;
            this.pooling = false;
            this.initialized = false;
            for
                    (
                    conn = (ConnectionImpl) this.freeList.getHead();
                    conn != null;
                    conn = (ConnectionImpl) conn.getNext()
                    ) {
                try {
                    conn.close();
                } catch (SQLException e) {
                    throw e;
                }
            }
            this.freeList = null;
        }
public voidstartUp()
Starts up this ConnectionManager by loading the proper JDBC driver class and initializing the pool if necessary.

You need to call this method if you are using the ConnectionManager as a component, or if you use the default constructor and set the attributes via the setXXX methods.

exception
ClassNotFoundException if the driver cannot be found.
exception
SQLException if a SQL error is encountered.

        if (this.initialized == true) return;

        this.busyList = new DoubleLinkedList();
        this.xactConnections = new Hashtable();
        this.expandedDriverName = this.expandAttribute(this.driverName);
        if (this.expandedDriverName == null) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.nulldriver") // NOI18N
                    ),
                            SQL_INVALID_VALUE // 21000
                    );
            throw se;
        }
        this.expandedUrl = this.expandAttribute(this.url);
        if (this.expandedUrl == null) {
            SQLException se = new SQLException
                    (
                            StringScanner.createParamString
                    (
                            I18NHelper.getMessage(messages,
                                    "connection.connectionmanager.nullurl") // NOI18N
                    ),
                            SQL_INVALID_VALUE // 21000
                    );
            throw se;
        }
        this.expandedUserName = this.expandAttribute(this.userName);
        if (this.expandedUserName == null) {
            this.expandedUserName = ""; // Allow null username. // NOI18N
        }
        this.expandedPassword = this.expandAttribute(this.password);
        if (this.expandedPassword == null) {
            this.expandedPassword = ""; // Allow null password. // NOI18N
        }
        try {
            Class.forName(this.expandedDriverName);

            // Check if connection pooling is requested.
            if ((this.minPool > 0) && (this.maxPool >= this.minPool)) {
                // Yes, create a connection of minPool size.
                this.pooling = true;
                this.freeList = new DoubleLinkedList();
                expandPool(this.minPool);
            } else if ((this.minPool == 0) && (this.maxPool == 0)) {
                // No, pooling is to be disabled.
                this.pooling = false;
            }

        } catch (SQLException se) {
            throw se;
        } catch (ClassNotFoundException e) {
            throw e;
        }
        this.initialized = true;
public synchronized java.lang.StringtoString()
Returns a string representation of the current ConnectionManager object.

return
A String decribing the contents of the current ConnectionManager object.

        /*
		TraceLogger lgr = ThreadContext.lgr();
		// Check for trace flag sp:1:1
		boolean dif = ThreadContext.lgr().test
		(
			TraceLogger.CONFIGURATION,
			TraceLogger.SVC_SP,
			SPLogFlags.CFG_DIFFABLE_EXCEPTS,
			1
		);
		String buf = "ConnectManager@\n"; // NOI18N
		if (dif == false)
		{
			buf = buf + "    busyList = " + this.busyList + "\n"; // NOI18N
		}
		if (this.busyList != null)
		{
			buf = buf + "    busyList Object = " + this.busyList.toString(); // NOI18N
		}
		buf = buf + "    connectionBlocking = " + this.connectionBlocking + "\n"; // NOI18N
		buf = buf + "    driverName = " + this.driverName + "\n"; // NOI18N
		if (dif == false)
		{
			buf = buf + "    expandedDriverName = " + this.expandedDriverName + "\n"; // NOI18N
			buf = buf + "    expandedPassword = " + this.expandedPassword + "\n"; // NOI18N
			buf = buf + "    expandedUrl = " + this.expandedUrl	+ "\n"; // NOI18N
			buf = buf + "    expandedUserName = " + this.expandedUserName + "\n"; // NOI18N
			buf = buf + "    freeList = " + this.freeList + "\n"; // NOI18N
		}
		if (this.freeList != null)
		{
			buf = buf + "    freeList Object = " + this.freeList.toString(); // NOI18N
		}
		if (dif == false)
		{
			buf = buf + "    hashCode = " + this.hashCode() + "\n"; // NOI18N
		}
		buf = buf + "    maxPool = " + this.maxPool + "\n"; // NOI18N
		buf = buf + "    minPool = " + this.minPool	+ "\n"; // NOI18N
		buf = buf + "    msInterval = " + this.msInterval + "\n"; // NOI18N
		buf = buf + "    msWait = " + this.msWait + "\n"; // NOI18N
		buf = buf + "    password = " + this.password + "\n"; // NOI18N
		buf = buf + "    pooling = " + this.pooling + "\n"; // NOI18N
		buf = buf + "    poolSize = " + this.poolSize + "\n"; // NOI18N
		buf = buf + "    shutDownPending = " + this.shutDownPending + "\n"; // NOI18N
		buf = buf + "    url = " + this.url + "\n"; // NOI18N
		buf = buf + "    userName = " + this.userName + "\n"; // NOI18N

        return buf;
		*/

        return null;
private synchronized voidwaitForConnection()
Wait for a pool connection. The thread will wait msInterval milliseconds between tries to get a connection from the pool. If no connection is available after msWait milliseconds, an exception is thrown.

exception
SQLException if connection fails.
ForteInternal

        int interval = this.msInterval;
        int wait = this.msWait;
        int totalTime = 0;
        boolean done = false;
        Thread t = Thread.currentThread();
        do {
            // If there are idle connections in the pool
            if (this.freeList.size > 0) {
                done = true;
            } else // There are no idle connection in the pool
            {
                // Can the pool be expanded?
                if (this.poolSize < this.maxPool) {
                    // Yes, try to expand the pool.
                    try {
                        expandPool(1);
                        done = true;
                    } catch (SQLException se) {
                        throw se;
                    }
                } else // the pool is at maximum size...
                {
                    // If we have waited long enough, throw an exception.
                    if (totalTime >= wait) {
                        SQLException se = new SQLException
                                (
                                        StringScanner.createParamString
                                (
                                        I18NHelper.getMessage(messages,
                                                "connection.connectionmanager.conntimeout") // NOI18N
                                ),
                                        SQL_CONN_FAIL
                                );
                        throw se;
                    } else // Timeout has not expired, sleep for awhile.
                    {
                        try {
                            this.wait(interval);
                        } catch (InterruptedException ie) {
                            SQLException se = new SQLException
                                    (
                                            StringScanner.createParamString
                                    (
                                            I18NHelper.getMessage(messages,
                                                    "connection.connectionmanager.threaditerupted") // NOI18N
                                    ),
                                            SQL_CONN_FAIL
                                    );
                            throw se;
                        }
                    }
                    totalTime += interval;
                }
            }
        } while (!done);