Class InstanceKeyDataSource
- All Implemented Interfaces:
Serializable
,Wrapper
,Referenceable
,CommonDataSource
,DataSource
- Direct Known Subclasses:
PerUserPoolDataSource
,SharedPoolDataSource
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-dbcp.
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.
- Version:
- $Revision: 907428 $ $Date: 2010-02-07 09:59:08 -0500 (Sun, 07 Feb 2010) $
- Author:
- John D. McNally
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract void
close()
Close the connection pool being maintained by this datasource.Attempt to establish a database connection.getConnection
(String username, String password) Attempt to retrieve a database connection usinggetPooledConnectionAndInfo(String, String)
with the provided username and password.Get the value of connectionPoolDataSource.Get the name of the ConnectionPoolDataSource which backs this pool.int
Get the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.Get the description.getJndiEnvironment
(String key) Get the value of jndiEnvironment which is used when instantiating a jndi InitialContext.int
Get the value of loginTimeout.Get the value of logWriter.int
Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).int
Returns the number of objects to examine during each run of the idle object evictor thread (if any).Retrieves the Reference of this object.boolean
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method.boolean
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.boolean
When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any).int
Returns the number of milliseconds to sleep between runs of the idle object evictor thread.The SQL query that will be used to validate connections from this pool before returning them to the caller.boolean
Get the value of defaultAutoCommit, which defines the state of connections handed out from this pool.boolean
Get the value of defaultReadOnly, which defines the state of connections handed out from this pool.boolean
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.final boolean
final boolean
final boolean
boolean
isWrapperFor
(Class<?> iface) void
Set the backend ConnectionPoolDataSource.void
Set the name of the ConnectionPoolDataSource which backs this pool.void
setDefaultAutoCommit
(boolean v) Set the value of defaultAutoCommit, which defines the state of connections handed out from this pool.void
setDefaultReadOnly
(boolean v) Set the value of defaultReadOnly, which defines the state of connections handed out from this pool.void
Set the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.void
Set 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 v) Set the value of loginTimeout.void
Set the value of logWriter.void
setMinEvictableIdleTimeMillis
(int minEvictableIdleTimeMillis) Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).void
setNumTestsPerEvictionRun
(int numTestsPerEvictionRun) Sets the number of objects to examine during each run of the idle object evictor thread (if any).void
setRollbackAfterValidation
(boolean rollbackAfterValidation) 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.void
setTestOnBorrow
(boolean testOnBorrow) When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method.void
setTestOnReturn
(boolean testOnReturn) When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.void
setTestWhileIdle
(boolean testWhileIdle) When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any).void
setTimeBetweenEvictionRunsMillis
(int timeBetweenEvictionRunsMillis) Sets the number of milliseconds to sleep between runs of the idle object evictor thread.void
setValidationQuery
(String validationQuery) The SQL query that will be used to validate connections from this pool before returning them to the caller.<T> T
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.sql.CommonDataSource
createShardingKeyBuilder, getParentLogger
Methods inherited from interface javax.sql.DataSource
createConnectionBuilder
-
Constructor Details
-
InstanceKeyDataSource
public InstanceKeyDataSource()Default no-arg constructor for Serialization
-
-
Method Details
-
close
Close the connection pool being maintained by this datasource.- Throws:
Exception
-
isWrapperFor
- Specified by:
isWrapperFor
in interfaceWrapper
- Throws:
SQLException
-
unwrap
- Specified by:
unwrap
in interfaceWrapper
- Throws:
SQLException
-
getConnectionPoolDataSource
Get the value of connectionPoolDataSource. This method will return null, if the backing datasource is being accessed via jndi.- Returns:
- value of connectionPoolDataSource.
-
setConnectionPoolDataSource
Set the backend ConnectionPoolDataSource. This property should not be set if using jndi to access the datasource.- Parameters:
v
- Value to assign to connectionPoolDataSource.
-
getDataSourceName
Get the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the datasource from a jndi service provider.- Returns:
- value of dataSourceName.
-
setDataSourceName
Set the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the datasource from a jndi service provider.- Parameters:
v
- Value to assign to dataSourceName.
-
isDefaultAutoCommit
public boolean isDefaultAutoCommit()Get 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 true.- Returns:
- value of defaultAutoCommit.
-
setDefaultAutoCommit
public void setDefaultAutoCommit(boolean v) Set 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 true.- Parameters:
v
- Value to assign to defaultAutoCommit.
-
isDefaultReadOnly
public boolean isDefaultReadOnly()Get 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 false.- Returns:
- value of defaultReadOnly.
-
setDefaultReadOnly
public void setDefaultReadOnly(boolean v) Set 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 false.- Parameters:
v
- Value to assign to defaultReadOnly.
-
getDefaultTransactionIsolation
public int getDefaultTransactionIsolation()Get 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.
-
setDefaultTransactionIsolation
public void setDefaultTransactionIsolation(int v) Set 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:
v
- Value to assign to defaultTransactionIsolation
-
getDescription
Get 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.
-
setDescription
Set 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:
v
- Value to assign to description.
-
getJndiEnvironment
Get the value of jndiEnvironment which is used when instantiating a jndi InitialContext. This InitialContext is used to locate the backend ConnectionPoolDataSource.- Returns:
- value of jndiEnvironment.
-
setJndiEnvironment
Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext. This InitialContext is used to locate the backend ConnectionPoolDataSource.- Parameters:
key
- the JNDI environment property to set.value
- the value assigned to specified JNDI environment property.
-
getLoginTimeout
public int getLoginTimeout()Get the value of loginTimeout.- Specified by:
getLoginTimeout
in interfaceCommonDataSource
- Specified by:
getLoginTimeout
in interfaceDataSource
- Returns:
- value of loginTimeout.
-
setLoginTimeout
public void setLoginTimeout(int v) Set the value of loginTimeout.- Specified by:
setLoginTimeout
in interfaceCommonDataSource
- Specified by:
setLoginTimeout
in interfaceDataSource
- Parameters:
v
- Value to assign to loginTimeout.
-
getLogWriter
Get the value of logWriter.- Specified by:
getLogWriter
in interfaceCommonDataSource
- Specified by:
getLogWriter
in interfaceDataSource
- Returns:
- value of logWriter.
-
setLogWriter
Set the value of logWriter.- Specified by:
setLogWriter
in interfaceCommonDataSource
- Specified by:
setLogWriter
in interfaceDataSource
- Parameters:
v
- Value to assign to logWriter.
-
isTestOnBorrow
public final boolean isTestOnBorrow()- See Also:
-
getTestOnBorrow
public boolean getTestOnBorrow()When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.- See Also:
-
setTestOnBorrow
public void setTestOnBorrow(boolean testOnBorrow) When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. For atrue
value to have any effect, thevalidationQuery
property must be set to a non-null string.- See Also:
-
isTestOnReturn
public final boolean isTestOnReturn()- See Also:
-
getTestOnReturn
public boolean getTestOnReturn()When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.- See Also:
-
setTestOnReturn
public void setTestOnReturn(boolean testOnReturn) When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}. For atrue
value to have any effect, thevalidationQuery
property must be set to a non-null string.- See Also:
-
getTimeBetweenEvictionRunsMillis
public int getTimeBetweenEvictionRunsMillis()Returns 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.- See Also:
-
setTimeBetweenEvictionRunsMillis
public void setTimeBetweenEvictionRunsMillis(int 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.- See Also:
-
getNumTestsPerEvictionRun
public int getNumTestsPerEvictionRun()Returns the number of objects to examine during each run of the idle object evictor thread (if any).- See Also:
-
setNumTestsPerEvictionRun
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) Sets the number of objects 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.
- See Also:
-
getMinEvictableIdleTimeMillis
public int getMinEvictableIdleTimeMillis()Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).- See Also:
-
setMinEvictableIdleTimeMillis
public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis) Sets the minimum amount of time an object may sit idle in the pool before it is eligable 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.- See Also:
-
isTestWhileIdle
public final boolean isTestWhileIdle()- See Also:
-
getTestWhileIdle
public boolean getTestWhileIdle()When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.- See Also:
-
setTestWhileIdle
public void setTestWhileIdle(boolean testWhileIdle) When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. For atrue
value to have any effect, thevalidationQuery
property must be set to a non-null string.- See Also:
-
getValidationQuery
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. -
setValidationQuery
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 none of the properties, testOnBorow, testOnReturn, testWhileIdle have been previously set, calling this method sets testOnBorrow to true. -
isRollbackAfterValidation
public boolean isRollbackAfterValidation()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
- Since:
- 1.2.2
-
setRollbackAfterValidation
public void setRollbackAfterValidation(boolean rollbackAfterValidation) 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- Since:
- 1.2.2
-
getConnection
Attempt to establish a database connection.- Specified by:
getConnection
in interfaceDataSource
- Throws:
SQLException
-
getConnection
Attempt to retrieve a database connection usinggetPooledConnectionAndInfo(String, String)
with the provided username and password. The password on thePooledConnectionAndInfo
instance returned bygetPooledConnectionAndInfo
is compared to thepassword
parameter. If the comparison fails, a database connection using the supplied username 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, thePooledConnectionAndInfo
instance retrieved with the old password is destroyed and thegetPooledConnectionAndInfo
is repeatedly invoked until aPooledConnectionAndInfo
instance with the new password is returned.- Specified by:
getConnection
in interfaceDataSource
- Throws:
SQLException
-
getReference
Retrieves the Reference of this object. Note:InstanceKeyDataSource
subclasses should override this method. The implementaion included below is not robust and will be removed at the next major version DBCP release.- Specified by:
getReference
in interfaceReferenceable
- Returns:
- The non-null Reference of this object.
- Throws:
NamingException
- If a naming exception was encountered while retrieving the reference.
-