Package org.apache.commons.dbcp2.cpdsadapter

# Class DriverAdapterCPDS

java.lang.Object
org.apache.commons.dbcp2.cpdsadapter.DriverAdapterCPDS

All Implemented Interfaces:
  `Serializable`, `Referenceable`, `ObjectFactory`, `CommonDataSource`, `ConnectionPoolDataSource`

public class DriverAdapterCPDS extends Object implements ConnectionPoolDataSource, Referenceable, Serializable, ObjectFactory

An adapter for JDBC drivers that do not include an implementation of `ConnectionPoolDataSource`, but still include a `DriverManager` implementation. `ConnectionPoolDataSource`s are not used within general applications. They are used by `DataSource` implementations that pool `Connection`s, such as `SharedPoolDataSource`. A J2EE container will normally provide some method of initializing the `ConnectionPoolDataSource` whose attributes are presented as bean getters/setters and then deploying it via JNDI. It is then available as a source of physical connections to the database, when the pooling `DataSource` needs to create a new physical connection.

Although normally used within a JNDI environment, the DriverAdapterCPDS can be instantiated and initialized as any bean and then attached directly to a pooling `DataSource`. `Jdbc2PoolDataSource` can use the `ConnectionPoolDataSource` with or without the use of JNDI.

The DriverAdapterCPDS also provides `PreparedStatement` pooling which is not generally available in jdbc2 `ConnectionPoolDataSource` implementation, but is addressed within the JDBC 3 specification. The `PreparedStatement` pool in DriverAdapterCPDS has been in the DBCP package for some time, but it has not undergone extensive testing in the configuration used here. It should be considered experimental and can be toggled with the poolPreparedStatements attribute.

The package documentation contains an example using Apache Catalina and JNDI. The datasources package documentation shows how to use `DriverAdapterCPDS` as a source for `Jdbc2PoolDataSource` without the use of JNDI.

Since:
  2.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DriverAdapterCPDS()`
  Default no-argument constructor for Serialization

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Properties`
  `getConnectionProperties()`
  Gets the connection properties passed to the JDBC driver.
  `String`
  `getDescription()`
  Gets the value of description.
  `String`
  `getDriver()`
  Gets the driver class name.
  `Duration`
  `getDurationBetweenEvictionRuns()`
  Gets the duration to sleep between runs of the idle object evictor thread.
  `int`
  `getLoginTimeout()`
  Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
  `PrintWriter`
  `getLogWriter()`
  Gets the log writer for this data source.
  `int`
  `getMaxIdle()`
  Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
  `int`
  `getMaxPreparedStatements()`
  Gets the maximum number of prepared statements.
  `Duration`
  `getMinEvictableIdleDuration()`
  Gets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
  `int`
  `getMinEvictableIdleTimeMillis()`
  Deprecated.
  USe `getMinEvictableIdleDuration()`.
  `int`
  `getNumTestsPerEvictionRun()`
  Gets the number of statements to examine during each run of the idle object evictor thread (if any.)
  `Object`
  `getObjectInstance(Object refObj, Name name, Context context, Hashtable<?,?> env)`
  Implements `ObjectFactory` to create an instance of this class
  `Logger`
  `getParentLogger()`
  `String`
  `getPassword()`
  Gets the value of password for the default user.
  `char[]`
  `getPasswordCharArray()`
  Gets the value of password for the default user.
  `PooledConnection`
  `getPooledConnection()`
  Attempts to establish a database connection using the default user and password.
  `PooledConnection`
  `getPooledConnection(String pooledUserName, String pooledUserPassword)`
  Attempts to establish a database connection.
  `Reference`
  `getReference()`
  Implements `Referenceable`.
  `long`
  `getTimeBetweenEvictionRunsMillis()`
  Deprecated.
  Use `getDurationBetweenEvictionRuns()`.
  `String`
  `getUrl()`
  Gets the value of connection string used to locate the database for this data source.
  `String`
  `getUser()`
  Gets the value of default user (login or user name).
  `boolean`
  `isAccessToUnderlyingConnectionAllowed()`
  Returns the value of the accessToUnderlyingConnectionAllowed property.
  `boolean`
  `isPoolPreparedStatements()`
  Tests whether to toggle the pooling of `PreparedStatement`s
  `void`
  `setAccessToUnderlyingConnectionAllowed(boolean allow)`
  Sets the value of the accessToUnderlyingConnectionAllowed property.
  `void`
  `setConnectionProperties(Properties props)`
  Sets the connection properties passed to the JDBC driver.
  `void`
  `setDescription(String description)`
  Sets the value of description.
  `void`
  `setDriver(String driver)`
  Sets the driver class name.
  `void`
  `setDurationBetweenEvictionRuns(Duration durationBetweenEvictionRuns)`
  Sets the duration to sleep between runs of the idle object evictor thread.
  `void`
  `setLoginTimeout(int seconds)`
  Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
  `void`
  `setLogWriter(PrintWriter logWriter)`
  Sets the log writer for this data source.
  `void`
  `setMaxIdle(int maxIdle)`
  Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
  `void`
  `setMaxPreparedStatements(int maxPreparedStatements)`
  Sets the maximum number of prepared statements.
  `void`
  `setMinEvictableIdleDuration(Duration minEvictableIdleDuration)`
  Sets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
  `void`
  `setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)`
  Deprecated.
  Use `setMinEvictableIdleDuration(Duration)`.
  `void`
  `setNumTestsPerEvictionRun(int numTestsPerEvictionRun)`
  Sets the number of statements to examine during each run of the idle object evictor thread (if any).
  `void`
  `setPassword(char[] userPassword)`
  Sets the value of password for the default user.
  `void`
  `setPassword(String userPassword)`
  Sets the value of password for the default user.
  `void`
  `setPoolPreparedStatements(boolean poolPreparedStatements)`
  Sets whether to toggle the pooling of `PreparedStatement`s
  `void`
  `setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)`
  Deprecated.
  Use `setDurationBetweenEvictionRuns(Duration)`.
  `void`
  `setUrl(String connectionString)`
  Sets the value of URL string used to locate the database for this data source.
  `void`
  `setUser(String userName)`
  Sets the value of default user (login or user name).
  `String`
  `toString()`
  Does not print the userName and userPassword field nor the 'user' or 'password' in the connectionProperties.

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

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

- ## Constructor Details

  - ### DriverAdapterCPDS

    public DriverAdapterCPDS()
    Default no-argument constructor for Serialization

- ## Method Details

  - ### getConnectionProperties

    public Properties getConnectionProperties()
    Gets the connection properties passed to the JDBC driver.
    Returns:
      the JDBC connection properties used when creating connections.

  - ### getDescription

    public String getDescription()
    Gets the value of description. This property is here for use by the code which will deploy this data source. It is not used internally.
    Returns:
      value of description, may be null.
    See Also:
      - `setDescription(String)`

  - ### getDriver

    public String getDriver()
    Gets the driver class name.
    Returns:
      value of driver.

  - ### getDurationBetweenEvictionRuns

    public Duration getDurationBetweenEvictionRuns()
    Gets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
    Returns:
      the value of the evictor thread timer
    Since:
      2.9.0
    See Also:
      - `setDurationBetweenEvictionRuns(Duration)`

  - ### getLoginTimeout

    public int getLoginTimeout()
    Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. NOT USED.
    Specified by:
      `getLoginTimeout` in interface `CommonDataSource`

  - ### getLogWriter

    public PrintWriter getLogWriter()
    Gets the log writer for this data source. NOT USED.
    Specified by:
      `getLogWriter` in interface `CommonDataSource`

  - ### getMaxIdle

    public int getMaxIdle()
    Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
    Returns:
      the value of maxIdle

  - ### getMaxPreparedStatements

    public int getMaxPreparedStatements()
    Gets the maximum number of prepared statements.
    Returns:
      maxPrepartedStatements, defaults to -1, meaning no limit.

  - ### getMinEvictableIdleDuration

    public Duration getMinEvictableIdleDuration()
    Gets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
    Returns:
      the minimum amount of time a statement may sit idle in the pool.
    Since:
      2.9.0
    See Also:
      - `setMinEvictableIdleDuration(java.time.Duration)`
      - `setDurationBetweenEvictionRuns(java.time.Duration)`

  - ### getMinEvictableIdleTimeMillis

    @Deprecated public int getMinEvictableIdleTimeMillis()
    Deprecated.
    USe `getMinEvictableIdleDuration()`.
    Gets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
    Returns:
      the minimum amount of time a statement may sit idle in the pool.
    See Also:
      - `setMinEvictableIdleTimeMillis(int)`
      - `setTimeBetweenEvictionRunsMillis(long)`

  - ### getNumTestsPerEvictionRun

    public int getNumTestsPerEvictionRun()
    Gets the number of statements to examine during each run of the idle object evictor thread (if any.)
    Returns:
      the number of statements to examine during each run of the idle object evictor thread (if any.)
    See Also:
      - `setNumTestsPerEvictionRun(int)`
      - `setTimeBetweenEvictionRunsMillis(long)`

  - ### getObjectInstance

    public Object getObjectInstance(Object refObj, Name name, Context context, Hashtable<?,?> env) throws ClassNotFoundException
    Implements `ObjectFactory` to create an instance of this class
    Specified by:
      `getObjectInstance` in interface `ObjectFactory`
    Throws:
      `ClassNotFoundException`

  - ### getParentLogger

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

  - ### getPassword

    public String getPassword()
    Gets the value of password for the default user.
    Returns:
      value of password.

  - ### getPasswordCharArray

    public char[] getPasswordCharArray()
    Gets the value of password for the default user.
    Returns:
      value of password.
    Since:
      2.4.0

  - ### getPooledConnection

    public PooledConnection getPooledConnection() throws SQLException
    Attempts to establish a database connection using the default user and password.
    Specified by:
      `getPooledConnection` in interface `ConnectionPoolDataSource`
    Throws:
      `SQLException`

  - ### getPooledConnection

    public PooledConnection getPooledConnection(String pooledUserName, String pooledUserPassword) throws SQLException
    Attempts to establish a database connection.
    Specified by:
      `getPooledConnection` in interface `ConnectionPoolDataSource`
    Parameters:
      `pooledUserName` - name to be used for the connection
      `pooledUserPassword` - password to be used fur the connection
    Throws:
      `SQLException`

  - ### getReference

    public Reference getReference() throws NamingException
    Implements `Referenceable`.
    Specified by:
      `getReference` in interface `Referenceable`
    Throws:
      `NamingException`

  - ### getTimeBetweenEvictionRunsMillis

    @Deprecated public long getTimeBetweenEvictionRunsMillis()
    Deprecated.
    Use `getDurationBetweenEvictionRuns()`.
    Gets 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.
    Returns:
      the value of the evictor thread timer
    See Also:
      - `setDurationBetweenEvictionRuns(Duration)`

  - ### getUrl

    public String getUrl()
    Gets the value of connection string used to locate the database for this data source.
    Returns:
      value of connection string.

  - ### getUser

    public String getUser()
    Gets the value of default user (login or user name).
    Returns:
      value of user.

  - ### isAccessToUnderlyingConnectionAllowed

    public boolean isAccessToUnderlyingConnectionAllowed()
    Returns the value of the accessToUnderlyingConnectionAllowed property.
    Returns:
      true if access to the underlying is allowed, false otherwise.

  - ### isPoolPreparedStatements

    public boolean isPoolPreparedStatements()
    Tests whether to toggle the pooling of `PreparedStatement`s
    Returns:
      value of poolPreparedStatements.

  - ### 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)
    Parameters:
      `allow` - Access to the underlying connection is granted when true.

  - ### setConnectionProperties

    public void setConnectionProperties(Properties props)
    Sets the connection properties passed to the JDBC driver.

    If `props` contains "user" and/or "password" properties, the corresponding instance properties are set. If these properties are not present, they are filled in using `getUser()`, `getPassword()` when `getPooledConnection()` is called, or using the actual parameters to the method call when `getPooledConnection(String, String)` is called. Calls to `setUser(String)` or `setPassword(String)` overwrite the values of these properties if `connectionProperties` is not null.

    Parameters:
      `props` - Connection properties to use when creating new connections.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setDescription

    public void setDescription(String description)
    Sets the value of description. This property is here for use by the code which will deploy this datasource. It is not used internally.
    Parameters:
      `description` - Value to assign to description.

  - ### setDriver

    public void setDriver(String driver) throws ClassNotFoundException
    Sets the driver class name. Setting the driver class name cause the driver to be registered with the DriverManager.
    Parameters:
      `driver` - Value to assign to driver.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called
      `ClassNotFoundException` - if the class cannot be located

  - ### setDurationBetweenEvictionRuns

    public void setDurationBetweenEvictionRuns(Duration durationBetweenEvictionRuns)
    Sets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
    Parameters:
      `durationBetweenEvictionRuns` - The duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called
    Since:
      2.9.0
    See Also:
      - `getDurationBetweenEvictionRuns()`

  - ### setLoginTimeout

    public void setLoginTimeout(int seconds)
    Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. NOT USED.
    Specified by:
      `setLoginTimeout` in interface `CommonDataSource`

  - ### setLogWriter

    public void setLogWriter(PrintWriter logWriter)
    Sets the log writer for this data source. NOT USED.
    Specified by:
      `setLogWriter` in interface `CommonDataSource`

  - ### setMaxIdle

    public void setMaxIdle(int maxIdle)
    Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
    Parameters:
      `maxIdle` - The maximum number of statements that can remain idle
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setMaxPreparedStatements

    public void setMaxPreparedStatements(int maxPreparedStatements)
    Sets the maximum number of prepared statements.
    Parameters:
      `maxPreparedStatements` - the new maximum number of prepared statements, <= 0 means no limit.

  - ### setMinEvictableIdleDuration

    public void setMinEvictableIdleDuration(Duration minEvictableIdleDuration)
    Sets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.
    Parameters:
      `minEvictableIdleDuration` - minimum time to set in milliseconds.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called.
    Since:
      2.9.0
    See Also:
      - `getMinEvictableIdleDuration()`
      - `setDurationBetweenEvictionRuns(Duration)`

  - ### setMinEvictableIdleTimeMillis

    @Deprecated public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
    Deprecated.
    Use `setMinEvictableIdleDuration(Duration)`.
    Sets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.
    Parameters:
      `minEvictableIdleTimeMillis` - minimum time to set in milliseconds.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called
    See Also:
      - `getMinEvictableIdleDuration()`
      - `setDurationBetweenEvictionRuns(Duration)`

  - ### setNumTestsPerEvictionRun

    public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
    Sets the number of statements to examine during each run of the idle object evictor thread (if any).

    When a negative value is supplied, `ceil({@link BasicDataSource#getNumIdle})/abs({@link #getNumTestsPerEvictionRun})` tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.

    Parameters:
      `numTestsPerEvictionRun` - number of statements to examine per run
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called
    See Also:
      - `getNumTestsPerEvictionRun()`
      - `setDurationBetweenEvictionRuns(Duration)`

  - ### setPassword

    public void setPassword(char[] userPassword)
    Sets the value of password for the default user.
    Parameters:
      `userPassword` - Value to assign to password.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setPassword

    public void setPassword(String userPassword)
    Sets the value of password for the default user.
    Parameters:
      `userPassword` - Value to assign to password.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setPoolPreparedStatements

    public void setPoolPreparedStatements(boolean poolPreparedStatements)
    Sets whether to toggle the pooling of `PreparedStatement`s
    Parameters:
      `poolPreparedStatements` - true to pool statements.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setTimeBetweenEvictionRunsMillis

    @Deprecated public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
    Deprecated.
    Use `setDurationBetweenEvictionRuns(Duration)`.
    Sets 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.
    Parameters:
      `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.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called
    See Also:
      - `getDurationBetweenEvictionRuns()`

  - ### setUrl

    public void setUrl(String connectionString)
    Sets the value of URL string used to locate the database for this data source.
    Parameters:
      `connectionString` - Value to assign to connection string.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### setUser

    public void setUser(String userName)
    Sets the value of default user (login or user name).
    Parameters:
      `userName` - Value to assign to user.
    Throws:
      `IllegalStateException` - if `getPooledConnection()` has been called

  - ### toString

    public String toString()
    Does not print the userName and userPassword field nor the 'user' or 'password' in the connectionProperties.
    Overrides:
      `toString` in class `Object`
    Since:
      2.6.0