BasicDataSource (Apache Tomcat 7.0.104 API Documentation)

org.apache.tomcat.dbcp.dbcp

## Class BasicDataSource

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp.BasicDataSource

- All Implemented Interfaces:
    Wrapper, CommonDataSource, DataSource

      public class BasicDataSource
      extends Object
      implements DataSource

  Basic implementation of `javax.sql.DataSource` that is configured via JavaBeans properties. This is not the only way to combine the commons-dbcp and commons-pool packages, but provides a "one stop shopping" solution for basic requirements.

  Users extending this class should take care to use appropriate accessors rather than accessing protected fields directly to ensure thread-safety.

  Author:
    Glenn L. Nielsen, Craig R. McClanahan, Dirk Verbeeck

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `closed`
    `protected List<String>` | `connectionInitSqls` These SQL statements run once after a Connection is created.
    `protected GenericObjectPool<PoolableConnection>` | `connectionPool` The object pool that internally manages our connections.
    `protected Properties` | `connectionProperties` The connection properties that will be sent to our JDBC driver when establishing new connections.
    `protected DataSource` | `dataSource` The data source we will use to manage connections.
    `protected boolean` | `defaultAutoCommit` The default auto-commit state of connections created by this pool.
    `protected String` | `defaultCatalog` The default "catalog" of connections created by this pool.
    `protected Boolean` | `defaultReadOnly` The default read-only state of connections created by this pool.
    `protected int` | `defaultTransactionIsolation` The default TransactionIsolation state of connections created by this pool.
    `protected ClassLoader` | `driverClassLoader` The class loader instance to use to load the JDBC driver.
    `protected String` | `driverClassName` The fully qualified Java class name of the JDBC driver to be used.
    `protected int` | `initialSize` The initial number of connections that are created when the pool is started.
    `protected PrintWriter` | `logWriter` The PrintWriter to which log messages should be directed.
    `protected int` | `maxActive` The maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit.
    `protected int` | `maxIdle` The maximum number of connections that can remain idle in the pool, without extra ones being destroyed, or negative for no limit.
    `protected int` | `maxOpenPreparedStatements` The maximum number of open statements that can be allocated from the statement pool at the same time, or non-positive for no limit.
    `protected long` | `maxWait` The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or <= 0 to wait indefinitely.
    `protected long` | `minEvictableIdleTimeMillis` The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
    `protected int` | `minIdle` The minimum number of active connections that can remain idle in the pool, without extra ones being created when the evictor runs, or 0 to create none.
    `protected int` | `numTestsPerEvictionRun` The number of objects to examine during each run of the idle object evictor thread (if any).
    `protected String` | `password` The connection password to be passed to our JDBC driver to establish a connection.
    `protected boolean` | `poolPreparedStatements` Prepared statement pooling for this pool.
    `protected boolean` | `testOnBorrow` The indication of whether objects will be validated before being borrowed from the pool.
    `protected boolean` | `testOnReturn` The indication of whether objects will be validated before being returned to the pool.
    `protected boolean` | `testWhileIdle` The indication of whether objects will be validated by the idle object evictor (if any).
    `protected long` | `timeBetweenEvictionRunsMillis` The number of milliseconds to sleep between runs of the idle object evictor thread.
    `protected String` | `url` The connection URL to be passed to our JDBC driver to establish a connection.
    `protected String` | `username` The connection username to be passed to our JDBC driver to establish a connection.
    `protected String` | `validationQuery` The SQL query that will be used to validate connections from this pool before returning them to the caller.
    `protected int` | `validationQueryTimeout` Timeout in seconds before connection validation queries fail.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BasicDataSource()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConnectionProperty(String name, String value)` Add a custom connection property to the set that will be passed to our JDBC driver.
    `void` | `close()` Closes and releases all idle connections that are currently stored in the connection pool associated with this data source.
    `protected ConnectionFactory` | `createConnectionFactory()` Creates a JDBC connection factory for this datasource.
    `protected void` | `createConnectionPool()` Creates a connection pool for this datasource.
    `protected DataSource` | `createDataSource()` Create (if necessary) and return the internal data source we are using to manage our connections.
    `protected void` | `createDataSourceInstance()` Creates the actual data source instance.
    `protected void` | `createPoolableConnectionFactory(ConnectionFactory driverConnectionFactory, KeyedObjectPoolFactory<PStmtKey,DelegatingPreparedStatement> statementPoolFactory, AbandonedConfig configuration)` Creates the PoolableConnectionFactory and attaches it to the connection pool.
    `Connection` | `getConnection()` Create (if necessary) and return a connection to the database.
    `Connection` | `getConnection(String user, String pass)` BasicDataSource does NOT support this method.
    `Collection<String>` | `getConnectionInitSqls()` Returns the list of SQL statements executed when a physical connection is first created.
    `boolean` | `getDefaultAutoCommit()` Returns the default auto-commit property.
    `String` | `getDefaultCatalog()` Returns the default catalog.
    `boolean` | `getDefaultReadOnly()` Returns the default readOnly property.
    `int` | `getDefaultTransactionIsolation()` Returns the default transaction isolation state of returned connections.
    `ClassLoader` | `getDriverClassLoader()` Returns the class loader specified for loading the JDBC driver.
    `String` | `getDriverClassName()` Returns the JDBC driver class name.
    `int` | `getInitialSize()` Returns the initial size of the connection pool.
    `boolean` | `getLifo()` Returns the LIFO property.
    `boolean` | `getLogAbandoned()` Flag to log stack traces for application code which abandoned a Statement or Connection.
    `int` | `getLoginTimeout()` BasicDataSource does NOT support this method.
    `PrintWriter` | `getLogWriter()` Returns the log writer being used by this data source.
    `int` | `getMaxActive()` Returns the maximum number of active connections that can be allocated at the same time.
    `int` | `getMaxIdle()` Returns the maximum number of connections that can remain idle in the pool.
    `int` | `getMaxOpenPreparedStatements()` Gets the value of the `maxOpenPreparedStatements` property.
    `long` | `getMaxWait()` Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.
    `long` | `getMinEvictableIdleTimeMillis()` Returns the `minEvictableIdleTimeMillis` property.
    `int` | `getMinIdle()` Returns the minimum number of idle connections in the pool.
    `int` | `getNumActive()` [Read Only] The current number of active connections that have been allocated from this data source.
    `int` | `getNumIdle()` [Read Only] The current number of idle connections that are waiting to be allocated from this data source.
    `int` | `getNumTestsPerEvictionRun()` Returns the value of the `numTestsPerEvictionRun` property.
    `Logger` | `getParentLogger()`
    `String` | `getPassword()` Returns the password passed to the JDBC driver to establish connections.
    `boolean` | `getRemoveAbandoned()` Flag to remove abandoned connections if they exceed the removeAbandonedTimout.
    `int` | `getRemoveAbandonedTimeout()` Timeout in seconds before an abandoned connection can be removed.
    `long` | `getSoftMinEvictableIdleTimeMillis()` Returns the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.
    `boolean` | `getTestOnBorrow()` Returns the `testOnBorrow` property.
    `boolean` | `getTestOnReturn()` Returns the value of the `testOnReturn` property.
    `boolean` | `getTestWhileIdle()` Returns the value of the `testWhileIdle` property.
    `long` | `getTimeBetweenEvictionRunsMillis()` Returns the value of the `timeBetweenEvictionRunsMillis` property.
    `String` | `getUrl()` Returns the JDBC connection `url` property.
    `String` | `getUsername()` Returns the JDBC connection `username` property.
    `String` | `getValidationQuery()` Returns the validation query used to validate connections before returning them.
    `int` | `getValidationQueryTimeout()` Returns the validation query timeout.
    `boolean` | `isAccessToUnderlyingConnectionAllowed()` Returns the value of the accessToUnderlyingConnectionAllowed property.
    `boolean` | `isClosed()` If true, this data source is closed and no more connections can be retrieved from this datasource.
    `boolean` | `isPoolPreparedStatements()` Returns true if we are pooling statements.
    `boolean` | `isWrapperFor(Class<?> iface)`
    `protected void` | `log(String message)`
    `void` | `removeConnectionProperty(String name)` Remove a custom connection property.
    `void` | `setAccessToUnderlyingConnectionAllowed(boolean allow)` Sets the value of the accessToUnderlyingConnectionAllowed property.
    `void` | `setConnectionInitSqls(Collection<String> connectionInitSqls)` Sets the list of SQL statements to be executed when a physical connection is first created.
    `void` | `setConnectionProperties(String connectionProperties)` Sets the connection properties passed to driver.connect(...).
    `void` | `setDefaultAutoCommit(boolean defaultAutoCommit)` Sets default auto-commit state of connections returned by this datasource.
    `void` | `setDefaultCatalog(String defaultCatalog)` Sets the default catalog.
    `void` | `setDefaultReadOnly(boolean defaultReadOnly)` Sets defaultReadonly property.
    `void` | `setDefaultTransactionIsolation(int defaultTransactionIsolation)` Sets the default transaction isolation state for returned connections.
    `void` | `setDriverClassLoader(ClassLoader driverClassLoader)` Sets the class loader to be used to load the JDBC driver.
    `void` | `setDriverClassName(String driverClassName)` Sets the JDBC driver class name.
    `void` | `setInitialSize(int initialSize)` Sets the initial size of the connection pool.
    `void` | `setLifo(boolean lifo)` Sets the LIFO property.
    `void` | `setLogAbandoned(boolean logAbandoned)`
    `void` | `setLoginTimeout(int loginTimeout)` BasicDataSource does NOT support this method.
    `void` | `setLogWriter(PrintWriter logWriter)` Sets the log writer being used by this data source.
    `void` | `setMaxActive(int maxActive)` Sets the maximum number of active connections that can be allocated at the same time.
    `void` | `setMaxIdle(int maxIdle)` Sets the maximum number of connections that can remain idle in the pool.
    `void` | `setMaxOpenPreparedStatements(int maxOpenStatements)` Sets the value of the `maxOpenPreparedStatements` property.
    `void` | `setMaxWait(long maxWait)` Sets the maxWait property.
    `void` | `setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)` Sets the `minEvictableIdleTimeMillis` property.
    `void` | `setMinIdle(int minIdle)` Sets the minimum number of idle connections in the pool.
    `void` | `setNumTestsPerEvictionRun(int numTestsPerEvictionRun)` Sets the value of the `numTestsPerEvictionRun` property.
    `void` | `setPassword(String password)` Sets the `password`.
    `void` | `setPoolPreparedStatements(boolean poolingStatements)` Sets whether to pool statements or not.
    `void` | `setRemoveAbandoned(boolean removeAbandoned)` Flag to remove abandoned connections if they exceed the removeAbandonedTimeout.
    `void` | `setRemoveAbandonedTimeout(int removeAbandonedTimeout)` Sets the timeout in seconds before an abandoned connection can be removed.
    `void` | `setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)` Sets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.
    `void` | `setTestOnBorrow(boolean testOnBorrow)` Sets the `testOnBorrow` property.
    `void` | `setTestOnReturn(boolean testOnReturn)` Sets the `testOnReturn` property.
    `void` | `setTestWhileIdle(boolean testWhileIdle)` Sets the `testWhileIdle` property.
    `void` | `setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)` Sets the `timeBetweenEvictionRunsMillis` property.
    `void` | `setUrl(String url)` Sets the `url`.
    `void` | `setUsername(String username)` Sets the `username`.
    `void` | `setValidationQuery(String validationQuery)` Sets the `validationQuery`.
    `void` | `setValidationQueryTimeout(int timeout)` Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query.
    `protected void` | `startPoolMaintenance()` Starts the connection pool maintenance task, if configured.
    `<T> T` | `unwrap(Class<T> iface)`
    `protected static void` | `validateConnectionFactory(PoolableConnectionFactory connectionFactory)`

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

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

- - ### Field Detail

    - #### defaultAutoCommit

          protected volatile boolean defaultAutoCommit

      The default auto-commit state of connections created by this pool.

    - #### defaultReadOnly

          protected transient Boolean defaultReadOnly

      The default read-only state of connections created by this pool.

    - #### defaultTransactionIsolation

          protected volatile int defaultTransactionIsolation

      The default TransactionIsolation state of connections created by this pool.

    - #### defaultCatalog

          protected volatile String defaultCatalog

      The default "catalog" of connections created by this pool.

    - #### driverClassName

          protected String driverClassName

      The fully qualified Java class name of the JDBC driver to be used.

    - #### driverClassLoader

          protected ClassLoader driverClassLoader

      The class loader instance to use to load the JDBC driver. If not specified, `Class.forName(String)` is used to load the JDBC driver. If specified, `Class.forName(String, boolean, ClassLoader)` is used.

    - #### maxActive

          protected int maxActive

      The maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit.

    - #### maxIdle

          protected int maxIdle

      The maximum number of connections that can remain idle in the pool, without extra ones being destroyed, or negative for no limit. If maxIdle is set too low on heavily loaded systems it is possible you will see connections being closed and almost immediately new connections being opened. This is a result of the active threads momentarily closing connections faster than they are opening them, causing the number of idle connections to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

    - #### minIdle

          protected int minIdle

      The minimum number of active connections that can remain idle in the pool, without extra ones being created when the evictor runs, or 0 to create none. The pool attempts to ensure that minIdle connections are available when the idle object evictor runs. The value of this property has no effect unless `timeBetweenEvictionRunsMillis` has a positive value.

    - #### initialSize

          protected int initialSize

      The initial number of connections that are created when the pool is started.
      Since:
        1.2

    - #### maxWait

          protected long maxWait

      The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or <= 0 to wait indefinitely.

    - #### poolPreparedStatements

          protected boolean poolPreparedStatements

      Prepared statement pooling for this pool. When this property is set to `true` both PreparedStatements and CallableStatements are pooled.

    - #### maxOpenPreparedStatements

          protected int maxOpenPreparedStatements

      The maximum number of open statements that can be allocated from the statement pool at the same time, or non-positive for no limit. Since a connection usually only uses one or two statements at a time, this is mostly used to help detect resource leaks.

      Note: As of version 1.3, CallableStatements (those produced by `Connection.prepareCall(java.lang.String)`) are pooled along with PreparedStatements (produced by `Connection.prepareStatement(java.lang.String)`) and `maxOpenPreparedStatements` limits the total number of prepared or callable statements that may be in use at a given time.

    - #### testOnBorrow

          protected boolean testOnBorrow

      The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

    - #### testOnReturn

          protected boolean testOnReturn

      The indication of whether objects will be validated before being returned to the pool.

    - #### timeBetweenEvictionRunsMillis

          protected long timeBetweenEvictionRunsMillis

      The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

    - #### numTestsPerEvictionRun

          protected int numTestsPerEvictionRun

      The number of objects to examine during each run of the idle object evictor thread (if any).

    - #### minEvictableIdleTimeMillis

          protected long minEvictableIdleTimeMillis

      The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).

    - #### testWhileIdle

          protected boolean testWhileIdle

      The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

    - #### password

          protected volatile String password

      The connection password to be passed to our JDBC driver to establish a connection.

    - #### url

          protected String url

      The connection URL to be passed to our JDBC driver to establish a connection.

    - #### username

          protected String username

      The connection username to be passed to our JDBC driver to establish a connection.

    - #### validationQuery

          protected volatile String validationQuery

      The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row.

    - #### validationQueryTimeout

          protected volatile int validationQueryTimeout

      Timeout in seconds before connection validation queries fail.
      Since:
        1.3

    - #### connectionInitSqls

          protected volatile List<String> connectionInitSqls

      These SQL statements run once after a Connection is created.

      This property can be used for example to run ALTER SESSION SET NLS_SORT=XCYECH in an Oracle Database only once after connection creation.

      Since:
        1.3

    - #### connectionPool

          protected volatile GenericObjectPool<PoolableConnection> connectionPool

      The object pool that internally manages our connections.

    - #### connectionProperties

          protected Properties connectionProperties

      The connection properties that will be sent to our JDBC driver when establishing new connections. NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.

    - #### dataSource

          protected volatile DataSource dataSource

      The data source we will use to manage connections. This object should be acquired ONLY by calls to the `createDataSource()` method.

    - #### logWriter

          protected PrintWriter logWriter

      The PrintWriter to which log messages should be directed.

    - #### closed

          protected boolean closed

  - ### Constructor Detail

    - #### BasicDataSource

          public BasicDataSource()

  - ### Method Detail

    - #### getDefaultAutoCommit

          public boolean getDefaultAutoCommit()

      Returns the default auto-commit property.
      Returns:
        true if default auto-commit is enabled

    - #### setDefaultAutoCommit

          public void setDefaultAutoCommit(boolean defaultAutoCommit)

      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.`

      Parameters:
        `defaultAutoCommit` - default auto-commit value

    - #### getDefaultReadOnly

          public boolean getDefaultReadOnly()

      Returns the default readOnly property.
      Returns:
        true if connections are readOnly by default

    - #### setDefaultReadOnly

          public void setDefaultReadOnly(boolean defaultReadOnly)

      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.`

      Parameters:
        `defaultReadOnly` - default read-only value

    - #### getDefaultTransactionIsolation

          public int getDefaultTransactionIsolation()

      Returns the default transaction isolation state of returned connections.
      Returns:
        the default value for transaction isolation state
      See Also:
        `Connection.getTransactionIsolation()`

    - #### setDefaultTransactionIsolation

          public void setDefaultTransactionIsolation(int defaultTransactionIsolation)

      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.`

      Parameters:
        `defaultTransactionIsolation` - the default transaction isolation state
      See Also:
        `Connection.getTransactionIsolation()`

    - #### getDefaultCatalog

          public String getDefaultCatalog()

      Returns the default catalog.
      Returns:
        the default catalog

    - #### setDefaultCatalog

          public void setDefaultCatalog(String defaultCatalog)

      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.`

      Parameters:
        `defaultCatalog` - the default catalog

    - #### getDriverClassName

          public String getDriverClassName()

      Returns the JDBC driver class name.
      Returns:
        the JDBC driver class name

    - #### setDriverClassName

          public void setDriverClassName(String driverClassName)

      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.`

      Parameters:
        `driverClassName` - the class name of the JDBC driver

    - #### getDriverClassLoader

          public ClassLoader getDriverClassLoader()

      Returns the class loader specified for loading the JDBC driver. Returns `null` if no class loader has been explicitly specified.

    - #### setDriverClassLoader

          public void setDriverClassLoader(ClassLoader driverClassLoader)

      Sets the class loader to be used to load the JDBC driver.

      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.`

      Parameters:
        `driverClassLoader` - the class loader with which to load the JDBC driver

    - #### getLifo

          public boolean getLifo()

      Returns the LIFO property.
      Returns:
        true if connection pool behaves as a LIFO queue.
      See Also:
        `lifo`

    - #### setLifo

          public void setLifo(boolean lifo)

      Sets the LIFO property. True means the pool behaves as a LIFO queue; false means FIFO.
      Parameters:
        `lifo` - the new value for the LIFO property

    - #### getMaxActive

          public int getMaxActive()

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

      A negative number means that there is no limit.

      Returns:
        the maximum number of active connections

    - #### setMaxActive

          public void setMaxActive(int maxActive)

      Sets the maximum number of active connections that can be allocated at the same time. Use a negative value for no limit.
      Parameters:
        `maxActive` - the new value for maxActive
      See Also:
        `getMaxActive()`

    - #### getMaxIdle

          public int getMaxIdle()

      Returns the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed on return to the pool.

      A negative value indicates that there is no limit

      Returns:
        the maximum number of idle connections

    - #### setMaxIdle

          public void setMaxIdle(int maxIdle)

      Sets the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed on return to the pool.
      Parameters:
        `maxIdle` - the new value for maxIdle
      See Also:
        `getMaxIdle()`

    - #### getMinIdle

          public int getMinIdle()

      Returns the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections are available when the idle object evictor runs. The value of this property has no effect unless `timeBetweenEvictionRunsMillis` has a positive value.
      Returns:
        the minimum number of idle connections
      See Also:
        `GenericObjectPool.getMinIdle()`

    - #### setMinIdle

          public void setMinIdle(int minIdle)

      Sets the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections are available when the idle object evictor runs. The value of this property has no effect unless `timeBetweenEvictionRunsMillis` has a positive value.
      Parameters:
        `minIdle` - the new value for minIdle
      See Also:
        `GenericObjectPool.setMinIdle(int)`

    - #### getInitialSize

          public int getInitialSize()

      Returns the initial size of the connection pool.
      Returns:
        the number of connections created when the pool is initialized

    - #### setInitialSize

          public void setInitialSize(int initialSize)

      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.`

      Parameters:
        `initialSize` - the number of connections created when the pool is initialized

    - #### getMaxWait

          public long getMaxWait()

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

      A value less than or equal to zero means the pool is set to wait indefinitely.

      Returns:
        the maxWait property value

    - #### setMaxWait

          public void setMaxWait(long maxWait)

      Sets the maxWait property.

      Use -1 to make the pool wait indefinitely.

      Parameters:
        `maxWait` - the new value for maxWait
      See Also:
        `getMaxWait()`

    - #### isPoolPreparedStatements

          public boolean isPoolPreparedStatements()

      Returns true if we are pooling statements.
      Returns:
        true if prepared and callable statements are pooled

    - #### setPoolPreparedStatements

          public void setPoolPreparedStatements(boolean poolingStatements)

      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.`

      Parameters:
        `poolingStatements` - pooling on or off

    - #### getMaxOpenPreparedStatements

          public int getMaxOpenPreparedStatements()

      Gets the value of the `maxOpenPreparedStatements` property.
      Returns:
        the maximum number of open statements
      See Also:
        `maxOpenPreparedStatements`

    - #### setMaxOpenPreparedStatements

          public void setMaxOpenPreparedStatements(int maxOpenStatements)

      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.`

      Parameters:
        `maxOpenStatements` - the new maximum number of prepared statements
      See Also:
        `maxOpenPreparedStatements`

    - #### getTestOnBorrow

          public boolean getTestOnBorrow()

      Returns the `testOnBorrow` property.
      Returns:
        true if objects are validated before being borrowed from the pool
      See Also:
        `testOnBorrow`

    - #### setTestOnBorrow

          public void setTestOnBorrow(boolean 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.
      Parameters:
        `testOnBorrow` - new value for testOnBorrow property

    - #### getTestOnReturn

          public boolean getTestOnReturn()

      Returns the value of the `testOnReturn` property.
      Returns:
        true if objects are validated before being returned to the pool
      See Also:
        `testOnReturn`

    - #### setTestOnReturn

          public void setTestOnReturn(boolean 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.
      Parameters:
        `testOnReturn` - new value for testOnReturn property

    - #### getTimeBetweenEvictionRunsMillis

          public long getTimeBetweenEvictionRunsMillis()

      Returns the value of the `timeBetweenEvictionRunsMillis` property.
      Returns:
        the time (in milliseconds) between evictor runs
      See Also:
        `timeBetweenEvictionRunsMillis`

    - #### setTimeBetweenEvictionRunsMillis

          public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

      Sets the `timeBetweenEvictionRunsMillis` property.
      Parameters:
        `timeBetweenEvictionRunsMillis` - the new time between evictor runs
      See Also:
        `timeBetweenEvictionRunsMillis`

    - #### getNumTestsPerEvictionRun

          public int getNumTestsPerEvictionRun()

      Returns the value of the `numTestsPerEvictionRun` property.
      Returns:
        the number of objects to examine during idle object evictor runs
      See Also:
        `numTestsPerEvictionRun`

    - #### setNumTestsPerEvictionRun

          public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

      Sets the value of the `numTestsPerEvictionRun` property.
      Parameters:
        `numTestsPerEvictionRun` - the new `numTestsPerEvictionRun` value
      See Also:
        `numTestsPerEvictionRun`

    - #### getMinEvictableIdleTimeMillis

          public long getMinEvictableIdleTimeMillis()

      Returns the `minEvictableIdleTimeMillis` property.
      Returns:
        the value of the `minEvictableIdleTimeMillis` property
      See Also:
        `minEvictableIdleTimeMillis`

    - #### setMinEvictableIdleTimeMillis

          public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

      Sets the `minEvictableIdleTimeMillis` property.
      Parameters:
        `minEvictableIdleTimeMillis` - the minimum amount of time an object may sit idle in the pool
      See Also:
        `minEvictableIdleTimeMillis`

    - #### setSoftMinEvictableIdleTimeMillis

          public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)

      Sets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.
      Parameters:
        `softMinEvictableIdleTimeMillis` - minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool.
      Since:
        1.4.1
      See Also:
        `getSoftMinEvictableIdleTimeMillis()`

    - #### getSoftMinEvictableIdleTimeMillis

          public long getSoftMinEvictableIdleTimeMillis()

      Returns the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.

      When `miniEvictableIdleTimeMillis` is set to a positive value, miniEvictableIdleTimeMillis is examined first by the idle connection evictor - i.e. when idle connections are visited by the evictor, idle time is first compared against `minEvictableIdleTimeMillis` (without considering the number of idle connections in the pool) and then against `softMinEvictableIdleTimeMillis`, including the `minIdle`, constraint.

      Returns:
        minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool
      Since:
        1.4.1

    - #### getTestWhileIdle

          public boolean getTestWhileIdle()

      Returns the value of the `testWhileIdle` property.
      Returns:
        true if objects examined by the idle object evictor are validated
      See Also:
        `testWhileIdle`

    - #### setTestWhileIdle

          public void setTestWhileIdle(boolean 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.
      Parameters:
        `testWhileIdle` - new value for testWhileIdle property

    - #### getNumActive

          public int getNumActive()

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

    - #### getNumIdle

          public int getNumIdle()

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

    - #### getPassword

          public String getPassword()

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

    - #### setPassword

          public void setPassword(String password)

      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.`

      Parameters:
        `password` - new value for the password

    - #### getUrl

          public String getUrl()

      Returns the JDBC connection `url` property.
      Returns:
        the `url` passed to the JDBC driver to establish connections

    - #### setUrl

          public void setUrl(String url)

      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.`

      Parameters:
        `url` - the new value for the JDBC connection url

    - #### getUsername

          public String getUsername()

      Returns the JDBC connection `username` property.
      Returns:
        the `username` passed to the JDBC driver to establish connections

    - #### setUsername

          public void setUsername(String username)

      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.`

      Parameters:
        `username` - the new value for the JDBC connection username

    - #### getValidationQuery

          public String getValidationQuery()

      Returns the validation query used to validate connections before returning them.
      Returns:
        the SQL validation query
      See Also:
        `validationQuery`

    - #### setValidationQuery

          public void setValidationQuery(String validationQuery)

      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.`

      Parameters:
        `validationQuery` - the new value for the validation query

    - #### getValidationQueryTimeout

          public int getValidationQueryTimeout()

      Returns the validation query timeout.
      Returns:
        the timeout in seconds before connection validation queries fail.
      Since:
        1.3

    - #### setValidationQueryTimeout

          public void setValidationQueryTimeout(int timeout)

      Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.

      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.`

      Parameters:
        `timeout` - new validation query timeout value in seconds
      Since:
        1.3

    - #### getConnectionInitSqls

          public Collection<String> getConnectionInitSqls()

      Returns the list of SQL statements executed when a physical connection is first created. Returns an empty list if there are no initialization statements configured.
      Returns:
        initialization SQL statements
      Since:
        1.3

    - #### setConnectionInitSqls

          public void setConnectionInitSqls(Collection<String> connectionInitSqls)

      Sets the list of SQL statements to be executed when a physical connection is first created.

      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.`

      Parameters:
        `connectionInitSqls` - Collection of SQL statements to execute on connection creation

    - #### isAccessToUnderlyingConnectionAllowed

          public boolean isAccessToUnderlyingConnectionAllowed()

      Returns the value of the accessToUnderlyingConnectionAllowed property.
      Returns:
        true if access to the underlying connection is allowed, false otherwise.

    - #### setAccessToUnderlyingConnectionAllowed

          public void setAccessToUnderlyingConnectionAllowed(boolean allow)

      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.`

      Parameters:
        `allow` - Access to the underlying connection is granted when true.

    - #### getConnection

          public Connection getConnection()
                                   throws SQLException

      Create (if necessary) and return a connection to the database.
      Specified by:
        `getConnection` in interface `DataSource`
      Returns:
        a database connection
      Throws:
        `SQLException` - if a database access error occurs

    - #### getConnection

          public Connection getConnection(String user,
                                 String pass)
                                   throws SQLException

      BasicDataSource does NOT support this method.
      Specified by:
        `getConnection` in interface `DataSource`
      Parameters:
        `user` - Database user on whose behalf the Connection is being made
        `pass` - The database user's password
      Returns:
        nothing - always throws UnsupportedOperationException
      Throws:
        `UnsupportedOperationException`
        `SQLException` - if a database access error occurs

    - #### getLoginTimeout

          public int getLoginTimeout()
                              throws SQLException

      BasicDataSource does NOT support this method.

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

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

      Specified by:
        `getLoginTimeout` in interface `CommonDataSource`
      Returns:
        login timeout in seconds
      Throws:
        `SQLException` - if a database access error occurs
        `UnsupportedOperationException` - If the DataSource implementation does not support the login timeout feature.

    - #### getLogWriter

          public PrintWriter getLogWriter()
                                   throws SQLException

      Returns the log writer being used by this data source.

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

      Specified by:
        `getLogWriter` in interface `CommonDataSource`
      Returns:
        log writer in use
      Throws:
        `SQLException` - if a database access error occurs

    - #### setLoginTimeout

          public void setLoginTimeout(int loginTimeout)
                               throws SQLException

      BasicDataSource does NOT support this method.

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

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

      Specified by:
        `setLoginTimeout` in interface `CommonDataSource`
      Parameters:
        `loginTimeout` - The new login timeout, or zero for no timeout
      Throws:
        `UnsupportedOperationException` - If the DataSource implementation does not support the login timeout feature.
        `SQLException` - if a database access error occurs

    - #### setLogWriter

          public void setLogWriter(PrintWriter logWriter)
                            throws SQLException

      Sets the log writer being used by this data source.

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

      Specified by:
        `setLogWriter` in interface `CommonDataSource`
      Parameters:
        `logWriter` - The new log writer
      Throws:
        `SQLException` - if a database access error occurs

    - #### getRemoveAbandoned

          public boolean getRemoveAbandoned()

      Flag to remove abandoned connections if they exceed the removeAbandonedTimout.

      The default value is false.

      If set to true a connection is considered abandoned and eligible for removal if it has not been used for more than `removeAbandonedTimeout` seconds.

      Abandoned connections are identified and removed when `getConnection()` is invoked and the following conditions hold

      - `getRemoveAbandoned()` = true
      - `getNumActive()` > `getMaxActive()` - 3
      - `getNumIdle()` < 2
      See Also:
        `getRemoveAbandonedTimeout()`

    - #### setRemoveAbandoned

          public void setRemoveAbandoned(boolean removeAbandoned)

      Flag to remove abandoned connections if they exceed the removeAbandonedTimeout.

      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.

      Parameters:
        `removeAbandoned` - true means abandoned connections will be removed
      See Also:
        `getRemoveAbandoned()`

    - #### getRemoveAbandonedTimeout

          public int getRemoveAbandonedTimeout()

      Timeout in seconds before an abandoned connection can be removed.

      Creating a Statement, PreparedStatement or CallableStatement or using one of these to execute a query (using one of the execute methods) resets the lastUsed property of the parent connection.

      Abandoned connection cleanup happens when

      - `removeAbandoned` == true
      - `numIdle` < 2
      - `numActive` > `maxActive` - 3

      The default value is 300 seconds.

    - #### setRemoveAbandonedTimeout

          public void setRemoveAbandonedTimeout(int removeAbandonedTimeout)

      Sets the timeout in seconds before an abandoned connection can be removed.

      Setting this property has no effect if `removeAbandoned` is false.

      Parameters:
        `removeAbandonedTimeout` - new abandoned timeout in seconds
      See Also:
        `getRemoveAbandonedTimeout()`, `getRemoveAbandoned()`

    - #### getLogAbandoned

          public boolean getLogAbandoned()

      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.

    - #### setLogAbandoned

          public void setLogAbandoned(boolean logAbandoned)

      Parameters:
        `logAbandoned` - new logAbandoned property value

    - #### addConnectionProperty

          public void addConnectionProperty(String name,
                                   String value)

      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.
      Parameters:
        `name` - Name of the custom connection property
        `value` - Value of the custom connection property

    - #### removeConnectionProperty

          public void removeConnectionProperty(String name)

      Remove a custom connection property.
      Parameters:
        `name` - Name of the custom connection property to remove
      See Also:
        `addConnectionProperty(String, String)`

    - #### setConnectionProperties

          public void setConnectionProperties(String connectionProperties)

      Sets the connection properties passed to driver.connect(...). Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be added explicitly, so they do not need to be included here.
      Parameters:
        `connectionProperties` - the connection properties used to create new connections

    - #### close

          public void close()
                     throws SQLException

      Closes and releases all idle connections that are currently stored in the connection pool associated with this data source.

      Connections that are checked out to clients when this method is invoked are not affected. When client applications subsequently invoke `Connection.close()` to return these connections to the pool, the underlying JDBC connections are closed.

      Attempts to acquire connections using `getConnection()` after this method has been invoked result in SQLExceptions.

      This method is idempotent - i.e., closing an already closed BasicDataSource has no effect and does not generate exceptions.

      Throws:
        `SQLException` - if an error occurs closing idle connections

    - #### isClosed

          public boolean isClosed()

      If true, this data source is closed and no more connections can be retrieved from this datasource.
      Returns:
        true, if the data source is closed; false otherwise

    - #### isWrapperFor

          public boolean isWrapperFor(Class<?> iface)
                               throws SQLException

      Specified by:
        `isWrapperFor` in interface `Wrapper`
      Throws:
        `SQLException`

    - #### unwrap

          public <T> T unwrap(Class<T> iface)
                   throws SQLException

      Specified by:
        `unwrap` in interface `Wrapper`
      Throws:
        `SQLException`

    - #### getParentLogger

          public Logger getParentLogger()
                                 throws SQLFeatureNotSupportedException

      Specified by:
        `getParentLogger` in interface `CommonDataSource`
      Throws:
        `SQLFeatureNotSupportedException`

    - #### createDataSource

          protected DataSource createDataSource()
                                         throws SQLException

      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.

      Throws:
        `SQLException` - if the object pool cannot be created.

    - #### createConnectionFactory

          protected ConnectionFactory createConnectionFactory()
                                                       throws SQLException

      Creates a JDBC connection factory for this datasource. The JDBC driver is loaded using the following algorithm:
      1. If `driverClassName` is specified that class is loaded using the `ClassLoader` of this class or, if `driverClassLoader` is set, `driverClassName` is loaded with the specified `ClassLoader`.
      2. If `driverClassName` is specified and the previous attempt fails, the class is loaded using the context class loader of the current thread.
      3. If a driver still isn't loaded one is loaded via the `DriverManager` using the specified `url`.
      This method exists so subclasses can replace the implementation class.
      Throws:
        `SQLException`

    - #### createConnectionPool

          protected void createConnectionPool()

      Creates a connection pool for this datasource. This method only exists so subclasses can replace the implementation class. This implementation configures all pool properties other than timeBetweenEvictionRunsMillis. Setting that property is deferred to `startPoolMaintenance()`, since setting timeBetweenEvictionRunsMillis to a positive value causes `GenericObjectPool`'s eviction timer to be started.

    - #### startPoolMaintenance

          protected void startPoolMaintenance()

      Starts the connection pool maintenance task, if configured.

    - #### createDataSourceInstance

          protected void createDataSourceInstance()
                                           throws SQLException

      Creates the actual data source instance. This method only exists so that subclasses can replace the implementation class.
      Throws:
        `SQLException` - if unable to create a datasource instance

    - #### createPoolableConnectionFactory

          protected void createPoolableConnectionFactory(ConnectionFactory driverConnectionFactory,
                                             KeyedObjectPoolFactory<PStmtKey,DelegatingPreparedStatement> statementPoolFactory,
                                             AbandonedConfig configuration)
                                                  throws SQLException

      Creates the PoolableConnectionFactory and attaches it to the connection pool. This method only exists so subclasses can replace the default implementation.
      Parameters:
        `driverConnectionFactory` - JDBC connection factory
        `statementPoolFactory` - statement pool factory (null if statement pooling is turned off)
        `configuration` - abandoned connection tracking configuration (null if no tracking)
      Throws:
        `SQLException` - if an error occurs creating the PoolableConnectionFactory

    - #### validateConnectionFactory

          protected static void validateConnectionFactory(PoolableConnectionFactory connectionFactory)
                                                   throws Exception

      Throws:
        `Exception`

    - #### log

          protected void log(String message)

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.