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. 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 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()	Whether to toggle the pooling of PreparedStatements
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)	Whether to toggle the pooling of PreparedStatements
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 value

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()

Whether to toggle the pooling of PreparedStatements

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

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)

Whether to toggle the pooling of PreparedStatements

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