Package org.apache.tomcat.dbcp.dbcp2.datasources

Class InstanceKeyDataSource

java.lang.Object
org.apache.tomcat.dbcp.dbcp2.datasources.InstanceKeyDataSource
All Implemented Interfaces:
Serializable, AutoCloseable, Wrapper, Referenceable, CommonDataSource, DataSource
Direct Known Subclasses:
PerUserPoolDataSource, SharedPoolDataSource
public abstract class InstanceKeyDataSource extends Object implements DataSource, Referenceable, Serializable, AutoCloseable

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-dbcp2.

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.

Since:
2.0
See Also:

  • Field Details

    • UNKNOWN_TRANSACTIONISOLATION

      protected static final int UNKNOWN_TRANSACTIONISOLATION
      Internal constant to indicate the level is not set.
      See Also:

  • Constructor Details

    • InstanceKeyDataSource

      public InstanceKeyDataSource()
      Default no-arg constructor for Serialization.

  • Method Details

    • assertInitializationAllowed

      protected void assertInitializationAllowed() throws IllegalStateException
      Throws an IllegalStateException, if a PooledConnection has already been requested.
      Throws:
      IllegalStateException - Thrown if a PooledConnection has already been requested.

    • close

      public abstract void close() throws Exception
      Closes the connection pool being maintained by this datasource.
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception

    • getConnectionManager

      protected abstract org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionManager getConnectionManager(org.apache.tomcat.dbcp.dbcp2.datasources.UserPassKey upkey)

    • isWrapperFor

      public boolean isWrapperFor(Class<?> iface) throws SQLException
      Specified by:
      isWrapperFor in interface Wrapper
      Throws:
      SQLException

    • unwrap

      public <T> T unwrap(Class<T> iface) throws SQLException
      Specified by:
      unwrap in interface Wrapper
      Throws:
      SQLException

    • getParentLogger

      public Logger getParentLogger() throws SQLFeatureNotSupportedException
      Specified by:
      getParentLogger in interface CommonDataSource
      Throws:
      SQLFeatureNotSupportedException

    • getDefaultBlockWhenExhausted

      public boolean getDefaultBlockWhenExhausted()
      Gets the default value for BaseObjectPoolConfig.getBlockWhenExhausted() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getBlockWhenExhausted() for each per user pool.

    • setDefaultBlockWhenExhausted

      public void setDefaultBlockWhenExhausted(boolean blockWhenExhausted)
      Sets the default value for BaseObjectPoolConfig.getBlockWhenExhausted() for each per user pool.
      Parameters:
      blockWhenExhausted - The default value for BaseObjectPoolConfig.getBlockWhenExhausted() for each per user pool.

    • getDefaultEvictionPolicyClassName

      public String getDefaultEvictionPolicyClassName()
      Gets the default value for BaseObjectPoolConfig.getEvictionPolicyClassName() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getEvictionPolicyClassName() for each per user pool.

    • setDefaultEvictionPolicyClassName

      public void setDefaultEvictionPolicyClassName(String evictionPolicyClassName)
      Sets the default value for BaseObjectPoolConfig.getEvictionPolicyClassName() for each per user pool.
      Parameters:
      evictionPolicyClassName - The default value for BaseObjectPoolConfig.getEvictionPolicyClassName() for each per user pool.

    • getDefaultLifo

      public boolean getDefaultLifo()
      Gets the default value for BaseObjectPoolConfig.getLifo() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getLifo() for each per user pool.

    • setDefaultLifo

      public void setDefaultLifo(boolean lifo)
      Sets the default value for BaseObjectPoolConfig.getLifo() for each per user pool.
      Parameters:
      lifo - The default value for BaseObjectPoolConfig.getLifo() for each per user pool.

    • getDefaultMaxIdle

      public int getDefaultMaxIdle()
      Gets the default value for GenericKeyedObjectPoolConfig.getMaxIdlePerKey() for each per user pool.
      Returns:
      The default value for GenericKeyedObjectPoolConfig.getMaxIdlePerKey() for each per user pool.

    • setDefaultMaxIdle

      public void setDefaultMaxIdle(int maxIdle)
      Sets the default value for GenericKeyedObjectPoolConfig.getMaxIdlePerKey() for each per user pool.
      Parameters:
      maxIdle - The default value for GenericKeyedObjectPoolConfig.getMaxIdlePerKey() for each per user pool.

    • getDefaultMaxTotal

      public int getDefaultMaxTotal()
      Gets the default value for GenericKeyedObjectPoolConfig.getMaxTotalPerKey() for each per user pool.
      Returns:
      The default value for GenericKeyedObjectPoolConfig.getMaxTotalPerKey() for each per user pool.

    • setDefaultMaxTotal

      public void setDefaultMaxTotal(int maxTotal)
      Sets the default value for GenericKeyedObjectPoolConfig.getMaxTotalPerKey() for each per user pool.
      Parameters:
      maxTotal - The default value for GenericKeyedObjectPoolConfig.getMaxTotalPerKey() for each per user pool.

    • getDefaultMaxWaitMillis

      public long getDefaultMaxWaitMillis()
      Gets the default value for BaseObjectPoolConfig.getMaxWaitMillis() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getMaxWaitMillis() for each per user pool.

    • setDefaultMaxWaitMillis

      public void setDefaultMaxWaitMillis(long maxWaitMillis)
      Sets the default value for BaseObjectPoolConfig.getMaxWaitMillis() for each per user pool.
      Parameters:
      maxWaitMillis - The default value for BaseObjectPoolConfig.getMaxWaitMillis() for each per user pool.

    • getDefaultMinEvictableIdleTimeMillis

      public long getDefaultMinEvictableIdleTimeMillis()
      Gets the default value for BaseObjectPoolConfig.getMinEvictableIdleTimeMillis() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getMinEvictableIdleTimeMillis() for each per user pool.

    • setDefaultMinEvictableIdleTimeMillis

      public void setDefaultMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
      Sets the default value for BaseObjectPoolConfig.getMinEvictableIdleTimeMillis() for each per user pool.
      Parameters:
      minEvictableIdleTimeMillis - The default value for BaseObjectPoolConfig.getMinEvictableIdleTimeMillis() for each per user pool.

    • getDefaultMinIdle

      public int getDefaultMinIdle()
      Gets the default value for GenericKeyedObjectPoolConfig.getMinIdlePerKey() for each per user pool.
      Returns:
      The default value for GenericKeyedObjectPoolConfig.getMinIdlePerKey() for each per user pool.

    • setDefaultMinIdle

      public void setDefaultMinIdle(int minIdle)
      Sets the default value for GenericKeyedObjectPoolConfig.getMinIdlePerKey() for each per user pool.
      Parameters:
      minIdle - The default value for GenericKeyedObjectPoolConfig.getMinIdlePerKey() for each per user pool.

    • getDefaultNumTestsPerEvictionRun

      public int getDefaultNumTestsPerEvictionRun()
      Gets the default value for BaseObjectPoolConfig.getNumTestsPerEvictionRun() for each per user pool.
      Returns:
      The default value for BaseObjectPoolConfig.getNumTestsPerEvictionRun() for each per user pool.

    • setDefaultNumTestsPerEvictionRun

      public void setDefaultNumTestsPerEvictionRun(int numTestsPerEvictionRun)
      Sets the default value for BaseObjectPoolConfig.getNumTestsPerEvictionRun() for each per user pool.
      Parameters:
      numTestsPerEvictionRun - The default value for BaseObjectPoolConfig.getNumTestsPerEvictionRun() for each per user pool.

    • getDefaultSoftMinEvictableIdleTimeMillis

      public long getDefaultSoftMinEvictableIdleTimeMillis()
      Gets the default value for GenericObjectPool#getSoftMinEvictableIdleTimeMillis() for each per user pool.
      Returns:
      The default value for GenericObjectPool#getSoftMinEvictableIdleTimeMillis() for each per user pool.

    • setDefaultSoftMinEvictableIdleTimeMillis

      public void setDefaultSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
      Sets the default value for GenericObjectPool#getSoftMinEvictableIdleTimeMillis() for each per user pool.
      Parameters:
      softMinEvictableIdleTimeMillis - The default value for GenericObjectPool#getSoftMinEvictableIdleTimeMillis() for each per user pool.

    • getDefaultTestOnCreate

      public boolean getDefaultTestOnCreate()
      Gets the default value for GenericObjectPool#getTestOnCreate() for each per user pool.
      Returns:
      The default value for GenericObjectPool#getTestOnCreate() for each per user pool.

    • setDefaultTestOnCreate

      public void setDefaultTestOnCreate(boolean testOnCreate)
      Sets the default value for GenericObjectPool#getTestOnCreate() for each per user pool.
      Parameters:
      testOnCreate - The default value for GenericObjectPool#getTestOnCreate() for each per user pool.

    • getDefaultTestOnBorrow

      public boolean getDefaultTestOnBorrow()
      Gets the default value for GenericObjectPool#getTestOnBorrow() for each per user pool.
      Returns:
      The default value for GenericObjectPool#getTestOnBorrow() for each per user pool.

    • setDefaultTestOnBorrow

      public void setDefaultTestOnBorrow(boolean testOnBorrow)
      Sets the default value for GenericObjectPool#getTestOnBorrow() for each per user pool.
      Parameters:
      testOnBorrow - The default value for GenericObjectPool#getTestOnBorrow() for each per user pool.

    • getDefaultTestOnReturn

      public boolean getDefaultTestOnReturn()
      Gets the default value for GenericObjectPool#getTestOnReturn() for each per user pool.
      Returns:
      The default value for GenericObjectPool#getTestOnReturn() for each per user pool.

    • setDefaultTestOnReturn

      public void setDefaultTestOnReturn(boolean testOnReturn)
      Sets the default value for GenericObjectPool#getTestOnReturn() for each per user pool.
      Parameters:
      testOnReturn - The default value for GenericObjectPool#getTestOnReturn() for each per user pool.

    • getDefaultTestWhileIdle

      public boolean getDefaultTestWhileIdle()
      Gets the default value for GenericObjectPool#getTestWhileIdle() for each per user pool.
      Returns:
      The default value for GenericObjectPool#getTestWhileIdle() for each per user pool.

    • setDefaultTestWhileIdle

      public void setDefaultTestWhileIdle(boolean testWhileIdle)
      Sets the default value for GenericObjectPool#getTestWhileIdle() for each per user pool.
      Parameters:
      testWhileIdle - The default value for GenericObjectPool#getTestWhileIdle() for each per user pool.

    • getDefaultTimeBetweenEvictionRunsMillis

      public long getDefaultTimeBetweenEvictionRunsMillis()
      Gets the default value for GenericObjectPool#getTimeBetweenEvictionRunsMillis () for each per user pool.
      Returns:
      The default value for GenericObjectPool#getTimeBetweenEvictionRunsMillis () for each per user pool.

    • setDefaultTimeBetweenEvictionRunsMillis

      public void setDefaultTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
      Sets the default value for GenericObjectPool#getTimeBetweenEvictionRunsMillis () for each per user pool.
      Parameters:
      timeBetweenEvictionRunsMillis - The default value for GenericObjectPool#getTimeBetweenEvictionRunsMillis () for each per user pool.

    • getConnectionPoolDataSource

      public ConnectionPoolDataSource getConnectionPoolDataSource()
      Gets the value of connectionPoolDataSource. This method will return null, if the backing data source is being accessed via JNDI.
      Returns:
      value of connectionPoolDataSource.

    • setConnectionPoolDataSource

      public void setConnectionPoolDataSource(ConnectionPoolDataSource dataSource)
      Sets the back end ConnectionPoolDataSource. This property should not be set if using JNDI to access the data source.
      Parameters:
      dataSource - Value to assign to connectionPoolDataSource.

    • getDataSourceName

      public String getDataSourceName()
      Gets the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the data source from a JNDI service provider.
      Returns:
      value of dataSourceName.

    • setDataSourceName

      public void setDataSourceName(String dataSourceName)
      Sets the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the data source from a JNDI service provider.
      Parameters:
      dataSourceName - Value to assign to dataSourceName.

    • isDefaultAutoCommit

      public Boolean isDefaultAutoCommit()
      Gets 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 null which will use the default value for the drive.
      Returns:
      value of defaultAutoCommit.

    • setDefaultAutoCommit

      public void setDefaultAutoCommit(Boolean defaultAutoCommit)
      Sets 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 null which will use the default value for the drive.
      Parameters:
      defaultAutoCommit - Value to assign to defaultAutoCommit.

    • isDefaultReadOnly

      public Boolean isDefaultReadOnly()
      Gets 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 null which will use the default value for the drive.
      Returns:
      value of defaultReadOnly.

    • setDefaultReadOnly

      public void setDefaultReadOnly(Boolean defaultReadOnly)
      Sets 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 null which will use the default value for the drive.
      Parameters:
      defaultReadOnly - Value to assign to defaultReadOnly.

    • getDefaultTransactionIsolation

      public int getDefaultTransactionIsolation()
      Gets 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 defaultTransactionIsolation)
      Sets 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:
      defaultTransactionIsolation - Value to assign to defaultTransactionIsolation

    • getDescription

      public String getDescription()
      Gets 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

      public void setDescription(String description)
      Sets 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:
      description - Value to assign to description.

    • getInstanceKey

      protected String getInstanceKey()

    • getJndiEnvironment

      public String getJndiEnvironment(String key)
      Gets the value of jndiEnvironment which is used when instantiating a JNDI InitialContext. This InitialContext is used to locate the back end ConnectionPoolDataSource.
      Parameters:
      key - JNDI environment key.
      Returns:
      value of jndiEnvironment.

    • setJndiEnvironment

      public void setJndiEnvironment(String key, String value)
      Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext. This InitialContext is used to locate the back end ConnectionPoolDataSource.
      Parameters:
      key - the JNDI environment property to set.
      value - the value assigned to specified JNDI environment property.

    • getLoginTimeout

      public int getLoginTimeout()
      Gets the value of loginTimeout.
      Specified by:
      getLoginTimeout in interface CommonDataSource
      Specified by:
      getLoginTimeout in interface DataSource
      Returns:
      value of loginTimeout.

    • setLoginTimeout

      public void setLoginTimeout(int loginTimeout)
      Sets the value of loginTimeout.
      Specified by:
      setLoginTimeout in interface CommonDataSource
      Specified by:
      setLoginTimeout in interface DataSource
      Parameters:
      loginTimeout - Value to assign to loginTimeout.

    • getLogWriter

      public PrintWriter getLogWriter()
      Gets the value of logWriter.
      Specified by:
      getLogWriter in interface CommonDataSource
      Specified by:
      getLogWriter in interface DataSource
      Returns:
      value of logWriter.

    • setLogWriter

      public void setLogWriter(PrintWriter logWriter)
      Sets the value of logWriter.
      Specified by:
      setLogWriter in interface CommonDataSource
      Specified by:
      setLogWriter in interface DataSource
      Parameters:
      logWriter - Value to assign to logWriter.

    • getValidationQuery

      public String getValidationQuery()
      Gets 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 not specified, Connection.isValid(int) will be used to validate connections.
      Returns:
      The SQL query that will be used to validate connections from this pool before returning them to the caller.

    • setValidationQuery

      public void setValidationQuery(String validationQuery)
      Sets 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 not specified, connections will be validated using Connection.isValid(int).
      Parameters:
      validationQuery - The SQL query that will be used to validate connections from this pool before returning them to the caller.

    • getValidationQueryTimeout

      public int getValidationQueryTimeout()
      Returns the timeout in seconds before the validation query fails.
      Returns:
      The timeout in seconds before the validation query fails.

    • setValidationQueryTimeout

      public void setValidationQueryTimeout(int validationQueryTimeoutSeconds)
      Sets the timeout in seconds before the validation query fails.
      Parameters:
      validationQueryTimeoutSeconds - The new timeout in seconds

    • 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

    • 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

    • getMaxConnLifetimeMillis

      public long getMaxConnLifetimeMillis()
      Returns the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.
      Returns:
      The maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

    • setMaxConnLifetimeMillis

      public void setMaxConnLifetimeMillis(long maxConnLifetimeMillis)

      Sets the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

      Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

      Parameters:
      maxConnLifetimeMillis - The maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an infinite lifetime.

    • getConnection

      public Connection getConnection() throws SQLException
      Attempts to establish a database connection.
      Specified by:
      getConnection in interface DataSource
      Throws:
      SQLException

    • getConnection

      public Connection getConnection(String userName, String userPassword) throws SQLException
      Attempts to retrieve a database connection using getPooledConnectionAndInfo(String, String) with the provided user name 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 user name 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.
      Specified by:
      getConnection in interface DataSource
      Throws:
      SQLException

    • getPooledConnectionAndInfo

      protected abstract org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String userName, String userPassword) throws SQLException
      Throws:
      SQLException

    • setupDefaults

      protected abstract void setupDefaults(Connection connection, String userName) throws SQLException
      Throws:
      SQLException

    • testCPDS

      protected ConnectionPoolDataSource testCPDS(String userName, String userPassword) throws NamingException, SQLException
      Throws:
      NamingException
      SQLException

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Since:
      2.6.0

    • toStringFields

      protected void toStringFields(StringBuilder builder)