Class 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:
    Serialized Form
    • Field Detail

      • UNKNOWN_TRANSACTIONISOLATION

        protected static final int UNKNOWN_TRANSACTIONISOLATION
        Internal constant to indicate the level is not set.
        See Also:
        Constant Field Values
    • Constructor Detail

      • InstanceKeyDataSource

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

      • 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
      • 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
      • getConnectionManager

        protected abstract org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionManager getConnectionManager​(org.apache.tomcat.dbcp.dbcp2.datasources.UserPassKey upkey)
      • 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.
      • 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.
      • getDefaultTimeBetweenEvictionRunsMillis

        @Deprecated
        public long getDefaultTimeBetweenEvictionRunsMillis()
        Gets the default value for () for each per user pool.
        Returns:
        The default value for () for each per user pool.
      • 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.
      • 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.
      • getInstanceKey

        protected String getInstanceKey()
        Gets the instance key.
        Returns:
        the instance key.
      • 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.
      • getLoginTimeoutDuration

        public Duration getLoginTimeoutDuration()
        Gets the value of loginTimeout.
        Returns:
        value of loginTimeout.
        Since:
        2.10.0
      • getMaxConnDuration

        public Duration getMaxConnDuration()
        Gets the maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
        Returns:
        The maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
        Since:
        2.10.0
      • getMaxConnLifetime

        @Deprecated
        public Duration getMaxConnLifetime()
        Deprecated.
        Gets the maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
        Returns:
        The maximum permitted lifetime of a connection. A value of zero or less indicates an infinite lifetime.
      • getMaxConnLifetimeMillis

        @Deprecated
        public long getMaxConnLifetimeMillis()
        Deprecated.
        Gets 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.
      • getPooledConnectionAndInfo

        protected abstract org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo​(String userName,
                                                                                                                       String userPassword)
                                                                                                                throws SQLException
        This method is protected but can only be implemented in this package because PooledConnectionAndInfo is a package private type.
        Parameters:
        userName - The user name.
        userPassword - The user password.
        Returns:
        Matching PooledConnectionAndInfo.
        Throws:
        SQLException - Connection or registration failure.
      • 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.
      • getValidationQueryTimeout

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

        public Duration getValidationQueryTimeoutDuration()
        Returns the timeout Duration before the validation query fails.
        Returns:
        The timeout Duration before the validation query fails.
      • 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.
      • 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.
      • 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
      • 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.
      • 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.
      • 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.
      • setDefaultDurationBetweenEvictionRuns

        public void setDefaultDurationBetweenEvictionRuns​(Duration defaultDurationBetweenEvictionRuns)
        Sets the default value for () for each per user pool.
        Parameters:
        defaultDurationBetweenEvictionRuns - The default value for () for each per user pool.
        Since:
        2.10.0
      • 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.
      • 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
      • 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.
      • 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.
      • setLoginTimeout

        public void setLoginTimeout​(Duration loginTimeout)
        Sets the value of loginTimeout.
        Parameters:
        loginTimeout - Value to assign to loginTimeout.
        Since:
        2.10.0
      • setMaxConnLifetime

        public void setMaxConnLifetime​(Duration maxConnLifetimeMillis)

        Sets the maximum permitted lifetime of a connection. 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. A value of zero or less indicates an infinite lifetime.
        Since:
        2.9.0
      • setMaxConnLifetimeMillis

        @Deprecated
        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.
      • 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
      • 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.
      • setValidationQueryTimeout

        public void setValidationQueryTimeout​(Duration validationQueryTimeoutDuration)
        Sets the timeout duration before the validation query fails.
        Parameters:
        validationQueryTimeoutDuration - The new timeout duration.
      • setValidationQueryTimeout

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

        protected void toStringFields​(StringBuilder builder)