public abstract class InstanceKeyDataSource
extends java.lang.Object
implements javax.sql.DataSource, javax.naming.Referenceable, java.io.Serializable
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.
Modifier and Type | Field and Description |
---|---|
private int |
_minEvictableIdleTimeMillis |
private int |
_numTestsPerEvictionRun |
private boolean |
_testOnBorrow |
private boolean |
_testOnReturn |
private boolean |
_testWhileIdle |
private int |
_timeBetweenEvictionRunsMillis |
private static java.lang.String |
BAD_TRANSACTION_ISOLATION |
private javax.sql.ConnectionPoolDataSource |
dataSource
Underlying source of PooledConnections
|
private java.lang.String |
dataSourceName
DataSource Name used to find the ConnectionPoolDataSource
|
private boolean |
defaultAutoCommit |
private boolean |
defaultReadOnly |
private int |
defaultTransactionIsolation |
private java.lang.String |
description
Description
|
private static java.lang.String |
GET_CONNECTION_CALLED |
private boolean |
getConnectionCalled
Guards property setters - once true, setters throw IllegalStateException
|
protected java.lang.String |
instanceKey
Instance key
|
(package private) java.util.Properties |
jndiEnvironment
Environment that may be used to set up a jndi initial context.
|
private int |
loginTimeout
Login TimeOut in seconds
|
private java.io.PrintWriter |
logWriter
Log stream
|
private boolean |
rollbackAfterValidation |
private static long |
serialVersionUID |
private boolean |
testPositionSet
true iff one of the setters for testOnBorrow, testOnReturn, testWhileIdle has been called.
|
protected static int |
UNKNOWN_TRANSACTIONISOLATION
Internal constant to indicate the level is not set.
|
private java.lang.String |
validationQuery |
Constructor and Description |
---|
InstanceKeyDataSource()
Default no-arg constructor for Serialization
|
Modifier and Type | Method and Description |
---|---|
protected void |
assertInitializationAllowed()
Throws an IllegalStateException, if a PooledConnection has already
been requested.
|
abstract void |
close()
Close the connection pool being maintained by this datasource.
|
private void |
closeDueToException(PooledConnectionAndInfo info) |
java.sql.Connection |
getConnection()
Attempt to establish a database connection.
|
java.sql.Connection |
getConnection(java.lang.String username,
java.lang.String password)
Attempt to retrieve a database connection using
getPooledConnectionAndInfo(String, String)
with the provided username and password. |
protected abstract PooledConnectionManager |
getConnectionManager(UserPassKey upkey) |
javax.sql.ConnectionPoolDataSource |
getConnectionPoolDataSource()
Get the value of connectionPoolDataSource.
|
java.lang.String |
getDataSourceName()
Get the name of the ConnectionPoolDataSource which backs this pool.
|
int |
getDefaultTransactionIsolation()
Get the value of defaultTransactionIsolation, which defines the state of
connections handed out from this pool.
|
java.lang.String |
getDescription()
Get the description.
|
java.lang.String |
getJndiEnvironment(java.lang.String key)
Get the value of jndiEnvironment which is used when instantiating
a jndi InitialContext.
|
int |
getLoginTimeout()
Get the value of loginTimeout.
|
java.io.PrintWriter |
getLogWriter()
Get the value of logWriter.
|
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).
|
int |
getNumTestsPerEvictionRun()
Returns the number of objects to examine during each run of the
idle object evictor thread (if any).
|
protected abstract PooledConnectionAndInfo |
getPooledConnectionAndInfo(java.lang.String username,
java.lang.String password) |
javax.naming.Reference |
getReference()
Retrieves the Reference of this object.
|
boolean |
getTestOnBorrow()
When true, objects will be
{*link PoolableObjectFactory#validateObject validated}
before being returned by the {*link #borrowObject}
method.
|
boolean |
getTestOnReturn()
When true, objects will be
{*link PoolableObjectFactory#validateObject validated}
before being returned to the pool within the
{*link #returnObject}.
|
boolean |
getTestWhileIdle()
When true, objects will be
{*link PoolableObjectFactory#validateObject validated}
by the idle object evictor (if any).
|
int |
getTimeBetweenEvictionRunsMillis()
Returns the number of milliseconds to sleep between runs of the
idle object evictor thread.
|
java.lang.String |
getValidationQuery()
The SQL query that will be used to validate connections from this pool
before returning them to the caller.
|
boolean |
isDefaultAutoCommit()
Get the value of defaultAutoCommit, which defines the state of
connections handed out from this pool.
|
boolean |
isDefaultReadOnly()
Get the value of defaultReadOnly, which defines the state of
connections handed out from this pool.
|
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.
|
boolean |
isTestOnBorrow() |
boolean |
isTestOnReturn() |
boolean |
isTestWhileIdle() |
boolean |
isWrapperFor(java.lang.Class<?> iface) |
void |
setConnectionPoolDataSource(javax.sql.ConnectionPoolDataSource v)
Set the backend ConnectionPoolDataSource.
|
void |
setDataSourceName(java.lang.String v)
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 |
setDefaultTransactionIsolation(int v)
Set the value of defaultTransactionIsolation, which defines the state of
connections handed out from this pool.
|
void |
setDescription(java.lang.String v)
Set the description.
|
void |
setJndiEnvironment(java.lang.String key,
java.lang.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 |
setLogWriter(java.io.PrintWriter v)
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.
|
protected abstract void |
setupDefaults(java.sql.Connection con,
java.lang.String username) |
void |
setValidationQuery(java.lang.String validationQuery)
The SQL query that will be used to validate connections from this pool
before returning them to the caller.
|
protected javax.sql.ConnectionPoolDataSource |
testCPDS(java.lang.String username,
java.lang.String password) |
<T> T |
unwrap(java.lang.Class<T> iface) |
protected byte |
whenExhaustedAction(int maxActive,
int maxWait) |
private static final long serialVersionUID
private static final java.lang.String GET_CONNECTION_CALLED
private static final java.lang.String BAD_TRANSACTION_ISOLATION
protected static final int UNKNOWN_TRANSACTIONISOLATION
private volatile boolean getConnectionCalled
private javax.sql.ConnectionPoolDataSource dataSource
private java.lang.String dataSourceName
private boolean defaultAutoCommit
private int defaultTransactionIsolation
private boolean defaultReadOnly
private java.lang.String description
java.util.Properties jndiEnvironment
private int loginTimeout
private java.io.PrintWriter logWriter
private boolean _testOnBorrow
private boolean _testOnReturn
private int _timeBetweenEvictionRunsMillis
private int _numTestsPerEvictionRun
private int _minEvictableIdleTimeMillis
private boolean _testWhileIdle
private java.lang.String validationQuery
private boolean rollbackAfterValidation
private boolean testPositionSet
protected java.lang.String instanceKey
public InstanceKeyDataSource()
protected void assertInitializationAllowed() throws java.lang.IllegalStateException
java.lang.IllegalStateException
public abstract void close() throws java.lang.Exception
java.lang.Exception
protected abstract PooledConnectionManager getConnectionManager(UserPassKey upkey)
public boolean isWrapperFor(java.lang.Class<?> iface) throws java.sql.SQLException
isWrapperFor
in interface java.sql.Wrapper
java.sql.SQLException
public <T> T unwrap(java.lang.Class<T> iface) throws java.sql.SQLException
unwrap
in interface java.sql.Wrapper
java.sql.SQLException
public javax.sql.ConnectionPoolDataSource getConnectionPoolDataSource()
public void setConnectionPoolDataSource(javax.sql.ConnectionPoolDataSource v)
v
- Value to assign to connectionPoolDataSource.public java.lang.String getDataSourceName()
public void setDataSourceName(java.lang.String v)
v
- Value to assign to dataSourceName.public boolean isDefaultAutoCommit()
public void setDefaultAutoCommit(boolean v)
v
- Value to assign to defaultAutoCommit.public boolean isDefaultReadOnly()
public void setDefaultReadOnly(boolean v)
v
- Value to assign to defaultReadOnly.public int getDefaultTransactionIsolation()
public void setDefaultTransactionIsolation(int v)
v
- Value to assign to defaultTransactionIsolationpublic java.lang.String getDescription()
public void setDescription(java.lang.String v)
v
- Value to assign to description.public java.lang.String getJndiEnvironment(java.lang.String key)
public void setJndiEnvironment(java.lang.String key, java.lang.String value)
key
- the JNDI environment property to set.value
- the value assigned to specified JNDI environment property.public int getLoginTimeout()
getLoginTimeout
in interface javax.sql.CommonDataSource
public void setLoginTimeout(int v)
setLoginTimeout
in interface javax.sql.CommonDataSource
v
- Value to assign to loginTimeout.public java.io.PrintWriter getLogWriter()
getLogWriter
in interface javax.sql.CommonDataSource
public void setLogWriter(java.io.PrintWriter v)
setLogWriter
in interface javax.sql.CommonDataSource
v
- Value to assign to logWriter.public final boolean isTestOnBorrow()
getTestOnBorrow()
public boolean getTestOnBorrow()
setTestOnBorrow(boolean)
public void setTestOnBorrow(boolean testOnBorrow)
true
value to have any effect,
the validationQuery
property must be set to a non-null
string.getTestOnBorrow()
public final boolean isTestOnReturn()
getTestOnReturn()
public boolean getTestOnReturn()
setTestOnReturn(boolean)
public void setTestOnReturn(boolean testOnReturn)
true
value to have any effect,
the validationQuery
property must be set to a non-null
string.getTestOnReturn()
public int getTimeBetweenEvictionRunsMillis()
setTimeBetweenEvictionRunsMillis(int)
public void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)
getTimeBetweenEvictionRunsMillis()
public int getNumTestsPerEvictionRun()
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
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.
public int getMinEvictableIdleTimeMillis()
public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
public final boolean isTestWhileIdle()
getTestWhileIdle()
public boolean getTestWhileIdle()
public void setTestWhileIdle(boolean testWhileIdle)
true
value to have any effect,
the validationQuery
property must be set to a non-null
string.public java.lang.String getValidationQuery()
public void setValidationQuery(java.lang.String validationQuery)
public boolean isRollbackAfterValidation()
public void setRollbackAfterValidation(boolean rollbackAfterValidation)
rollbackAfterValidation
- new property valuepublic java.sql.Connection getConnection() throws java.sql.SQLException
getConnection
in interface javax.sql.DataSource
java.sql.SQLException
public java.sql.Connection getConnection(java.lang.String username, java.lang.String password) throws java.sql.SQLException
getPooledConnectionAndInfo(String, String)
with the provided username 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 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, 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.getConnection
in interface javax.sql.DataSource
java.sql.SQLException
protected abstract PooledConnectionAndInfo getPooledConnectionAndInfo(java.lang.String username, java.lang.String password) throws java.sql.SQLException
java.sql.SQLException
protected abstract void setupDefaults(java.sql.Connection con, java.lang.String username) throws java.sql.SQLException
java.sql.SQLException
private void closeDueToException(PooledConnectionAndInfo info)
protected javax.sql.ConnectionPoolDataSource testCPDS(java.lang.String username, java.lang.String password) throws javax.naming.NamingException, java.sql.SQLException
javax.naming.NamingException
java.sql.SQLException
protected byte whenExhaustedAction(int maxActive, int maxWait)
public javax.naming.Reference getReference() throws javax.naming.NamingException
InstanceKeyDataSource
subclasses
should override this method. The implementaion included below
is not robust and will be removed at the next major version DBCP
release.getReference
in interface javax.naming.Referenceable
javax.naming.NamingException
- If a naming exception was encountered
while retrieving the reference.