Package org.apache.commons.dbcp2.datasources

# Class InstanceKeyDataSource

java.lang.Object
org.apache.commons.dbcp2.datasources.InstanceKeyDataSource

All Implemented Interfaces:
  `Serializable`, `AutoCloseable`, `Wrapper`, `Referenceable`, `CommonDataSource`, `DataSource`

Direct Known Subclasses:
  `PerUserPoolDataSource`, `SharedPoolDataSource`

public abstract class InstanceKeyDataSource extends Object implements DataSource, Referenceable, Serializable, AutoCloseable

The base class for `SharedPoolDataSource` and `PerUserPoolDataSource`. Many of the configuration properties are shared and defined here. This class is declared public in order to allow particular usage with commons-beanutils; do not make direct use of it outside of commons-dbcp2.

A J2EE container will normally provide some method of initializing the `DataSource` whose attributes are presented as bean getters/setters and then deploying it via JNDI. It is then available to an application as a source of pooled logical connections to the database. The pool needs a source of physical connections. This source is in the form of a `ConnectionPoolDataSource` that can be specified via the `setDataSourceName(String)` used to lookup the source via JNDI.

Although normally used within a JNDI environment, A DataSource can be instantiated and initialized as any bean. In this case the `ConnectionPoolDataSource` will likely be instantiated in a similar manner. This class allows the physical source of connections to be attached directly to this pool using the `setConnectionPoolDataSource(ConnectionPoolDataSource)` method.

The dbcp package contains an adapter, `DriverAdapterCPDS`, that can be used to allow the use of `DataSource`'s based on this class with JDBC driver implementations that do not supply a `ConnectionPoolDataSource`, but still provide a `Driver` implementation.

The package documentation contains an example using Apache Tomcat and JNDI and it also contains a non-JNDI example.

Since:
  2.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final int`
  `UNKNOWN_TRANSACTIONISOLATION`
  Internal constant to indicate the level is not set.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InstanceKeyDataSource()`
  Default no-arg constructor for Serialization.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `assertInitializationAllowed()`
  Throws an IllegalStateException, if a PooledConnection has already been requested.
  `abstract void`
  `close()`
  Closes the connection pool being maintained by this datasource.
  `Connection`
  `getConnection()`
  Attempts to establish a database connection.
  `Connection`
  `getConnection(String userName, String userPassword)`
  Attempts to retrieve a database connection using `getPooledConnectionAndInfo(String, String)` with the provided user name and password.
  `protected abstract org.apache.commons.dbcp2.datasources.PooledConnectionManager`
  `getConnectionManager(org.apache.commons.dbcp2.datasources.UserPassKey upkey)`
  Gets the pooled connection manager for the given key.
  `ConnectionPoolDataSource`
  `getConnectionPoolDataSource()`
  Gets the value of connectionPoolDataSource.
  `String`
  `getDataSourceName()`
  Gets the name of the ConnectionPoolDataSource which backs this pool.
  `boolean`
  `getDefaultBlockWhenExhausted()`
  Gets the default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.
  `Duration`
  `getDefaultDurationBetweenEvictionRuns()`
  Gets the default value for `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` for each per user pool.
  `String`
  `getDefaultEvictionPolicyClassName()`
  Gets the default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.
  `boolean`
  `getDefaultLifo()`
  Gets the default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.
  `int`
  `getDefaultMaxIdle()`
  Gets the default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.
  `int`
  `getDefaultMaxTotal()`
  Gets the default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.
  `Duration`
  `getDefaultMaxWait()`
  Gets the default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
  `long`
  `getDefaultMaxWaitMillis()`
  Deprecated.
  Use `getDefaultMaxWait()`.
  `Duration`
  `getDefaultMinEvictableIdleDuration()`
  Gets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
  `long`
  `getDefaultMinEvictableIdleTimeMillis()`
  Deprecated.
  Use `getDefaultMinEvictableIdleDuration()`.
  `int`
  `getDefaultMinIdle()`
  Gets the default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.
  `int`
  `getDefaultNumTestsPerEvictionRun()`
  Gets the default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.
  `Duration`
  `getDefaultSoftMinEvictableIdleDuration()`
  Gets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
  `long`
  `getDefaultSoftMinEvictableIdleTimeMillis()`
  Deprecated.
  Use `getDefaultSoftMinEvictableIdleDuration()`.
  `boolean`
  `getDefaultTestOnBorrow()`
  Gets the default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.
  `boolean`
  `getDefaultTestOnCreate()`
  Gets the default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.
  `boolean`
  `getDefaultTestOnReturn()`
  Gets the default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.
  `boolean`
  `getDefaultTestWhileIdle()`
  Gets the default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.
  `long`
  `getDefaultTimeBetweenEvictionRunsMillis()`
  Deprecated.
  Use `getDefaultDurationBetweenEvictionRuns()`.
  `int`
  `getDefaultTransactionIsolation()`
  Gets the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.
  `String`
  `getDescription()`
  Gets the description.
  `protected String`
  `getInstanceKey()`
  Gets the instance key.
  `String`
  `getJndiEnvironment(String key)`
  Gets the value of jndiEnvironment which is used when instantiating a JNDI InitialContext.
  `int`
  `getLoginTimeout()`
  Deprecated.
  Use `getLoginTimeoutDuration()`.
  `Duration`
  `getLoginTimeoutDuration()`
  Gets the value of loginTimeout.
  `PrintWriter`
  `getLogWriter()`
  Gets the value of logWriter.
  `Duration`
  `getMaxConnDuration()`
  Gets the maximum permitted lifetime of a connection.
  `Duration`
  `getMaxConnLifetime()`
  Deprecated.
  Use `getMaxConnDuration()`.
  `long`
  `getMaxConnLifetimeMillis()`
  Deprecated.
  Use `getMaxConnLifetime()`.
  `Logger`
  `getParentLogger()`
  `protected abstract org.apache.commons.dbcp2.datasources.PooledConnectionAndInfo`
  `getPooledConnectionAndInfo(String userName, String userPassword)`
  This method is protected but can only be implemented in this package because PooledConnectionAndInfo is a package private type.
  `String`
  `getValidationQuery()`
  Gets the SQL query that will be used to validate connections from this pool before returning them to the caller.
  `int`
  `getValidationQueryTimeout()`
  Deprecated.
  Use `getValidationQueryTimeoutDuration()`.
  `Duration`
  `getValidationQueryTimeoutDuration()`
  Returns the timeout Duration before the validation query fails.
  `Boolean`
  `isDefaultAutoCommit()`
  Gets the value of defaultAutoCommit, which defines the state of connections handed out from this pool.
  `Boolean`
  `isDefaultReadOnly()`
  Gets the value of defaultReadOnly, which defines the state of connections handed out from this pool.
  `boolean`
  `isRollbackAfterValidation()`
  Tests whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.
  `boolean`
  `isWrapperFor(Class<?> iface)`
  `void`
  `setConnectionPoolDataSource(ConnectionPoolDataSource dataSource)`
  Sets the back end ConnectionPoolDataSource.
  `void`
  `setDataSourceName(String dataSourceName)`
  Sets the name of the ConnectionPoolDataSource which backs this pool.
  `void`
  `setDefaultAutoCommit(Boolean defaultAutoCommit)`
  Sets the value of defaultAutoCommit, which defines the state of connections handed out from this pool.
  `void`
  `setDefaultBlockWhenExhausted(boolean blockWhenExhausted)`
  Sets the default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.
  `void`
  `setDefaultDurationBetweenEvictionRuns(Duration defaultDurationBetweenEvictionRuns)`
  Sets the default value for `()` for each per user pool.
  `void`
  `setDefaultEvictionPolicyClassName(String evictionPolicyClassName)`
  Sets the default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.
  `void`
  `setDefaultLifo(boolean lifo)`
  Sets the default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.
  `void`
  `setDefaultMaxIdle(int maxIdle)`
  Sets the default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.
  `void`
  `setDefaultMaxTotal(int maxTotal)`
  Sets the default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.
  `void`
  `setDefaultMaxWait(Duration maxWaitMillis)`
  Sets the default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
  `void`
  `setDefaultMaxWaitMillis(long maxWaitMillis)`
  Deprecated.
  Use `setDefaultMaxWait(Duration)`.
  `void`
  `setDefaultMinEvictableIdle(Duration defaultMinEvictableIdleDuration)`
  Sets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
  `void`
  `setDefaultMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)`
  Deprecated.
  Use `setDefaultMinEvictableIdle(Duration)`.
  `void`
  `setDefaultMinIdle(int minIdle)`
  Sets the default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.
  `void`
  `setDefaultNumTestsPerEvictionRun(int numTestsPerEvictionRun)`
  Sets the default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.
  `void`
  `setDefaultReadOnly(Boolean defaultReadOnly)`
  Sets the value of defaultReadOnly, which defines the state of connections handed out from this pool.
  `void`
  `setDefaultSoftMinEvictableIdle(Duration defaultSoftMinEvictableIdleDuration)`
  Sets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
  `void`
  `setDefaultSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)`
  Deprecated.
  Use `setDefaultSoftMinEvictableIdle(Duration)`.
  `void`
  `setDefaultTestOnBorrow(boolean testOnBorrow)`
  Sets the default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.
  `void`
  `setDefaultTestOnCreate(boolean testOnCreate)`
  Sets the default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.
  `void`
  `setDefaultTestOnReturn(boolean testOnReturn)`
  Sets the default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.
  `void`
  `setDefaultTestWhileIdle(boolean testWhileIdle)`
  Sets the default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.
  `void`
  `setDefaultTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)`
  Deprecated.
  Use `setDefaultDurationBetweenEvictionRuns(Duration)`.
  `void`
  `setDefaultTransactionIsolation(int defaultTransactionIsolation)`
  Sets the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.
  `void`
  `setDescription(String description)`
  Sets the description.
  `void`
  `setJndiEnvironment(String key, String value)`
  Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext.
  `void`
  `setLoginTimeout(int loginTimeout)`
  Deprecated.
  Use `setLoginTimeout(Duration)`.
  `void`
  `setLoginTimeout(Duration loginTimeout)`
  Sets the value of loginTimeout.
  `void`
  `setLogWriter(PrintWriter logWriter)`
  Sets the value of logWriter.
  `void`
  `setMaxConnLifetime(Duration maxConnLifetimeMillis)`
  Sets the maximum permitted lifetime of a connection.
  `void`
  `setMaxConnLifetimeMillis(long maxConnLifetimeMillis)`
  Deprecated.
  Use `setMaxConnLifetime(Duration)`.
  `void`
  `setRollbackAfterValidation(boolean rollbackAfterValidation)`
  Sets whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.
  `protected abstract void`
  `setupDefaults(Connection connection, String userName)`
  Sets up the defaults for a given connection.
  `void`
  `setValidationQuery(String validationQuery)`
  Sets the SQL query that will be used to validate connections from this pool before returning them to the caller.
  `void`
  `setValidationQueryTimeout(int validationQueryTimeoutSeconds)`
  Deprecated.
  Use `setValidationQueryTimeout(Duration)`.
  `void`
  `setValidationQueryTimeout(Duration validationQueryTimeoutDuration)`
  Sets the timeout duration before the validation query fails.
  `protected ConnectionPoolDataSource`
  `testCPDS(String userName, String userPassword)`
  Tests and returns whether a JNDI context can be created to lookup a ConnectionPoolDataSource to then access a PooledConnection connection.
  `String`
  `toString()`
  `protected void`
  `toStringFields(StringBuilder builder)`
  Appends this instance's fields to a string builder.
  `<T> T`
  `unwrap(Class<T> iface)`

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

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

  ### Methods inherited from interface javax.naming.Referenceable

  `getReference`

- ## Field Details

  - ### UNKNOWN_TRANSACTIONISOLATION

    protected static final int UNKNOWN_TRANSACTIONISOLATION
    Internal constant to indicate the level is not set.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### InstanceKeyDataSource

    public InstanceKeyDataSource()
    Default no-arg constructor for Serialization.

- ## Method Details

  - ### assertInitializationAllowed

    protected void assertInitializationAllowed() throws IllegalStateException
    Throws an IllegalStateException, if a PooledConnection has already been requested.
    Throws:
      `IllegalStateException` - Thrown if a PooledConnection has already been requested.

  - ### close

    public abstract void close() throws SQLException
    Closes the connection pool being maintained by this datasource.
    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `SQLException`

  - ### getConnection

    public Connection getConnection() throws SQLException
    Attempts to establish a database connection.
    Specified by:
      `getConnection` in interface `DataSource`
    Throws:
      `SQLException`

  - ### getConnection

    public Connection getConnection(String userName, String userPassword) throws SQLException
    Attempts to retrieve a database connection using `getPooledConnectionAndInfo(String, String)` with the provided user name and password. The password on the `PooledConnectionAndInfo` instance returned by `getPooledConnectionAndInfo` is compared to the `password` parameter. If the comparison fails, a database connection using the supplied user name and password is attempted. If the connection attempt fails, an SQLException is thrown, indicating that the given password did not match the password used to create the pooled connection. If the connection attempt succeeds, this means that the database password has been changed. In this case, the `PooledConnectionAndInfo` instance retrieved with the old password is destroyed and the `getPooledConnectionAndInfo` is repeatedly invoked until a `PooledConnectionAndInfo` instance with the new password is returned.
    Specified by:
      `getConnection` in interface `DataSource`
    Throws:
      `SQLException`

  - ### getConnectionManager

    protected abstract org.apache.commons.dbcp2.datasources.PooledConnectionManager getConnectionManager(org.apache.commons.dbcp2.datasources.UserPassKey upkey)
    Gets the pooled connection manager for the given key.
    Parameters:
      `upkey` - the key.
    Returns:
      the pooled connection manager for the given key.

  - ### getConnectionPoolDataSource

    public ConnectionPoolDataSource getConnectionPoolDataSource()
    Gets the value of connectionPoolDataSource. This method will return null, if the backing data source is being accessed via JNDI.
    Returns:
      value of connectionPoolDataSource.

  - ### getDataSourceName

    public String getDataSourceName()
    Gets the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the data source from a JNDI service provider.
    Returns:
      value of dataSourceName.

  - ### getDefaultBlockWhenExhausted

    public boolean getDefaultBlockWhenExhausted()
    Gets the default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.

  - ### getDefaultDurationBetweenEvictionRuns

    public Duration getDefaultDurationBetweenEvictionRuns()
    Gets the default value for `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` for each per user pool.
    Since:
      2.10.0

  - ### getDefaultEvictionPolicyClassName

    public String getDefaultEvictionPolicyClassName()
    Gets the default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.

  - ### getDefaultLifo

    public boolean getDefaultLifo()
    Gets the default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.

  - ### getDefaultMaxIdle

    public int getDefaultMaxIdle()
    Gets the default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.
    Returns:
      The default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.

  - ### getDefaultMaxTotal

    public int getDefaultMaxTotal()
    Gets the default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.
    Returns:
      The default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.

  - ### getDefaultMaxWait

    public Duration getDefaultMaxWait()
    Gets the default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
    Since:
      2.9.0

  - ### getDefaultMaxWaitMillis

    @Deprecated public long getDefaultMaxWaitMillis()
    Deprecated.
    Use `getDefaultMaxWait()`.
    Gets the default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.

  - ### getDefaultMinEvictableIdleDuration

    public Duration getDefaultMinEvictableIdleDuration()
    Gets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Since:
      2.10.0

  - ### getDefaultMinEvictableIdleTimeMillis

    @Deprecated public long getDefaultMinEvictableIdleTimeMillis()
    Deprecated.
    Use `getDefaultMinEvictableIdleDuration()`.
    Gets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.

  - ### getDefaultMinIdle

    public int getDefaultMinIdle()
    Gets the default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.
    Returns:
      The default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.

  - ### getDefaultNumTestsPerEvictionRun

    public int getDefaultNumTestsPerEvictionRun()
    Gets the default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.
    Returns:
      The default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.

  - ### getDefaultSoftMinEvictableIdleDuration

    public Duration getDefaultSoftMinEvictableIdleDuration()
    Gets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Since:
      2.10.0

  - ### getDefaultSoftMinEvictableIdleTimeMillis

    @Deprecated public long getDefaultSoftMinEvictableIdleTimeMillis()
    Deprecated.
    Use `getDefaultSoftMinEvictableIdleDuration()`.
    Gets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.

  - ### getDefaultTestOnBorrow

    public boolean getDefaultTestOnBorrow()
    Gets the default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.

  - ### getDefaultTestOnCreate

    public boolean getDefaultTestOnCreate()
    Gets the default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.

  - ### getDefaultTestOnReturn

    public boolean getDefaultTestOnReturn()
    Gets the default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.

  - ### getDefaultTestWhileIdle

    public boolean getDefaultTestWhileIdle()
    Gets the default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.
    Returns:
      The default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.

  - ### getDefaultTimeBetweenEvictionRunsMillis

    @Deprecated public long getDefaultTimeBetweenEvictionRunsMillis()
    Deprecated.
    Use `getDefaultDurationBetweenEvictionRuns()`.
    Gets the default value for `()` for each per user pool.
    Returns:
      The default value for `()` for each per user pool.

  - ### getDefaultTransactionIsolation

    public int getDefaultTransactionIsolation()
    Gets the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setTransactionIsolation(int). If this method returns -1, the default is JDBC driver dependent.
    Returns:
      value of defaultTransactionIsolation.

  - ### getDescription

    public String getDescription()
    Gets the description. This property is defined by JDBC as for use with GUI (or other) tools that might deploy the datasource. It serves no internal purpose.
    Returns:
      value of description.

  - ### getInstanceKey

    protected String getInstanceKey()
    Gets the instance key.
    Returns:
      the instance key.

  - ### getJndiEnvironment

    public String getJndiEnvironment(String key)
    Gets the value of jndiEnvironment which is used when instantiating a JNDI InitialContext. This InitialContext is used to locate the back end ConnectionPoolDataSource.
    Parameters:
      `key` - JNDI environment key.
    Returns:
      value of jndiEnvironment.

  - ### getLoginTimeout

    @Deprecated public int getLoginTimeout()
    Deprecated.
    Use `getLoginTimeoutDuration()`.
    Gets the value of loginTimeout.
    Specified by:
      `getLoginTimeout` in interface `CommonDataSource`
    Returns:
      value of loginTimeout.

  - ### getLoginTimeoutDuration

    public Duration getLoginTimeoutDuration()
    Gets the value of loginTimeout.
    Returns:
      value of loginTimeout.
    Since:
      2.10.0

  - ### getLogWriter

    public PrintWriter getLogWriter()
    Gets the value of logWriter.
    Specified by:
      `getLogWriter` in interface `CommonDataSource`
    Returns:
      value of logWriter.

  - ### getMaxConnDuration

    public Duration getMaxConnDuration()
    Gets the maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
    Returns:
      The maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
    Since:
      2.10.0

  - ### getMaxConnLifetime

    @Deprecated public Duration getMaxConnLifetime()
    Deprecated.
    Use `getMaxConnDuration()`.
    Gets the maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
    Returns:
      The maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.

  - ### getMaxConnLifetimeMillis

    @Deprecated public long getMaxConnLifetimeMillis()
    Deprecated.
    Use `getMaxConnLifetime()`.
    Gets the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.
    Returns:
      The maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

  - ### getParentLogger

    public Logger getParentLogger() throws SQLFeatureNotSupportedException
    Specified by:
      `getParentLogger` in interface `CommonDataSource`
    Throws:
      `SQLFeatureNotSupportedException`

  - ### getPooledConnectionAndInfo

    protected abstract org.apache.commons.dbcp2.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String userName, String userPassword) throws SQLException
    This method is protected but can only be implemented in this package because PooledConnectionAndInfo is a package private type.
    Parameters:
      `userName` - The user name.
      `userPassword` - The user password.
    Returns:
      Matching PooledConnectionAndInfo.
    Throws:
      `SQLException` - Connection or registration failure.

  - ### getValidationQuery

    public String getValidationQuery()
    Gets 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. If not specified, `Connection.isValid(int)` will be used to validate connections.
    Returns:
      The SQL query that will be used to validate connections from this pool before returning them to the caller.

  - ### getValidationQueryTimeout

    @Deprecated public int getValidationQueryTimeout()
    Deprecated.
    Use `getValidationQueryTimeoutDuration()`.
    Returns the timeout in seconds before the validation query fails.
    Returns:
      The timeout in seconds before the validation query fails.

  - ### getValidationQueryTimeoutDuration

    public Duration getValidationQueryTimeoutDuration()
    Returns the timeout Duration before the validation query fails.
    Returns:
      The timeout Duration before the validation query fails.

  - ### isDefaultAutoCommit

    public Boolean isDefaultAutoCommit()
    Gets the value of defaultAutoCommit, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setAutoCommit(boolean). The default is `null` which will use the default value for the driver.
    Returns:
      value of defaultAutoCommit.

  - ### isDefaultReadOnly

    public Boolean isDefaultReadOnly()
    Gets the value of defaultReadOnly, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setReadOnly(boolean). The default is `null` which will use the default value for the driver.
    Returns:
      value of defaultReadOnly.

  - ### isRollbackAfterValidation

    public boolean isRollbackAfterValidation()
    Tests whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.
    Returns:
      true if a rollback will be issued after executing the validation query

  - ### isWrapperFor

    public boolean isWrapperFor(Class<?> iface) throws SQLException
    Specified by:
      `isWrapperFor` in interface `Wrapper`
    Throws:
      `SQLException`

  - ### setConnectionPoolDataSource

    public void setConnectionPoolDataSource(ConnectionPoolDataSource dataSource)
    Sets the back end ConnectionPoolDataSource. This property should not be set if using JNDI to access the data source.
    Parameters:
      `dataSource` - Value to assign to connectionPoolDataSource.

  - ### setDataSourceName

    public void setDataSourceName(String dataSourceName)
    Sets the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the data source from a JNDI service provider.
    Parameters:
      `dataSourceName` - Value to assign to dataSourceName.

  - ### setDefaultAutoCommit

    public void setDefaultAutoCommit(Boolean defaultAutoCommit)
    Sets the value of defaultAutoCommit, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setAutoCommit(boolean). The default is `null` which will use the default value for the driver.
    Parameters:
      `defaultAutoCommit` - Value to assign to defaultAutoCommit.

  - ### setDefaultBlockWhenExhausted

    public void setDefaultBlockWhenExhausted(boolean blockWhenExhausted)
    Sets the default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.
    Parameters:
      `blockWhenExhausted` - The default value for `BaseObjectPoolConfig.getBlockWhenExhausted()` for each per user pool.

  - ### setDefaultDurationBetweenEvictionRuns

    public void setDefaultDurationBetweenEvictionRuns(Duration defaultDurationBetweenEvictionRuns)
    Sets the default value for `()` for each per user pool.
    Parameters:
      `defaultDurationBetweenEvictionRuns` - The default value for `()` for each per user pool.
    Since:
      2.10.0

  - ### setDefaultEvictionPolicyClassName

    public void setDefaultEvictionPolicyClassName(String evictionPolicyClassName)
    Sets the default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.
    Parameters:
      `evictionPolicyClassName` - The default value for `BaseObjectPoolConfig.getEvictionPolicyClassName()` for each per user pool.

  - ### setDefaultLifo

    public void setDefaultLifo(boolean lifo)
    Sets the default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.
    Parameters:
      `lifo` - The default value for `BaseObjectPoolConfig.getLifo()` for each per user pool.

  - ### setDefaultMaxIdle

    public void setDefaultMaxIdle(int maxIdle)
    Sets the default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.
    Parameters:
      `maxIdle` - The default value for `GenericKeyedObjectPoolConfig.getMaxIdlePerKey()` for each per user pool.

  - ### setDefaultMaxTotal

    public void setDefaultMaxTotal(int maxTotal)
    Sets the default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.
    Parameters:
      `maxTotal` - The default value for `GenericKeyedObjectPoolConfig.getMaxTotalPerKey()` for each per user pool.

  - ### setDefaultMaxWait

    public void setDefaultMaxWait(Duration maxWaitMillis)
    Sets the default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
    Parameters:
      `maxWaitMillis` - The default value for `BaseObjectPoolConfig.getMaxWaitDuration()` for each per user pool.
    Since:
      2.9.0

  - ### setDefaultMaxWaitMillis

    @Deprecated public void setDefaultMaxWaitMillis(long maxWaitMillis)
    Deprecated.
    Use `setDefaultMaxWait(Duration)`.
    Sets the default value for `BaseObjectPoolConfig.getMaxWaitMillis()` for each per user pool.
    Parameters:
      `maxWaitMillis` - The default value for `BaseObjectPoolConfig.getMaxWaitMillis()` for each per user pool.

  - ### setDefaultMinEvictableIdle

    public void setDefaultMinEvictableIdle(Duration defaultMinEvictableIdleDuration)
    Sets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Parameters:
      `defaultMinEvictableIdleDuration` - The default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Since:
      2.10.0

  - ### setDefaultMinEvictableIdleTimeMillis

    @Deprecated public void setDefaultMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
    Deprecated.
    Use `setDefaultMinEvictableIdle(Duration)`.
    Sets the default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.
    Parameters:
      `minEvictableIdleTimeMillis` - The default value for `BaseObjectPoolConfig.getMinEvictableIdleDuration()` for each per user pool.

  - ### setDefaultMinIdle

    public void setDefaultMinIdle(int minIdle)
    Sets the default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.
    Parameters:
      `minIdle` - The default value for `GenericKeyedObjectPoolConfig.getMinIdlePerKey()` for each per user pool.

  - ### setDefaultNumTestsPerEvictionRun

    public void setDefaultNumTestsPerEvictionRun(int numTestsPerEvictionRun)
    Sets the default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.
    Parameters:
      `numTestsPerEvictionRun` - The default value for `BaseObjectPoolConfig.getNumTestsPerEvictionRun()` for each per user pool.

  - ### setDefaultReadOnly

    public void setDefaultReadOnly(Boolean defaultReadOnly)
    Sets the value of defaultReadOnly, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setReadOnly(boolean). The default is `null` which will use the default value for the driver.
    Parameters:
      `defaultReadOnly` - Value to assign to defaultReadOnly.

  - ### setDefaultSoftMinEvictableIdle

    public void setDefaultSoftMinEvictableIdle(Duration defaultSoftMinEvictableIdleDuration)
    Sets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Parameters:
      `defaultSoftMinEvictableIdleDuration` - The default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Since:
      2.10.0

  - ### setDefaultSoftMinEvictableIdleTimeMillis

    @Deprecated public void setDefaultSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
    Deprecated.
    Use `setDefaultSoftMinEvictableIdle(Duration)`.
    Sets the default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.
    Parameters:
      `softMinEvictableIdleTimeMillis` - The default value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for each per user pool.

  - ### setDefaultTestOnBorrow

    public void setDefaultTestOnBorrow(boolean testOnBorrow)
    Sets the default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.
    Parameters:
      `testOnBorrow` - The default value for `BaseGenericObjectPool.getTestOnBorrow()` for each per user pool.

  - ### setDefaultTestOnCreate

    public void setDefaultTestOnCreate(boolean testOnCreate)
    Sets the default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.
    Parameters:
      `testOnCreate` - The default value for `BaseGenericObjectPool.getTestOnCreate()` for each per user pool.

  - ### setDefaultTestOnReturn

    public void setDefaultTestOnReturn(boolean testOnReturn)
    Sets the default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.
    Parameters:
      `testOnReturn` - The default value for `BaseGenericObjectPool.getTestOnReturn()` for each per user pool.

  - ### setDefaultTestWhileIdle

    public void setDefaultTestWhileIdle(boolean testWhileIdle)
    Sets the default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.
    Parameters:
      `testWhileIdle` - The default value for `BaseGenericObjectPool.getTestWhileIdle()` for each per user pool.

  - ### setDefaultTimeBetweenEvictionRunsMillis

    @Deprecated public void setDefaultTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
    Deprecated.
    Use `setDefaultDurationBetweenEvictionRuns(Duration)`.
    Sets the default value for `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` for each per user pool.
    Parameters:
      `timeBetweenEvictionRunsMillis` - The default value for `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` for each per user pool.

  - ### setDefaultTransactionIsolation

    public void setDefaultTransactionIsolation(int defaultTransactionIsolation)
    Sets the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setTransactionIsolation(int). The default is JDBC driver dependent.
    Parameters:
      `defaultTransactionIsolation` - Value to assign to defaultTransactionIsolation

  - ### setDescription

    public void setDescription(String description)
    Sets the description. This property is defined by JDBC as for use with GUI (or other) tools that might deploy the datasource. It serves no internal purpose.
    Parameters:
      `description` - Value to assign to description.

  - ### setJndiEnvironment

    public void setJndiEnvironment(String key, String value)
    Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext. This InitialContext is used to locate the back end ConnectionPoolDataSource.
    Parameters:
      `key` - the JNDI environment property to set.
      `value` - the value assigned to specified JNDI environment property.

  - ### setLoginTimeout

    public void setLoginTimeout(Duration loginTimeout)
    Sets the value of loginTimeout.
    Parameters:
      `loginTimeout` - Value to assign to loginTimeout.
    Since:
      2.10.0

  - ### setLoginTimeout

    @Deprecated public void setLoginTimeout(int loginTimeout)
    Deprecated.
    Use `setLoginTimeout(Duration)`.
    Sets the value of loginTimeout.
    Specified by:
      `setLoginTimeout` in interface `CommonDataSource`
    Parameters:
      `loginTimeout` - Value to assign to loginTimeout.

  - ### setLogWriter

    public void setLogWriter(PrintWriter logWriter)
    Sets the value of logWriter.
    Specified by:
      `setLogWriter` in interface `CommonDataSource`
    Parameters:
      `logWriter` - Value to assign to logWriter.

  - ### setMaxConnLifetime

    public void setMaxConnLifetime(Duration maxConnLifetimeMillis)

    Sets the maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.

    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(PrintWriter)`, `setLoginTimeout(Duration)`, `getLoginTimeoutDuration()`, `getLogWriter()`.

    Parameters:
      `maxConnLifetimeMillis` - The maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
    Since:
      2.9.0

  - ### setMaxConnLifetimeMillis

    @Deprecated public void setMaxConnLifetimeMillis(long maxConnLifetimeMillis)
    Deprecated.
    Use `setMaxConnLifetime(Duration)`.

    Sets the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

    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(PrintWriter)`, `setLoginTimeout(Duration)`, `getLoginTimeoutDuration()`, `getLogWriter()`.

    Parameters:
      `maxConnLifetimeMillis` - The maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

  - ### setRollbackAfterValidation

    public void setRollbackAfterValidation(boolean rollbackAfterValidation)
    Sets whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller. Default behavior is NOT to issue a rollback. The setting will only have an effect if a validation query is set
    Parameters:
      `rollbackAfterValidation` - new property value

  - ### setupDefaults

    protected abstract void setupDefaults(Connection connection, String userName) throws SQLException
    Sets up the defaults for a given connection.
    Parameters:
      `connection` - The target connection.
      `userName` - The user name for the connection.
    Throws:
      `SQLException` - if a database access error occurs or this method is called on a closed connection

  - ### setValidationQuery

    public void setValidationQuery(String validationQuery)
    Sets 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. If not specified, connections will be validated using `Connection.isValid(int)`.
    Parameters:
      `validationQuery` - The SQL query that will be used to validate connections from this pool before returning them to the caller.

  - ### setValidationQueryTimeout

    public void setValidationQueryTimeout(Duration validationQueryTimeoutDuration)
    Sets the timeout duration before the validation query fails.
    Parameters:
      `validationQueryTimeoutDuration` - The new timeout duration.

  - ### setValidationQueryTimeout

    @Deprecated public void setValidationQueryTimeout(int validationQueryTimeoutSeconds)
    Deprecated.
    Use `setValidationQueryTimeout(Duration)`.
    Sets the timeout in seconds before the validation query fails.
    Parameters:
      `validationQueryTimeoutSeconds` - The new timeout in seconds

  - ### testCPDS

    protected ConnectionPoolDataSource testCPDS(String userName, String userPassword) throws NamingException, SQLException
    Tests and returns whether a JNDI context can be created to lookup a ConnectionPoolDataSource to then access a PooledConnection connection.
    Parameters:
      `userName` - An optional user name, may be null.
      `userPassword` - An optional user user password, may be null.
    Returns:
      A ConnectionPoolDataSource from a JNDI context.
    Throws:
      `NamingException` - if a naming exception is encountered.
      `SQLException` - if a ConnectionPoolDataSource or PooledConnection is not available.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`
    Since:
      2.6.0

  - ### toStringFields

    protected void toStringFields(StringBuilder builder)
    Appends this instance's fields to a string builder.
    Parameters:
      `builder` - the target string builder.

  - ### unwrap

    public <T> T unwrap(Class<T> iface) throws SQLException
    Specified by:
      `unwrap` in interface `Wrapper`
    Throws:
      `SQLException`