since: 1.2 -

 public  void addConnectionProperty(String name,
    String value) 
{
        connectionProperties.put(name, value);
        this.restartNeeded = true;
}

Add a custom connection property to the set that will be passed to our JDBC driver. This MUST be called before the first connection is retrieved (along with all the other configuration property setters). Calls to this method after the connection pool has been initialized have no effect.

 public synchronized  void close() throws SQLException 
{
        GenericObjectPool oldpool = connectionPool;
        connectionPool = null;
        dataSource = null;
        try {
            if (oldpool != null) {
                oldpool.close();
            }
        } catch(SQLException e) {
            throw e;
        } catch(RuntimeException e) {
            throw e;
        } catch(Exception e) {
            throw new SQLNestedException("Cannot close connection pool", e);
        }
}

Close and release all connections that are currently stored in the connection pool associated with our data source.

 protected synchronized DataSource createDataSource() throws SQLException 
{
        // Return the pool if we have already created it
        if (dataSource != null) {
            return (dataSource);
        }
        // Load the JDBC driver class
        if (driverClassName != null) {
            try {
                Class.forName(driverClassName);
            } catch (Throwable t) {
                String message = "Cannot load JDBC driver class '" +
                    driverClassName + "'";
                logWriter.println(message);
                t.printStackTrace(logWriter);
                throw new SQLNestedException(message, t);
            }
        }
        // Create a JDBC driver instance
        Driver driver = null;
        try {
            driver = DriverManager.getDriver(url);
        } catch (Throwable t) {
            String message = "Cannot create JDBC driver of class '" +
                (driverClassName != null ? driverClassName : "") + 
                "' for connect URL '" + url + "'";
            logWriter.println(message);
            t.printStackTrace(logWriter);
            throw new SQLNestedException(message, t);
        }
        // Can't test without a validationQuery
        if (validationQuery == null) {
            setTestOnBorrow(false);
            setTestOnReturn(false);
            setTestWhileIdle(false);
        }
        // Create an object pool to contain our active connections
        if ((abandonedConfig != null) && (abandonedConfig.getRemoveAbandoned())) {
            connectionPool = new AbandonedObjectPool(null,abandonedConfig);
        }
        else {
            connectionPool = new GenericObjectPool();
        }
        connectionPool.setMaxActive(maxActive);
        connectionPool.setMaxIdle(maxIdle);
        connectionPool.setMinIdle(minIdle);
        connectionPool.setMaxWait(maxWait);
        connectionPool.setTestOnBorrow(testOnBorrow);
        connectionPool.setTestOnReturn(testOnReturn);
        connectionPool.setTimeBetweenEvictionRunsMillis(timeBetweenEvictionRunsMillis);
        connectionPool.setNumTestsPerEvictionRun(numTestsPerEvictionRun);
        connectionPool.setMinEvictableIdleTimeMillis(minEvictableIdleTimeMillis);
        connectionPool.setTestWhileIdle(testWhileIdle);
        // Set up statement pool, if desired
        GenericKeyedObjectPoolFactory statementPoolFactory = null;
        if (isPoolPreparedStatements()) {
            statementPoolFactory = new GenericKeyedObjectPoolFactory(null, 
                        -1, // unlimited maxActive (per key)
                        GenericKeyedObjectPool.WHEN_EXHAUSTED_FAIL, 
                        0, // maxWait
                        1, // maxIdle (per key) 
                        maxOpenPreparedStatements); 
        }
        // Set up the driver connection factory we will use
        if (username != null) {
            connectionProperties.put("user", username);
        } else {
            log("DBCP DataSource configured without a 'username'");
        }
        if (password != null) {
            connectionProperties.put("password", password);
        } else {
            log("DBCP DataSource configured without a 'password'");
        }
        DriverConnectionFactory driverConnectionFactory =
            new DriverConnectionFactory(driver, url, connectionProperties);
        // Set up the poolable connection factory we will use
        PoolableConnectionFactory connectionFactory = null;
        try {
            connectionFactory =
                new PoolableConnectionFactory(driverConnectionFactory,
                                              connectionPool,
                                              statementPoolFactory,
                                              validationQuery,
                                              defaultReadOnly,
                                              defaultAutoCommit,
                                              defaultTransactionIsolation,
                                              defaultCatalog,
                                              abandonedConfig);
            if (connectionFactory == null) {
                throw new SQLException("Cannot create PoolableConnectionFactory");
            }
            validateConnectionFactory(connectionFactory);
        } catch (RuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new SQLNestedException("Cannot create PoolableConnectionFactory (" + e.getMessage() + ")", e);
        }
        // Create and return the pooling data source to manage the connections
        dataSource = new PoolingDataSource(connectionPool);
        ((PoolingDataSource) dataSource).setAccessToUnderlyingConnectionAllowed(isAccessToUnderlyingConnectionAllowed());
        dataSource.setLogWriter(logWriter);
        try {
            for (int i = 0 ; i <  initialSize ; i++) {
                connectionPool.addObject();
            }
        } catch (Exception e) {
            throw new SQLNestedException("Error preloading the connection pool", e);
        }
        return dataSource;
}

Create (if necessary) and return the internal data source we are using to manage our connections.

IMPLEMENTATION NOTE - It is tempting to use the "double checked locking" idiom in an attempt to avoid synchronizing on every single call to this method. However, this idiom fails to work correctly in the face of some optimizations that are legal for a JVM to perform.

 public Connection getConnection() throws SQLException 
{
    // ----------------------------------------------------- DataSource Methods
        return createDataSource().getConnection();
}

Create (if necessary) and return a connection to the database.

 public Connection getConnection(String username,
    String password) throws SQLException 
{
        // This method isn't supported by the PoolingDataSource returned by
        // the createDataSource
        throw new UnsupportedOperationException("Not supported by BasicDataSource");
        // return createDataSource().getConnection(username, password);
}

BasicDataSource does NOT support this method.

 public synchronized boolean getDefaultAutoCommit() 
{
                      
        return this.defaultAutoCommit;
}

Returns the default auto-commit property.

 public synchronized String getDefaultCatalog() 
{
                  
        return this.defaultCatalog;
}

Returns the default catalog.

 public synchronized boolean getDefaultReadOnly() 
{
                       
        if (this.defaultReadOnly != null) {
            return this.defaultReadOnly.booleanValue();
        }
        return false;
}

Returns the default readOnly property.

 public synchronized int getDefaultTransactionIsolation() 
{
                             
        return this.defaultTransactionIsolation;
}

Returns the default transaction isolation state of returned connections.

 public synchronized String getDriverClassName() 
{
                      
        return this.driverClassName;
}

Returns the jdbc driver class name.

 public synchronized int getInitialSize() 
{
    
        return this.initialSize;
}

Returns the initial size of the connection pool.

 public boolean getLogAbandoned() 
{
   
        if (abandonedConfig != null) {
            return abandonedConfig.getLogAbandoned();
        }
        return false;
}

Flag to log stack traces for application code which abandoned a Statement or Connection.

Defaults to false.

Logging of abandoned Statements and Connections adds overhead for every Connection open or new Statement because a stack trace has to be generated.

 public PrintWriter getLogWriter() throws SQLException 
{
        return createDataSource().getLogWriter();
}

Returns the log writer being used by this data source.

Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public int getLoginTimeout() throws SQLException 
{
        return createDataSource().getLoginTimeout();
}

Returns the login timeout (in seconds) for connecting to the database.

Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public synchronized int getMaxActive() 
{
                                          
        return this.maxActive;
}

Returns the maximum number of active connections that can be allocated at the same time.

A non-positive number means that there is no limit.

 public synchronized int getMaxIdle() 
{
                                        
        return this.maxIdle;
}

Returns the maximum number of connections that can remain idle in the pool.

A negative value indicates that there is no limit

 public synchronized int getMaxOpenPreparedStatements() 
{
                           
        return this.maxOpenPreparedStatements;
}

Gets the value of the #maxOpenPreparedStatements property.

 public synchronized long getMaxWait() 
{
                                               
        return this.maxWait;
}

Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.

Returns -1 if the pool is set to wait indefinitely.

 public synchronized long getMinEvictableIdleTimeMillis() 
{
                         
        return this.minEvictableIdleTimeMillis;
}

Returns the #minEvictableIdleTimeMillis property.

 public synchronized int getMinIdle() 
{
                             
        return this.minIdle;
}

Returns the minimum number of idle connections in the pool

 public synchronized int getNumActive() 
{
        if (connectionPool != null) {
            return connectionPool.getNumActive();
        } else {
            return 0;
        }
}

[Read Only] The current number of active connections that have been allocated from this data source.

 public synchronized int getNumIdle() 
{
        if (connectionPool != null) {
            return connectionPool.getNumIdle();
        } else {
            return 0;
        }
}

[Read Only] The current number of idle connections that are waiting to be allocated from this data source.

 public synchronized int getNumTestsPerEvictionRun() 
{
                                
        return this.numTestsPerEvictionRun;
}

Returns the value of the #numTestsPerEvictionRun property.

 public synchronized String getPassword() 
{
                         
        return this.password;
}

Returns the password passed to the JDBC driver to establish connections.

 public boolean getRemoveAbandoned() 
{
   
        if (abandonedConfig != null) {
            return abandonedConfig.getRemoveAbandoned();
        }
        return false;
}

Flag to remove abandoned connections if they exceed the removeAbandonedTimout. Set to true or false, default false. If set to true a connection is considered abandoned and eligible for removal if it has been idle longer than the removeAbandonedTimeout. Setting this to true can recover db connections from poorly written applications which fail to close a connection.

 public int getRemoveAbandonedTimeout() 
{
 
        if (abandonedConfig != null) {
            return abandonedConfig.getRemoveAbandonedTimeout();
        }
        return 300;
}

Timeout in seconds before an abandoned connection can be removed. Defaults to 300 seconds.

 public synchronized boolean getTestOnBorrow() 
{
                              
        return this.testOnBorrow;
}

Returns the #testOnBorrow property.

 public synchronized boolean getTestOnReturn() 
{
                                
        return this.testOnReturn;
}

Returns the value of the #testOnReturn property.

 public synchronized boolean getTestWhileIdle() 
{
                                
        return this.testWhileIdle;
}

Returns the value of the #testWhileIdle property.

 public synchronized long getTimeBetweenEvictionRunsMillis() 
{
        
        return this.timeBetweenEvictionRunsMillis;
}

Returns the value of the #timeBetweenEvictionRunsMillis property.

 public synchronized String getUrl() 
{
                             
        return this.url;
}

Returns the JDBC connection #url property.

 public synchronized String getUsername() 
{
                             
        return this.username;
}

Returns the JDBC connection #username property.

 public synchronized String getValidationQuery() 
{
                            
        return this.validationQuery;
}

Returns the validation query used to validate connections before returning them.

 public synchronized boolean isAccessToUnderlyingConnectionAllowed() 
{
 
        return this.accessToUnderlyingConnectionAllowed;
}

Returns the value of the accessToUnderlyingConnectionAllowed property.

 public synchronized boolean isPoolPreparedStatements() 
{
    
        return this.poolPreparedStatements;
}

Returns true if we are pooling statements.

 public  void removeConnectionProperty(String name) 
{
        connectionProperties.remove(name);
        this.restartNeeded = true;
}

Remove a custom connection property.

 public synchronized  void setAccessToUnderlyingConnectionAllowed(boolean allow) 
{
        this.accessToUnderlyingConnectionAllowed = allow;
        this.restartNeeded = true;
}

Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to the underlying connection. (Default: false)

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDefaultAutoCommit(boolean defaultAutoCommit) 
{
        this.defaultAutoCommit = defaultAutoCommit;
        this.restartNeeded = true;
}

Sets default auto-commit state of connections returned by this datasource.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDefaultCatalog(String defaultCatalog) 
{
        if ((defaultCatalog != null) && (defaultCatalog.trim().length()  > 0)) {
            this.defaultCatalog = defaultCatalog;
        }
        else {
            this.defaultCatalog = null;
        }
        this.restartNeeded = true;
}

Sets the default catalog.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDefaultReadOnly(boolean defaultReadOnly) 
{
        this.defaultReadOnly = defaultReadOnly ? Boolean.TRUE : Boolean.FALSE;
        this.restartNeeded = true;
}

Sets defaultReadonly property.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDefaultTransactionIsolation(int defaultTransactionIsolation) 
{
        this.defaultTransactionIsolation = defaultTransactionIsolation;
        this.restartNeeded = true;
}

Sets the default transaction isolation state for returned connections.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDriverClassName(String driverClassName) 
{
        if ((driverClassName != null) && (driverClassName.trim().length()  > 0)) {
            this.driverClassName = driverClassName;
        }
        else {
            this.driverClassName = null;
        }
        this.restartNeeded = true;
}

Sets the jdbc driver class name.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setInitialSize(int initialSize) 
{
        this.initialSize = initialSize;
        this.restartNeeded = true;
}

Sets the initial size of the connection pool.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setLogAbandoned(boolean logAbandoned) 
{
        if (abandonedConfig == null) {
            abandonedConfig = new AbandonedConfig();
        }
        abandonedConfig.setLogAbandoned(logAbandoned);
        this.restartNeeded = true;
}

 public  void setLogWriter(PrintWriter logWriter) throws SQLException 
{
        createDataSource().setLogWriter(logWriter);
        this.logWriter = logWriter;
}

Sets the log writer being used by this data source.

Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public  void setLoginTimeout(int loginTimeout) throws SQLException 
{
        createDataSource().setLoginTimeout(loginTimeout);
}

Set the login timeout (in seconds) for connecting to the database.

Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public synchronized  void setMaxActive(int maxActive) 
{
        this.maxActive = maxActive;
        if (connectionPool != null) {
            connectionPool.setMaxActive(maxActive);
        }
}

Sets the maximum number of active connections that can be allocated at the same time.

 public synchronized  void setMaxIdle(int maxIdle) 
{
        this.maxIdle = maxIdle;
        if (connectionPool != null) {
            connectionPool.setMaxIdle(maxIdle);
        }
}

Sets the maximum number of connections that can remail idle in the pool.

 public synchronized  void setMaxOpenPreparedStatements(int maxOpenStatements) 
{
        this.maxOpenPreparedStatements = maxOpenStatements;
        this.restartNeeded = true;
}

Sets the value of the #maxOpenPreparedStatements property.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setMaxWait(long maxWait) 
{
        this.maxWait = maxWait;
        if (connectionPool != null) {
            connectionPool.setMaxWait(maxWait);
        }
}

Sets the maxWait property.

 public synchronized  void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) 
{
        this.minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
        if (connectionPool != null) {
            connectionPool.setMinEvictableIdleTimeMillis(minEvictableIdleTimeMillis);
        }
}

Sets the #minEvictableIdleTimeMillis property.

 public synchronized  void setMinIdle(int minIdle) 
{
       this.minIdle = minIdle;
       if (connectionPool != null) {
           connectionPool.setMinIdle(minIdle);
       }
}

Sets the minimum number of idle connections in the pool.

 public synchronized  void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) 
{
        this.numTestsPerEvictionRun = numTestsPerEvictionRun;
        if (connectionPool != null) {
            connectionPool.setNumTestsPerEvictionRun(numTestsPerEvictionRun);
        }
}

Sets the value of the #numTestsPerEvictionRun property.

 public synchronized  void setPassword(String password) 
{
        this.password = password;
        this.restartNeeded = true;
}

Sets the #password .

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setPoolPreparedStatements(boolean poolingStatements) 
{
        this.poolPreparedStatements = poolingStatements;
        this.restartNeeded = true;
}

Sets whether to pool statements or not.

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setRemoveAbandoned(boolean removeAbandoned) 
{
        if (abandonedConfig == null) {
            abandonedConfig = new AbandonedConfig();
        }
        abandonedConfig.setRemoveAbandoned(removeAbandoned);
        this.restartNeeded = true;
}

 public  void setRemoveAbandonedTimeout(int removeAbandonedTimeout) 
{
        if (abandonedConfig == null) {
            abandonedConfig = new AbandonedConfig();
        }
        abandonedConfig.setRemoveAbandonedTimeout(removeAbandonedTimeout);
        this.restartNeeded = true;
}

 public synchronized  void setTestOnBorrow(boolean testOnBorrow) 
{
        this.testOnBorrow = testOnBorrow;
        if (connectionPool != null) {
            connectionPool.setTestOnBorrow(testOnBorrow);
        }
}

Sets the #testOnBorrow property. This property determines whether or not the pool will validate objects before they are borrowed from the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.

 public synchronized  void setTestOnReturn(boolean testOnReturn) 
{
        this.testOnReturn = testOnReturn;
        if (connectionPool != null) {
            connectionPool.setTestOnReturn(testOnReturn);
        }
}

Sets the testOnReturn property. This property determines whether or not the pool will validate objects before they are returned to the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.

 public synchronized  void setTestWhileIdle(boolean testWhileIdle) 
{
        this.testWhileIdle = testWhileIdle;
        if (connectionPool != null) {
            connectionPool.setTestWhileIdle(testWhileIdle);
        }
}

Sets the testWhileIdle property. This property determines whether or not the idle object evictor will validate connections. For a true value to have any effect, the validationQuery property must be set to a non-null string.

 public synchronized  void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) 
{
        this.timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
        if (connectionPool != null) {
            connectionPool.setTimeBetweenEvictionRunsMillis(timeBetweenEvictionRunsMillis);
        }
}

Sets the #timeBetweenEvictionRunsMillis property.

 public synchronized  void setUrl(String url) 
{
        this.url = url;
        this.restartNeeded = true;
}

Sets the #url .

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setUsername(String username) 
{
        this.username = username;
        this.restartNeeded = true;
}

Sets the #username .

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setValidationQuery(String validationQuery) 
{
        if ((validationQuery != null) && (validationQuery.trim().length()  > 0)) {
            this.validationQuery = validationQuery;
        } else {
            this.validationQuery = null;
        }
        this.restartNeeded = true;
}

Sets the #validationQuery .

Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.