Package org.apache.tomcat.dbcp.dbcp2

Class BasicDataSource

  • All Implemented Interfaces:
    java.lang.AutoCloseable, java.sql.Wrapper, javax.management.MBeanRegistration, javax.sql.CommonDataSource, javax.sql.DataSource, BasicDataSourceMXBean, DataSourceMXBean
    Direct Known Subclasses:
    BasicManagedDataSource
    public class BasicDataSource
extends java.lang.Object
implements javax.sql.DataSource, BasicDataSourceMXBean, javax.management.MBeanRegistration, java.lang.AutoCloseable
    Basic implementation of javax.sql.DataSource that is configured via JavaBeans properties.

    This is not the only way to combine the commons-dbcp2 and commons-pool2 packages, but provides a one-stop solution for basic requirements.

    Since:
    2.0

    • Constructor Detail

      • BasicDataSource

        public BasicDataSource()

    • Method Detail

      • validateConnectionFactory

        protected static void validateConnectionFactory​(PoolableConnectionFactory connectionFactory)
                                         throws java.lang.Exception
        Validates the given factory.
        Parameters:
        connectionFactory - the factory
        Throws:
        java.lang.Exception - Thrown by one of the factory methods while managing a temporary pooled object.

      • addConnectionProperty

        public void addConnectionProperty​(java.lang.String name,
                                  java.lang.String value)
        Adds a custom connection property to the set that will be passed to our JDBC driver. This MUST be called before the first connection is retrieved (along with all the other configuration property setters). Calls to this method after the connection pool has been initialized have no effect.
        Parameters:
        name - Name of the custom connection property
        value - Value of the custom connection property

      • close

        public void close()
           throws java.sql.SQLException
        Closes and releases all idle connections that are currently stored in the connection pool associated with this data source.

        Connections that are checked out to clients when this method is invoked are not affected. When client applications subsequently invoke Connection.close() to return these connections to the pool, the underlying JDBC connections are closed.

        Attempts to acquire connections using getConnection() after this method has been invoked result in SQLExceptions. To reopen a datasource that has been closed using this method, use start().

        This method is idempotent - i.e., closing an already closed BasicDataSource has no effect and does not generate exceptions.

        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.sql.SQLException - if an error occurs closing idle connections

      • createConnectionFactory

        protected ConnectionFactory createConnectionFactory()
                                             throws java.sql.SQLException
        Creates a JDBC connection factory for this data source. The JDBC driver is loaded using the following algorithm:
        1. If a Driver instance has been specified via setDriver(Driver) use it
        2. If no Driver instance was specified and {code driverClassName} is specified that class is loaded using the ClassLoader of this class or, if {code driverClassLoader} is set, {code driverClassName} is loaded with the specified ClassLoader.
        3. If {code driverClassName} is specified and the previous attempt fails, the class is loaded using the context class loader of the current thread.
        4. If a driver still isn't loaded one is loaded via the DriverManager using the specified {code url}.

        This method exists so subclasses can replace the implementation class.

        Returns:
        A new connection factory.
        Throws:
        java.sql.SQLException - If the connection factory cannot be created

      • createConnectionPool

        protected void createConnectionPool​(PoolableConnectionFactory factory)
        Creates a connection pool for this datasource. This method only exists so subclasses can replace the implementation class.

        This implementation configures all pool properties other than timeBetweenEvictionRunsMillis. Setting that property is deferred to startPoolMaintenance(), since setting timeBetweenEvictionRunsMillis to a positive value causes GenericObjectPool's eviction timer to be started.

        Parameters:
        factory - The factory to use to create new connections for this pool.

      • createDataSource

        protected javax.sql.DataSource createDataSource()
                                         throws java.sql.SQLException
        Creates (if necessary) and return the internal data source we are using to manage our connections.
        Returns:
        The current internal DataSource or a newly created instance if it has not yet been created.
        Throws:
        java.sql.SQLException - if the object pool cannot be created.

      • createDataSourceInstance

        protected javax.sql.DataSource createDataSourceInstance()
                                                 throws java.sql.SQLException
        Creates the actual data source instance. This method only exists so that subclasses can replace the implementation class.
        Returns:
        A new DataSource instance
        Throws:
        java.sql.SQLException - if unable to create a datasource instance

      • createPoolableConnectionFactory

        protected PoolableConnectionFactory createPoolableConnectionFactory​(ConnectionFactory driverConnectionFactory)
                                                             throws java.sql.SQLException
        Creates the PoolableConnectionFactory and attaches it to the connection pool. This method only exists so subclasses can replace the default implementation.
        Parameters:
        driverConnectionFactory - JDBC connection factory
        Returns:
        A new PoolableConnectionFactory configured with the current configuration of this BasicDataSource
        Throws:
        java.sql.SQLException - if an error occurs creating the PoolableConnectionFactory

      • evict

        public void evict()
           throws java.lang.Exception
        Manually evicts idle connections
        Throws:
        java.lang.Exception - when there is a problem evicting idle objects.

      • getAbandonedLogWriter

        public java.io.PrintWriter getAbandonedLogWriter()
        Gets the print writer used by this configuration to log information on abandoned objects.
        Returns:
        The print writer used by this configuration to log information on abandoned objects.

      • getAbandonedUsageTracking

        public boolean getAbandonedUsageTracking()
        If the connection pool implements UsageTracking, should the connection pool record a stack trace every time a method is called on a pooled connection and retain the most recent stack trace to aid debugging of abandoned connections?
        Specified by:
        getAbandonedUsageTracking in interface DataSourceMXBean
        Returns:
        true if usage tracking is enabled

      • getAutoCommitOnReturn

        public boolean getAutoCommitOnReturn()
        Gets the value of the flag that controls whether or not connections being returned to the pool will be checked and configured with Connection.setAutoCommit(true) if the auto commit setting is false when the connection is returned. It is true by default.
        Returns:
        Whether or not connections being returned to the pool will be checked and configured with auto-commit.

      • getCacheState

        public boolean getCacheState()
        Gets the state caching flag.
        Specified by:
        getCacheState in interface DataSourceMXBean
        Returns:
        the state caching flag

      • getConnection

        public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
        Creates (if necessary) and return a connection to the database.
        Specified by:
        getConnection in interface javax.sql.DataSource
        Returns:
        a database connection
        Throws:
        java.sql.SQLException - if a database access error occurs

      • getConnection

        public java.sql.Connection getConnection​(java.lang.String user,
                                         java.lang.String pass)
                                  throws java.sql.SQLException
        BasicDataSource does NOT support this method.
        Specified by:
        getConnection in interface javax.sql.DataSource
        Parameters:
        user - Database user on whose behalf the Connection is being made
        pass - The database user's password
        Returns:
        nothing - always throws UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException - always thrown.
        java.sql.SQLException - if a database access error occurs

      • getConnectionFactoryClassName

        public java.lang.String getConnectionFactoryClassName()
        Gets the ConnectionFactoryClassName that has been configured for use by this pool.

        Note: This getter only returns the last value set by a call to setConnectionFactoryClassName(String).

        Returns:
        the ConnectionFactoryClassName that has been configured for use by this pool.
        Since:
        2.7.0

      • getConnectionInitSqls

        public java.util.List<java.lang.String> getConnectionInitSqls()
        Gets the list of SQL statements executed when a physical connection is first created. Returns an empty list if there are no initialization statements configured.
        Returns:
        initialization SQL statements

      • getDefaultAutoCommit

        public java.lang.Boolean getDefaultAutoCommit()
        Gets the default auto-commit property.
        Specified by:
        getDefaultAutoCommit in interface DataSourceMXBean
        Returns:
        true if default auto-commit is enabled

      • getDefaultCatalog

        public java.lang.String getDefaultCatalog()
        Gets the default catalog.
        Specified by:
        getDefaultCatalog in interface DataSourceMXBean
        Returns:
        the default catalog

      • getDefaultQueryTimeout

        @Deprecated
public java.lang.Integer getDefaultQueryTimeout()
        Deprecated.
        Use getDefaultQueryTimeoutDuration().
        Gets the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.
        Returns:
        The default query timeout in seconds.

      • getDefaultQueryTimeoutDuration

        public java.time.Duration getDefaultQueryTimeoutDuration()
        Gets the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.
        Returns:
        The default query timeout Duration.
        Since:
        2.10.0

      • getDefaultReadOnly

        public java.lang.Boolean getDefaultReadOnly()
        Gets the default readOnly property.
        Specified by:
        getDefaultReadOnly in interface DataSourceMXBean
        Returns:
        true if connections are readOnly by default

      • getDefaultSchema

        public java.lang.String getDefaultSchema()
        Gets the default schema.
        Specified by:
        getDefaultSchema in interface DataSourceMXBean
        Returns:
        the default schema.
        Since:
        2.5.0

      • getDefaultTransactionIsolation

        public int getDefaultTransactionIsolation()
        Gets the default transaction isolation state of returned connections.
        Specified by:
        getDefaultTransactionIsolation in interface DataSourceMXBean
        Returns:
        the default value for transaction isolation state
        See Also:
        Connection.getTransactionIsolation()

      • getDisconnectionSqlCodes

        public java.util.Set<java.lang.String> getDisconnectionSqlCodes()
        Gets the set of SQL_STATE codes considered to signal fatal conditions.
        Returns:
        fatal disconnection state codes
        Since:
        2.1
        See Also:
        setDisconnectionSqlCodes(Collection)

      • getDriver

        public java.sql.Driver getDriver()
        Gets the JDBC Driver that has been configured for use by this pool.

        Note: This getter only returns the last value set by a call to setDriver(Driver). It does not return any driver instance that may have been created from the value set via setDriverClassName(String).

        Returns:
        the JDBC Driver that has been configured for use by this pool

      • getDriverClassLoader

        public java.lang.ClassLoader getDriverClassLoader()
        Gets the class loader specified for loading the JDBC driver. Returns null if no class loader has been explicitly specified.

        Note: This getter only returns the last value set by a call to setDriverClassLoader(ClassLoader). It does not return the class loader of any driver that may have been set via setDriver(Driver).

        Returns:
        The class loader specified for loading the JDBC driver.

      • getDriverClassName

        public java.lang.String getDriverClassName()
        Gets the JDBC driver class name.

        Note: This getter only returns the last value set by a call to setDriverClassName(String). It does not return the class name of any driver that may have been set via setDriver(Driver).

        Specified by:
        getDriverClassName in interface DataSourceMXBean
        Returns:
        the JDBC driver class name

      • getEnableAutoCommitOnReturn

        @Deprecated
public boolean getEnableAutoCommitOnReturn()
        Deprecated.
        Use getAutoCommitOnReturn().
        Gets the value of the flag that controls whether or not connections being returned to the pool will be checked and configured with Connection.setAutoCommit(true) if the auto commit setting is false when the connection is returned. It is true by default.
        Returns:
        Whether or not connections being returned to the pool will be checked and configured with auto-commit.

      • getEvictionPolicyClassName

        public java.lang.String getEvictionPolicyClassName()
        Gets the EvictionPolicy implementation in use with this connection pool.
        Returns:
        The EvictionPolicy implementation in use with this connection pool.

      • getFastFailValidation

        public boolean getFastFailValidation()
        True means that validation will fail immediately for connections that have previously thrown SQLExceptions with SQL_STATE indicating fatal disconnection errors.
        Specified by:
        getFastFailValidation in interface DataSourceMXBean
        Returns:
        true if connections created by this datasource will fast fail validation.
        Since:
        2.1
        See Also:
        setDisconnectionSqlCodes(Collection)

      • getInitialSize

        public int getInitialSize()
        Gets the initial size of the connection pool.
        Specified by:
        getInitialSize in interface DataSourceMXBean
        Returns:
        the number of connections created when the pool is initialized

      • getJmxName

        public java.lang.String getJmxName()
        Gets the JMX name that has been requested for this DataSource. If the requested name is not valid, an alternative may be chosen.
        Returns:
        The JMX name that has been requested for this DataSource.

      • getLifo

        public boolean getLifo()
        Gets the LIFO property.
        Specified by:
        getLifo in interface DataSourceMXBean
        Returns:
        true if connection pool behaves as a LIFO queue.

      • getLogAbandoned

        public boolean getLogAbandoned()
        Flag to log stack traces for application code which abandoned a Statement or Connection.

        Defaults to false.

        Logging of abandoned Statements and Connections adds overhead for every Connection open or new Statement because a stack trace has to be generated.

        Specified by:
        getLogAbandoned in interface DataSourceMXBean
        Returns:
        getLogAbandoned().

      • getLoginTimeout

        public int getLoginTimeout()
                    throws java.sql.SQLException
        BasicDataSource does NOT support this method.

        Gets the login timeout (in seconds) for connecting to the database.

        Calls createDataSource(), so has the side effect of initializing the connection pool.

        Specified by:
        getLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        getLoginTimeout in interface javax.sql.DataSource
        Returns:
        login timeout in seconds
        Throws:
        java.sql.SQLException - if a database access error occurs
        java.lang.UnsupportedOperationException - If the DataSource implementation does not support the login timeout feature.

      • getLogWriter

        public java.io.PrintWriter getLogWriter()
                                 throws java.sql.SQLException
        Gets the log writer being used by this data source.

        Calls createDataSource(), so has the side effect of initializing the connection pool.

        Specified by:
        getLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        getLogWriter in interface javax.sql.DataSource
        Returns:
        log writer in use
        Throws:
        java.sql.SQLException - if a database access error occurs

      • getMaxConnDuration

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

      • getMaxIdle

        public int getMaxIdle()
        Gets the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed on return to the pool.

        A negative value indicates that there is no limit

        Specified by:
        getMaxIdle in interface DataSourceMXBean
        Returns:
        the maximum number of idle connections

      • getMaxOpenPreparedStatements

        public int getMaxOpenPreparedStatements()
        Gets the value of the maxOpenPreparedStatements property.
        Specified by:
        getMaxOpenPreparedStatements in interface DataSourceMXBean
        Returns:
        the maximum number of open statements

      • getMaxTotal

        public int getMaxTotal()
        Gets the maximum number of active connections that can be allocated at the same time.

        A negative number means that there is no limit.

        Specified by:
        getMaxTotal in interface DataSourceMXBean
        Returns:
        the maximum number of active connections

      • getMaxWaitDuration

        public java.time.Duration getMaxWaitDuration()
        Gets the maximum Duration that the pool will wait for a connection to be returned before throwing an exception. A value less than or equal to zero means the pool is set to wait indefinitely.
        Returns:
        the maxWaitDuration property value.
        Since:
        2.10.0

      • getMaxWaitMillis

        @Deprecated
public long getMaxWaitMillis()
        Deprecated.
        Use getMaxWaitDuration().
        Gets the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception. A value less than or equal to zero means the pool is set to wait indefinitely.
        Specified by:
        getMaxWaitMillis in interface DataSourceMXBean
        Returns:
        the maxWaitMillis property value.

      • getMinEvictableIdleDuration

        public java.time.Duration getMinEvictableIdleDuration()
        Gets the {code minEvictableIdleDuration} property.
        Returns:
        the value of the {code minEvictableIdleDuration} property
        Since:
        2.10.0
        See Also:
        setMinEvictableIdle(Duration)

      • getMinIdle

        public int getMinIdle()
        Gets the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections are available when the idle object evictor runs. The value of this property has no effect unless {code durationBetweenEvictionRuns} has a positive value.
        Specified by:
        getMinIdle in interface DataSourceMXBean
        Returns:
        the minimum number of idle connections
        See Also:
        GenericObjectPool.getMinIdle()

      • getNumActive

        public int getNumActive()
        [Read Only] The current number of active connections that have been allocated from this data source.
        Specified by:
        getNumActive in interface DataSourceMXBean
        Returns:
        the current number of active connections

      • getNumIdle

        public int getNumIdle()
        [Read Only] The current number of idle connections that are waiting to be allocated from this data source.
        Specified by:
        getNumIdle in interface DataSourceMXBean
        Returns:
        the current number of idle connections

      • getParentLogger

        public java.util.logging.Logger getParentLogger()
                                         throws java.sql.SQLFeatureNotSupportedException
        Specified by:
        getParentLogger in interface javax.sql.CommonDataSource
        Throws:
        java.sql.SQLFeatureNotSupportedException

      • getPassword

        public java.lang.String getPassword()
        Gets the password passed to the JDBC driver to establish connections.
        Specified by:
        getPassword in interface BasicDataSourceMXBean
        Returns:
        the connection password

      • getRegisteredJmxName

        protected javax.management.ObjectName getRegisteredJmxName()
        Gets the registered JMX ObjectName.
        Returns:
        the registered JMX ObjectName.

      • getRemoveAbandonedTimeoutDuration

        public java.time.Duration getRemoveAbandonedTimeoutDuration()
        Gets the timeout before an abandoned connection can be removed.

        Creating a Statement, PreparedStatement or CallableStatement or using one of these to execute a query (using one of the execute methods) resets the lastUsed property of the parent connection.

        Abandoned connection cleanup happens when:

        The default value is 300 seconds.

        Returns:
        Timeout before an abandoned connection can be removed.
        Since:
        2.10.0

      • getRollbackOnReturn

        public boolean getRollbackOnReturn()
        Gets the current value of the flag that controls whether a connection will be rolled back when it is returned to the pool if auto commit is not enabled and the connection is not read only.
        Returns:
        whether a connection will be rolled back when it is returned to the pool.

      • getSoftMinEvictableIdleDuration

        public java.time.Duration getSoftMinEvictableIdleDuration()
        Gets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.

        When minEvictableIdleTimeMillis is set to a positive value, minEvictableIdleTimeMillis is examined first by the idle connection evictor - i.e. when idle connections are visited by the evictor, idle time is first compared against minEvictableIdleTimeMillis (without considering the number of idle connections in the pool) and then against softMinEvictableIdleTimeMillis, including the minIdle, constraint.

        Returns:
        minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool
        Since:
        2.10.0

      • getSoftMinEvictableIdleTimeMillis

        @Deprecated
public long getSoftMinEvictableIdleTimeMillis()
        Deprecated.
        Use getSoftMinEvictableIdleDuration().
        Gets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.

        When minEvictableIdleTimeMillis is set to a positive value, minEvictableIdleTimeMillis is examined first by the idle connection evictor - i.e. when idle connections are visited by the evictor, idle time is first compared against minEvictableIdleTimeMillis (without considering the number of idle connections in the pool) and then against softMinEvictableIdleTimeMillis, including the minIdle, constraint.

        Specified by:
        getSoftMinEvictableIdleTimeMillis in interface DataSourceMXBean
        Returns:
        minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool

      • getTestOnReturn

        public boolean getTestOnReturn()
        Gets the value of the {code testOnReturn} property.
        Returns:
        true if objects are validated before being returned to the pool
        See Also:
        setTestOnReturn(boolean)

      • getDurationBetweenEvictionRuns

        public java.time.Duration getDurationBetweenEvictionRuns()
        Gets the value of the {code durationBetweenEvictionRuns} property.
        Returns:
        the time (in milliseconds) between evictor runs
        Since:
        2.10.0
        See Also:
        setDurationBetweenEvictionRuns(Duration)

      • getUrl

        public java.lang.String getUrl()
        Gets the JDBC connection {code url} property.
        Specified by:
        getUrl in interface DataSourceMXBean
        Returns:
        the {code url} passed to the JDBC driver to establish connections

      • getUsername

        public java.lang.String getUsername()
        Gets the JDBC connection {code userName} property.
        Specified by:
        getUsername in interface DataSourceMXBean
        Returns:
        the {code userName} passed to the JDBC driver to establish connections

      • getValidationQueryTimeoutDuration

        public java.time.Duration getValidationQueryTimeoutDuration()
        Gets the validation query timeout.
        Returns:
        the timeout in seconds before connection validation queries fail.

      • invalidateConnection

        public void invalidateConnection​(java.sql.Connection connection)
                          throws java.lang.IllegalStateException
        Manually invalidates a connection, effectively requesting the pool to try to close it, remove it from the pool and reclaim pool capacity.
        Parameters:
        connection - The Connection to invalidate.
        Throws:
        java.lang.IllegalStateException - if invalidating the connection failed.
        Since:
        2.1

      • isAccessToUnderlyingConnectionAllowed

        public boolean isAccessToUnderlyingConnectionAllowed()
        Gets the value of the accessToUnderlyingConnectionAllowed property.
        Specified by:
        isAccessToUnderlyingConnectionAllowed in interface DataSourceMXBean
        Returns:
        true if access to the underlying connection is allowed, false otherwise.

      • isClearStatementPoolOnReturn

        public boolean isClearStatementPoolOnReturn()
        Returns true if the statement pool is cleared when the connection is returned to its pool.
        Specified by:
        isClearStatementPoolOnReturn in interface DataSourceMXBean
        Returns:
        true if the statement pool is cleared at connection return
        Since:
        2.8.0

      • isClosed

        public boolean isClosed()
        If true, this data source is closed and no more connections can be retrieved from this data source.
        Specified by:
        isClosed in interface DataSourceMXBean
        Returns:
        true, if the data source is closed; false otherwise

      • isPoolPreparedStatements

        public boolean isPoolPreparedStatements()
        Returns true if we are pooling statements.
        Specified by:
        isPoolPreparedStatements in interface DataSourceMXBean
        Returns:
        true if prepared and callable statements are pooled

      • isWrapperFor

        public boolean isWrapperFor​(java.lang.Class<?> iface)
                     throws java.sql.SQLException
        Specified by:
        isWrapperFor in interface java.sql.Wrapper
        Throws:
        java.sql.SQLException

      • log

        protected void log​(java.lang.String message)
        Logs the given message.
        Parameters:
        message - the message to log.

      • log

        protected void log​(java.lang.String message,
                   java.lang.Throwable throwable)
        Logs the given throwable.
        Parameters:
        message - TODO
        throwable - the throwable.
        Since:
        2.7.0

      • postDeregister

        public void postDeregister()
        Specified by:
        postDeregister in interface javax.management.MBeanRegistration

      • postRegister

        public void postRegister​(java.lang.Boolean registrationDone)
        Specified by:
        postRegister in interface javax.management.MBeanRegistration

      • preDeregister

        public void preDeregister()
                   throws java.lang.Exception
        Specified by:
        preDeregister in interface javax.management.MBeanRegistration
        Throws:
        java.lang.Exception

      • preRegister

        public javax.management.ObjectName preRegister​(javax.management.MBeanServer server,
                                               javax.management.ObjectName objectName)
        Specified by:
        preRegister in interface javax.management.MBeanRegistration

      • removeConnectionProperty

        public void removeConnectionProperty​(java.lang.String name)
        Removes a custom connection property.
        Parameters:
        name - Name of the custom connection property to remove
        See Also:
        addConnectionProperty(String, String)

      • restart

        public void restart()
             throws java.sql.SQLException
        Restarts the datasource.

        This method calls close() and start() in sequence within synchronized scope so any connection requests that come in while the datasource is shutting down will be served by the new pool.

        Idle connections that are stored in the connection pool when this method is invoked are closed, but connections that are checked out to clients when this method is invoked are not affected. When client applications subsequently invoke Connection.close() to return these connections to the pool, the underlying JDBC connections are closed. These connections do not count in getMaxTotal() or getNumActive() after invoking this method. For example, if there are 3 connections checked out by clients when restart() is invoked, after this method is called, getNumActive() will return 0 and up to getMaxTotal() + 3 connections may be open until the connections sourced from the original pool are returned.

        The new connection pool created by this method is initialized with currently set configuration properties.

        Specified by:
        restart in interface DataSourceMXBean
        Throws:
        java.sql.SQLException - if an error occurs initializing the datasource

      • setAbandonedLogWriter

        public void setAbandonedLogWriter​(java.io.PrintWriter logWriter)
        Sets the print writer to be used by this configuration to log information on abandoned objects.
        Parameters:
        logWriter - The new log writer

      • setAbandonedUsageTracking

        public void setAbandonedUsageTracking​(boolean usageTracking)
        If the connection pool implements UsageTracking, configure whether the connection pool should record a stack trace every time a method is called on a pooled connection and retain the most recent stack trace to aid debugging of abandoned connections.
        Parameters:
        usageTracking - A value of true will enable the recording of a stack trace on every use of a pooled connection

      • setAccessToUnderlyingConnectionAllowed

        public void setAccessToUnderlyingConnectionAllowed​(boolean allow)
        Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to the underlying connection. (Default: false)

        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:
        allow - Access to the underlying connection is granted when true.

      • setAutoCommitOnReturn

        public void setAutoCommitOnReturn​(boolean autoCommitOnReturn)
        Sets the value of the flag that controls whether or not connections being returned to the pool will be checked and configured with Connection.setAutoCommit(true) if the auto commit setting is false when the connection is returned. It is true by default.
        Parameters:
        autoCommitOnReturn - Whether or not connections being returned to the pool will be checked and configured with auto-commit.
        Since:
        2.6.0

      • setCacheState

        public void setCacheState​(boolean cacheState)
        Sets the state caching flag.
        Parameters:
        cacheState - The new value for the state caching flag

      • setClearStatementPoolOnReturn

        public void setClearStatementPoolOnReturn​(boolean clearStatementPoolOnReturn)
        Sets whether the pool of statements (which was enabled with setPoolPreparedStatements(boolean)) should be cleared when the connection is returned to its pool. Default is false.
        Parameters:
        clearStatementPoolOnReturn - clear or not
        Since:
        2.8.0

      • setConnectionFactoryClassName

        public void setConnectionFactoryClassName​(java.lang.String connectionFactoryClassName)
        Sets the ConnectionFactory class name.
        Parameters:
        connectionFactoryClassName - A class name.
        Since:
        2.7.0

      • setConnectionInitSqls

        public void setConnectionInitSqls​(java.util.Collection<java.lang.String> connectionInitSqls)
        Sets the list of SQL statements to be executed when a physical connection is first created.

        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:
        connectionInitSqls - Collection of SQL statements to execute on connection creation

      • setConnectionProperties

        public void setConnectionProperties​(java.lang.String connectionProperties)
        Sets the connection properties passed to driver.connect(...).

        Format of the string must be [propertyName=property;]*

        NOTE - The "user" and "password" properties will be added explicitly, so they do not need to be included here.

        Parameters:
        connectionProperties - the connection properties used to create new connections

      • setDefaultAutoCommit

        public void setDefaultAutoCommit​(java.lang.Boolean defaultAutoCommit)
        Sets default auto-commit state of connections returned by this datasource.

        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:
        defaultAutoCommit - default auto-commit value

      • setDefaultCatalog

        public void setDefaultCatalog​(java.lang.String defaultCatalog)
        Sets the default catalog.

        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:
        defaultCatalog - the default catalog

      • setDefaultQueryTimeout

        public void setDefaultQueryTimeout​(java.time.Duration defaultQueryTimeoutDuration)
        Sets the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.
        Parameters:
        defaultQueryTimeoutDuration - The default query timeout Duration.
        Since:
        2.10.0

      • setDefaultQueryTimeout

        @Deprecated
public void setDefaultQueryTimeout​(java.lang.Integer defaultQueryTimeoutSeconds)
        Deprecated.
        Use setDefaultQueryTimeout(Duration).
        Sets the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.
        Parameters:
        defaultQueryTimeoutSeconds - The default query timeout in seconds.

      • setDefaultReadOnly

        public void setDefaultReadOnly​(java.lang.Boolean defaultReadOnly)
        Sets defaultReadonly property.

        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:
        defaultReadOnly - default read-only value

      • setDefaultSchema

        public void setDefaultSchema​(java.lang.String defaultSchema)
        Sets the default schema.

        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:
        defaultSchema - the default catalog
        Since:
        2.5.0

      • setDefaultTransactionIsolation

        public void setDefaultTransactionIsolation​(int defaultTransactionIsolation)
        Sets the default transaction isolation state for returned connections.

        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:
        defaultTransactionIsolation - the default transaction isolation state
        See Also:
        Connection.getTransactionIsolation()

      • setDisconnectionSqlCodes

        public void setDisconnectionSqlCodes​(java.util.Collection<java.lang.String> disconnectionSqlCodes)
        Sets the SQL_STATE codes considered to signal fatal conditions.

        Overrides the defaults in Utils.DISCONNECTION_SQL_CODES (plus anything starting with Utils.DISCONNECTION_SQL_CODE_PREFIX). If this property is non-null and getFastFailValidation() is true, whenever connections created by this datasource generate exceptions with SQL_STATE codes in this list, they will be marked as "fatally disconnected" and subsequent validations will fail fast (no attempt at isValid or validation query).

        If getFastFailValidation() is false setting this property has no effect.

        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:
        disconnectionSqlCodes - SQL_STATE codes considered to signal fatal conditions
        Since:
        2.1

      • setDriver

        public void setDriver​(java.sql.Driver driver)
        Sets the JDBC Driver instance to use for this pool.

        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:
        driver - The JDBC Driver instance to use for this pool.

      • setDriverClassLoader

        public void setDriverClassLoader​(java.lang.ClassLoader driverClassLoader)
        Sets the class loader to be used to load the JDBC driver.

        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:
        driverClassLoader - the class loader with which to load the JDBC driver

      • setDriverClassName

        public void setDriverClassName​(java.lang.String driverClassName)
        Sets the JDBC driver class name.

        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:
        driverClassName - the class name of the JDBC driver

      • setEnableAutoCommitOnReturn

        @Deprecated
public void setEnableAutoCommitOnReturn​(boolean autoCommitOnReturn)
        Deprecated.
        Use setAutoCommitOnReturn(boolean).
        Sets the value of the flag that controls whether or not connections being returned to the pool will be checked and configured with Connection.setAutoCommit(true) if the auto commit setting is false when the connection is returned. It is true by default.
        Parameters:
        autoCommitOnReturn - Whether or not connections being returned to the pool will be checked and configured with auto-commit.

      • setEvictionPolicyClassName

        public void setEvictionPolicyClassName​(java.lang.String evictionPolicyClassName)
        Sets the EvictionPolicy implementation to use with this connection pool.
        Parameters:
        evictionPolicyClassName - The fully qualified class name of the EvictionPolicy implementation

      • setFastFailValidation

        public void setFastFailValidation​(boolean fastFailValidation)
        Parameters:
        fastFailValidation - true means connections created by this factory will fast fail validation
        Since:
        2.1
        See Also:
        getFastFailValidation()

      • setInitialSize

        public void setInitialSize​(int initialSize)
        Sets the initial size of the connection pool.

        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:
        initialSize - the number of connections created when the pool is initialized

      • setJmxName

        public void setJmxName​(java.lang.String jmxName)
        Sets the JMX name that has been requested for this DataSource. If the requested name is not valid, an alternative may be chosen. This DataSource will attempt to register itself using this name. If another component registers this DataSource with JMX and this name is valid this name will be used in preference to any specified by the other component.
        Parameters:
        jmxName - The JMX name that has been requested for this DataSource

      • setLifo

        public void setLifo​(boolean lifo)
        Sets the LIFO property. True means the pool behaves as a LIFO queue; false means FIFO.
        Parameters:
        lifo - the new value for the LIFO property

      • setLogAbandoned

        public void setLogAbandoned​(boolean logAbandoned)
        Parameters:
        logAbandoned - new logAbandoned property value

      • setLogExpiredConnections

        public void setLogExpiredConnections​(boolean logExpiredConnections)
        When getMaxConnDuration() is set to limit connection lifetime, this property determines whether or not log messages are generated when the pool closes connections due to maximum lifetime exceeded. Set this property to false to suppress log messages when connections expire.
        Parameters:
        logExpiredConnections - Whether or not log messages are generated when the pool closes connections due to maximum lifetime exceeded.

      • setLoginTimeout

        public void setLoginTimeout​(int loginTimeout)
                     throws java.sql.SQLException
        BasicDataSource does NOT support this method.

        Set the login timeout (in seconds) for connecting to the database.

        Calls createDataSource(), so has the side effect of initializing the connection pool.

        Specified by:
        setLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        setLoginTimeout in interface javax.sql.DataSource
        Parameters:
        loginTimeout - The new login timeout, or zero for no timeout
        Throws:
        java.lang.UnsupportedOperationException - If the DataSource implementation does not support the login timeout feature.
        java.sql.SQLException - if a database access error occurs

      • setLogWriter

        public void setLogWriter​(java.io.PrintWriter logWriter)
                  throws java.sql.SQLException
        Sets the log writer being used by this data source.

        Calls createDataSource(), so has the side effect of initializing the connection pool.

        Specified by:
        setLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        setLogWriter in interface javax.sql.DataSource
        Parameters:
        logWriter - The new log writer
        Throws:
        java.sql.SQLException - if a database access error occurs

      • setMaxConn

        public void setMaxConn​(java.time.Duration maxConnDuration)
        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:
        maxConnDuration - The maximum permitted lifetime of a connection.
        Since:
        2.10.0

      • setMaxConnLifetimeMillis

        @Deprecated
public void setMaxConnLifetimeMillis​(long maxConnLifetimeMillis)
        Deprecated.
        Use setMaxConn(Duration).
        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.

      • setMaxIdle

        public void setMaxIdle​(int maxIdle)
        Sets the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed on return to the pool.
        Parameters:
        maxIdle - the new value for maxIdle
        See Also:
        getMaxIdle()

      • setMaxOpenPreparedStatements

        public void setMaxOpenPreparedStatements​(int maxOpenStatements)
        Sets the value of the maxOpenPreparedStatements property.

        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:
        maxOpenStatements - the new maximum number of prepared statements

      • setMaxTotal

        public void setMaxTotal​(int maxTotal)
        Sets the maximum total number of idle and borrows connections that can be active at the same time. Use a negative value for no limit.
        Parameters:
        maxTotal - the new value for maxTotal
        See Also:
        getMaxTotal()

      • setMaxWait

        public void setMaxWait​(java.time.Duration maxWaitDuration)
        Sets the MaxWaitMillis property. Use -1 to make the pool wait indefinitely.
        Parameters:
        maxWaitDuration - the new value for MaxWaitMillis
        Since:
        2.10.0
        See Also:
        getMaxWaitDuration()

      • setMaxWaitMillis

        @Deprecated
public void setMaxWaitMillis​(long maxWaitMillis)
        Deprecated.
        setMaxWait(Duration).
        Sets the MaxWaitMillis property. Use -1 to make the pool wait indefinitely.
        Parameters:
        maxWaitMillis - the new value for MaxWaitMillis
        See Also:
        getMaxWaitDuration()

      • setMinEvictableIdle

        public void setMinEvictableIdle​(java.time.Duration minEvictableIdleDuration)
        Sets the {code minEvictableIdleDuration} property.
        Parameters:
        minEvictableIdleDuration - the minimum amount of time an object may sit idle in the pool
        Since:
        2.10.0
        See Also:
        setMinEvictableIdle(Duration)

      • setMinEvictableIdleTimeMillis

        @Deprecated
public void setMinEvictableIdleTimeMillis​(long minEvictableIdleTimeMillis)
        Deprecated.
        Use setMinEvictableIdle(Duration).
        Sets the {code minEvictableIdleDuration} property.
        Parameters:
        minEvictableIdleTimeMillis - the minimum amount of time an object may sit idle in the pool
        See Also:
        setMinEvictableIdle(Duration)

      • setMinIdle

        public void setMinIdle​(int minIdle)
        Sets the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections are available when the idle object evictor runs. The value of this property has no effect unless {code durationBetweenEvictionRuns} has a positive value.
        Parameters:
        minIdle - the new value for minIdle
        See Also:
        GenericObjectPool.setMinIdle(int)

      • setNumTestsPerEvictionRun

        public void setNumTestsPerEvictionRun​(int numTestsPerEvictionRun)
        Sets the value of the {code numTestsPerEvictionRun} property.
        Parameters:
        numTestsPerEvictionRun - the new {code numTestsPerEvictionRun} value
        See Also:
        setNumTestsPerEvictionRun(int)

      • setPassword

        public void setPassword​(java.lang.String password)
        Sets the {code password}.

        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:
        password - new value for the password

      • setPoolPreparedStatements

        public void setPoolPreparedStatements​(boolean poolingStatements)
        Sets whether to pool statements or not.

        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:
        poolingStatements - pooling on or off

      • setRemoveAbandonedOnBorrow

        public void setRemoveAbandonedOnBorrow​(boolean removeAbandonedOnBorrow)
        Parameters:
        removeAbandonedOnBorrow - true means abandoned connections may be removed when connections are borrowed from the pool.
        See Also:
        getRemoveAbandonedOnBorrow()

      • setRemoveAbandonedOnMaintenance

        public void setRemoveAbandonedOnMaintenance​(boolean removeAbandonedOnMaintenance)
        Parameters:
        removeAbandonedOnMaintenance - true means abandoned connections may be removed on pool maintenance.
        See Also:
        getRemoveAbandonedOnMaintenance()

      • setRollbackOnReturn

        public void setRollbackOnReturn​(boolean rollbackOnReturn)
        Sets the flag that controls if a connection will be rolled back when it is returned to the pool if auto commit is not enabled and the connection is not read only.
        Parameters:
        rollbackOnReturn - whether a connection will be rolled back when it is returned to the pool.

      • setSoftMinEvictableIdle

        public void setSoftMinEvictableIdle​(java.time.Duration softMinEvictableIdleTimeMillis)
        Sets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.
        Parameters:
        softMinEvictableIdleTimeMillis - minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool.
        Since:
        2.10.0
        See Also:
        getSoftMinEvictableIdleTimeMillis()

      • setSoftMinEvictableIdleTimeMillis

        @Deprecated
public void setSoftMinEvictableIdleTimeMillis​(long softMinEvictableIdleTimeMillis)
        Deprecated.
        Use setSoftMinEvictableIdle(Duration).
        Sets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool.
        Parameters:
        softMinEvictableIdleTimeMillis - minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming there are minIdle idle connections in the pool.
        See Also:
        getSoftMinEvictableIdleTimeMillis()

      • setTestOnBorrow

        public void setTestOnBorrow​(boolean testOnBorrow)
        Sets the {code testOnBorrow} property. This property determines whether or not the pool will validate objects before they are borrowed from the pool.
        Parameters:
        testOnBorrow - new value for testOnBorrow property

      • setTestOnCreate

        public void setTestOnCreate​(boolean testOnCreate)
        Sets the {code testOnCreate} property. This property determines whether or not the pool will validate objects immediately after they are created by the pool
        Parameters:
        testOnCreate - new value for testOnCreate property

      • setTestOnReturn

        public void setTestOnReturn​(boolean testOnReturn)
        Sets the testOnReturn property. This property determines whether or not the pool will validate objects before they are returned to the pool.
        Parameters:
        testOnReturn - new value for testOnReturn property

      • setTestWhileIdle

        public void setTestWhileIdle​(boolean testWhileIdle)
        Sets the testWhileIdle property. This property determines whether or not the idle object evictor will validate connections.
        Parameters:
        testWhileIdle - new value for testWhileIdle property

      • setDurationBetweenEvictionRuns

        public void setDurationBetweenEvictionRuns​(java.time.Duration timeBetweenEvictionRunsMillis)
        Sets the {code durationBetweenEvictionRuns} property.
        Parameters:
        timeBetweenEvictionRunsMillis - the new time between evictor runs
        Since:
        2.10.0
        See Also:
        setDurationBetweenEvictionRuns(Duration)

      • setUrl

        public void setUrl​(java.lang.String url)
        Sets the {code url}.

        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:
        url - the new value for the JDBC connection url

      • setUsername

        public void setUsername​(java.lang.String userName)
        Sets the {code userName}.

        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:
        userName - the new value for the JDBC connection user name

      • setValidationQuery

        public void setValidationQuery​(java.lang.String validationQuery)
        Sets the {code validationQuery}.

        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:
        validationQuery - the new value for the validation query

      • setValidationQueryTimeout

        public void setValidationQueryTimeout​(java.time.Duration validationQueryTimeoutDuration)
        Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.

        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:
        validationQueryTimeoutDuration - new validation query timeout value in seconds
        Since:
        2.10.0

      • setValidationQueryTimeout

        @Deprecated
public void setValidationQueryTimeout​(int validationQueryTimeoutSeconds)
        Deprecated.
        Use setValidationQueryTimeout(Duration).
        Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.

        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:
        validationQueryTimeoutSeconds - new validation query timeout value in seconds

      • start

        public void start()
           throws java.sql.SQLException
        Starts the datasource.

        It is not necessary to call this method before using a newly created BasicDataSource instance, but calling it in that context causes the datasource to be immediately initialized (instead of waiting for the first getConnection() request). Its primary use is to restart and reinitialize a datasource that has been closed.

        When this method is called after close(), connections checked out by clients before the datasource was stopped do not count in getMaxTotal() or getNumActive(). For example, if there are 3 connections checked out by clients when close() is invoked and they are not returned before start() is invoked, after this method is called, getNumActive() will return 0. These connections will be physically closed when they are returned, but they will not count against the maximum allowed in the newly started datasource.

        Specified by:
        start in interface DataSourceMXBean
        Throws:
        java.sql.SQLException - if an error occurs initializing the datasource

      • startPoolMaintenance

        protected void startPoolMaintenance()
        Starts the connection pool maintenance task, if configured.

      • unwrap

        public <T> T unwrap​(java.lang.Class<T> iface)
             throws java.sql.SQLException
        Specified by:
        unwrap in interface java.sql.Wrapper
        Throws:
        java.sql.SQLException