public abstract class InstanceKeyDataSource extends Object implements DataSource, Referenceable, 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 | 
|---|---|
| protected String | instanceKeyInstance key | 
| protected static int | UNKNOWN_TRANSACTIONISOLATIONInternal constant to indicate the level is not set. | 
| 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. | 
| Connection | getConnection()Attempt to establish a database connection. | 
| Connection | getConnection(String username,
             String password)Attempt to retrieve a database connection using  getPooledConnectionAndInfo(String, String)with the provided username and password. | 
| protected abstract org.apache.tomcat.dbcp.dbcp.datasources.PooledConnectionManager | getConnectionManager(org.apache.tomcat.dbcp.dbcp.datasources.UserPassKey upkey) | 
| ConnectionPoolDataSource | getConnectionPoolDataSource()Get the value of connectionPoolDataSource. | 
| 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. | 
| String | getDescription()Get the description. | 
| String | getJndiEnvironment(String key)Get the value of jndiEnvironment which is used when instantiating
 a jndi InitialContext. | 
| int | getLoginTimeout()Get the value of loginTimeout. | 
| 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). | 
| Logger | getParentLogger() | 
| protected abstract org.apache.tomcat.dbcp.dbcp.datasources.PooledConnectionAndInfo | getPooledConnectionAndInfo(String username,
                          String password) | 
| 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. | 
| 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(Class<?> iface) | 
| void | setConnectionPoolDataSource(ConnectionPoolDataSource v)Set the backend ConnectionPoolDataSource. | 
| void | setDataSourceName(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(String v)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 | setLogWriter(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(Connection con,
             String username) | 
| void | setValidationQuery(String validationQuery)The SQL query that will be used to validate connections from this pool
 before returning them to the caller. | 
| protected ConnectionPoolDataSource | testCPDS(String username,
        String password) | 
| <T> T | unwrap(Class<T> iface) | 
| protected byte | whenExhaustedAction(int maxActive,
                   int maxWait) | 
protected static final int UNKNOWN_TRANSACTIONISOLATION
protected String instanceKey
public InstanceKeyDataSource()
protected void assertInitializationAllowed()
                                    throws IllegalStateException
IllegalStateExceptionpublic abstract void close()
                    throws Exception
Exceptionprotected abstract org.apache.tomcat.dbcp.dbcp.datasources.PooledConnectionManager getConnectionManager(org.apache.tomcat.dbcp.dbcp.datasources.UserPassKey upkey)
public boolean isWrapperFor(Class<?> iface) throws SQLException
isWrapperFor in interface WrapperSQLExceptionpublic <T> T unwrap(Class<T> iface) throws SQLException
unwrap in interface WrapperSQLExceptionpublic Logger getParentLogger() throws SQLFeatureNotSupportedException
getParentLogger in interface CommonDataSourceSQLFeatureNotSupportedExceptionpublic ConnectionPoolDataSource getConnectionPoolDataSource()
public void setConnectionPoolDataSource(ConnectionPoolDataSource v)
v - Value to assign to connectionPoolDataSource.public String getDataSourceName()
public void setDataSourceName(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 String getDescription()
public void setDescription(String v)
v - Value to assign to description.public String getJndiEnvironment(String key)
public void setJndiEnvironment(String key, String value)
key - the JNDI environment property to set.value - the value assigned to specified JNDI environment property.public int getLoginTimeout()
getLoginTimeout in interface CommonDataSourcepublic void setLoginTimeout(int v)
setLoginTimeout in interface CommonDataSourcev - Value to assign to loginTimeout.public PrintWriter getLogWriter()
getLogWriter in interface CommonDataSourcepublic void setLogWriter(PrintWriter v)
setLogWriter in interface CommonDataSourcev - Value to assign to logWriter.public final boolean isTestOnBorrow()
getTestOnBorrow()public boolean getTestOnBorrow()
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.setTestOnBorrow(boolean)public void setTestOnBorrow(boolean testOnBorrow)
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 a 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()
true, objects will be
 {*link PoolableObjectFactory#validateObject validated}
 before being returned to the pool within the
 {*link #returnObject}.setTestOnReturn(boolean)public void setTestOnReturn(boolean testOnReturn)
true, objects will be
 {*link PoolableObjectFactory#validateObject validated}
 before being returned to the pool within the
 {*link #returnObject}. For a true value to have any effect,
 the validationQuery property must be set to a non-null
 string.getTestOnReturn()public int getTimeBetweenEvictionRunsMillis()
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()
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.public void setTestWhileIdle(boolean testWhileIdle)
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 a
 true value to have any effect,
 the validationQuery property must be set to a non-null
 string.public String getValidationQuery()
public void setValidationQuery(String validationQuery)
public boolean isRollbackAfterValidation()
public void setRollbackAfterValidation(boolean rollbackAfterValidation)
rollbackAfterValidation - new property valuepublic Connection getConnection() throws SQLException
getConnection in interface DataSourceSQLExceptionpublic Connection getConnection(String username, String password) throws 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 DataSourceSQLExceptionprotected abstract org.apache.tomcat.dbcp.dbcp.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String username, String password) throws SQLException
SQLExceptionprotected abstract void setupDefaults(Connection con, String username) throws SQLException
SQLExceptionprotected ConnectionPoolDataSource testCPDS(String username, String password) throws NamingException, SQLException
NamingExceptionSQLExceptionprotected byte whenExhaustedAction(int maxActive,
                       int maxWait)
public Reference getReference() throws 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 ReferenceableNamingException - If a naming exception was encountered
      while retrieving the reference.Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.