DriverAdapterCPDS (Apache Commons DBCP 2.2.0 API)

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. ConnectionPoolDataSources are not used within general applications. They are used by DataSource implementations that pool Connections, 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 jdbc3 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 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

Author:

John D. McNally

See Also:
Serialized Form

Constructor Summary

Constructors
Constructor and Description

DriverAdapterCPDS()
Default no-arg constructor for Serialization

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

Method Summary

Methods
Modifier and Type	Method and Description
`Properties`	`getConnectionProperties()` Gets the connection properties passed to the JDBC driver.
`String`	`getDescription()` Gets the value of description.
`String`	`getDriver()` Gets the driver classname.
`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.
`int`	`getMinEvictableIdleTimeMillis()` 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`	`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.
`PooledConnection`	`getPooledConnection()` Attempt to establish a database connection using the default user and password.
`PooledConnection`	`getPooledConnection(String username, String pass)` Attempt to establish a database connection.
`Reference`	`getReference()` `Referenceable` implementation.
`long`	`getTimeBetweenEvictionRunsMillis()` Gets the number of milliseconds to sleep between runs of the idle object evictor thread.
`String`	`getUrl()` Gets the value of url used to locate the database for this datasource.
`String`	`getUser()` Gets the value of default user (login or username).
`boolean`	`isAccessToUnderlyingConnectionAllowed()` Returns the value of the accessToUnderlyingConnectionAllowed property.
`boolean`	`isPoolPreparedStatements()` Flag 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 v)` Sets the value of description.
`void`	`setDriver(String v)` Sets the driver classname.
`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 out)` 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`	`setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)` 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`	`setNumTestsPerEvictionRun(int numTestsPerEvictionRun)` Sets the number of statements to examine during each run of the idle object evictor thread (if any).
`void`	`setPassword(String v)` Sets the value of password for the default user.
`void`	`setPoolPreparedStatements(boolean v)` Flag to toggle the pooling of `PreparedStatement`s
`void`	`setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)` Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
`void`	`setUrl(String v)` Sets the value of URL string used to locate the database for this datasource.
`void`	`setUser(String v)` Sets the value of default user (login or username).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - DriverAdapterCPDS
```
public DriverAdapterCPDS()
```
    Default no-arg constructor for Serialization
- Method Detail
  - getPooledConnection
```
public PooledConnection getPooledConnection()
                                     throws SQLException
```
    Attempt to establish a database connection using the default user and password.
    
    Specified by:
    
    getPooledConnection in interface ConnectionPoolDataSource
    
    Throws:
    
    SQLException
  - getPooledConnection
```
public PooledConnection getPooledConnection(String username,
                                   String pass)
                                     throws SQLException
```
    Attempt to establish a database connection.
    
    Specified by:
    
    getPooledConnection in interface ConnectionPoolDataSource
    
    Parameters:
    username - name to be used for the connection
    pass - password to be used fur the connection
    
    Throws:
    
    SQLException
  - getParentLogger
```
public Logger getParentLogger()
                       throws SQLFeatureNotSupportedException
```
    Specified by:
    
    getParentLogger in interface CommonDataSource
    
    Throws:
    
    SQLFeatureNotSupportedException
  - getReference
```
public Reference getReference()
                       throws NamingException
```
    Referenceable implementation.
    
    Specified by:
    
    getReference in interface Referenceable
    
    Throws:
    
    NamingException
  - getObjectInstance
```
public Object getObjectInstance(Object refObj,
                       Name name,
                       Context context,
                       Hashtable<?,?> env)
                         throws Exception
```
    implements ObjectFactory to create an instance of this class
    
    Specified by:
    
    getObjectInstance in interface ObjectFactory
    
    Throws:
    
    Exception
  - getConnectionProperties
```
public Properties getConnectionProperties()
```
    Gets the connection properties passed to the JDBC driver.
    
    Returns:
    the JDBC connection properties used when creating connections.
  - 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
  - getDescription
```
public String getDescription()
```
    Gets the value of description. This property is here for use by the code which will deploy this datasource. It is not used internally.
    
    Returns:
    value of description, may be null.
    See Also:
    setDescription(String)
  - setDescription
```
public void setDescription(String v)
```
    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:
    v - Value to assign to description.
  - getPassword
```
public String getPassword()
```
    Gets the value of password for the default user.
    
    Returns:
    value of password.
  - setPassword
```
public void setPassword(String v)
```
    Sets the value of password for the default user.
    
    Parameters:
    v - Value to assign to password.
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
  - getUrl
```
public String getUrl()
```
    Gets the value of url used to locate the database for this datasource.
    
    Returns:
    value of url.
  - setUrl
```
public void setUrl(String v)
```
    Sets the value of URL string used to locate the database for this datasource.
    
    Parameters:
    v - Value to assign to url.
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
  - getUser
```
public String getUser()
```
    Gets the value of default user (login or username).
    
    Returns:
    value of user.
  - setUser
```
public void setUser(String v)
```
    Sets the value of default user (login or username).
    
    Parameters:
    v - Value to assign to user.
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
  - getDriver
```
public String getDriver()
```
    Gets the driver classname.
    
    Returns:
    value of driver.
  - setDriver
```
public void setDriver(String v)
               throws ClassNotFoundException
```
    Sets the driver classname. Setting the driver classname cause the driver to be registered with the DriverManager.
    
    Parameters:
    v - Value to assign to driver.
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
    
    ClassNotFoundException
  - 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
  - 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 out)
```
    Sets the log writer for this data source. NOT USED.
    
    Specified by:
    
    setLogWriter in interface CommonDataSource
  - isPoolPreparedStatements
```
public boolean isPoolPreparedStatements()
```
    Flag to toggle the pooling of PreparedStatements
    
    Returns:
    value of poolPreparedStatements.
  - setPoolPreparedStatements
```
public void setPoolPreparedStatements(boolean v)
```
    Flag to toggle the pooling of PreparedStatements
    
    Parameters:
    v - true to pool statements.
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
  - 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
  - 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
  - getTimeBetweenEvictionRunsMillis
```
public long getTimeBetweenEvictionRunsMillis()
```
    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:
    setTimeBetweenEvictionRunsMillis(long)
  - setTimeBetweenEvictionRunsMillis
```
public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
```
    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 -
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
    See Also:
    getTimeBetweenEvictionRunsMillis()
  - getNumTestsPerEvictionRun
```
public int getNumTestsPerEvictionRun()
```
    Gets the number of statements to examine during each run of the idle object evictor thread (if any). *see #setNumTestsPerEvictionRun *see #setTimeBetweenEvictionRunsMillis
  - 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 #numIdle})/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(), setTimeBetweenEvictionRunsMillis(long)
  - getMinEvictableIdleTimeMillis
```
public int getMinEvictableIdleTimeMillis()
```
    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). *see #setMinEvictableIdleTimeMillis *see #setTimeBetweenEvictionRunsMillis
  - setMinEvictableIdleTimeMillis
```
public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
```
    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 ms)
    
    Throws:
    
    IllegalStateException - if getPooledConnection() has been called
    See Also:
    getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)
  - isAccessToUnderlyingConnectionAllowed
```
public boolean isAccessToUnderlyingConnectionAllowed()
```
    Returns the value of the accessToUnderlyingConnectionAllowed property.
    
    Returns:
    true if access to the underlying 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)
    
    Parameters:
    allow - Access to the underlying connection is granted when true.
  - getMaxPreparedStatements
```
public int getMaxPreparedStatements()
```
    Gets the maximum number of prepared statements.
    
    Returns:
    maxPrepartedStatements value
  - setMaxPreparedStatements
```
public void setMaxPreparedStatements(int maxPreparedStatements)
```
    Sets the maximum number of prepared statements.
    
    Parameters:
    maxPreparedStatements - the new maximum number of prepared statements

Class DriverAdapterCPDS

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DriverAdapterCPDS

Method Detail

getPooledConnection

getPooledConnection

getParentLogger

getReference

getObjectInstance

getConnectionProperties

setConnectionProperties

getDescription

setDescription

getPassword

setPassword

getUrl

setUrl

getUser

setUser

getDriver

setDriver

getLoginTimeout

getLogWriter

setLoginTimeout

setLogWriter

isPoolPreparedStatements

setPoolPreparedStatements

getMaxIdle

setMaxIdle

getTimeBetweenEvictionRunsMillis

setTimeBetweenEvictionRunsMillis

getNumTestsPerEvictionRun

setNumTestsPerEvictionRun

getMinEvictableIdleTimeMillis

setMinEvictableIdleTimeMillis

isAccessToUnderlyingConnectionAllowed

setAccessToUnderlyingConnectionAllowed

getMaxPreparedStatements

setMaxPreparedStatements