Package org.apache.commons.dbcp2

Class BasicDataSource

  • All Implemented Interfaces:
    java.lang.AutoCloseable, java.sql.Wrapper, javax.management.MBeanRegistration, javax.sql.CommonDataSource, javax.sql.DataSource, BasicDataSourceMXBean
    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-dbcp and commons-pool packages, but provides a "one stop shopping" solution for basic requirements.

    Since:
    2.0
    Version:
    $Id: BasicDataSource.java 1693836 2015-08-02 22:51:27Z psteitz $
    Author:
    Glenn L. Nielsen, Craig R. McClanahan, Dirk Verbeeck

    • Constructor Summary

      Constructors 
      Constructor Description
      BasicDataSource()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addConnectionProperty​(java.lang.String name, java.lang.String value)
      Add a custom connection property to the set that will be passed to our JDBC driver.
      void close()
      Closes and releases all idle connections that are currently stored in the connection pool associated with this data source.
      java.io.PrintWriter getAbandonedLogWriter()
      Gets the log writer to be used by this configuration to log information on abandoned objects.
      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?
      boolean getCacheState()
      Returns the state caching flag.
      java.sql.Connection getConnection()
      Create (if necessary) and return a connection to the database.
      java.sql.Connection getConnection​(java.lang.String user, java.lang.String pass)
      BasicDataSource does NOT support this method.
      java.util.List<java.lang.String> getConnectionInitSqls()
      Returns the list of SQL statements executed when a physical connection is first created.
      java.lang.String[] getConnectionInitSqlsAsArray()
      Provides the same data as getConnectionInitSqls() but in an array so it is accessible via JMX.
      java.lang.Boolean getDefaultAutoCommit()
      Returns the default auto-commit property.
      java.lang.String getDefaultCatalog()
      Returns the default catalog.
      java.lang.Integer getDefaultQueryTimeout()
      Obtain the default query timeout that will be used for Statements created from this connection.
      java.lang.Boolean getDefaultReadOnly()
      Returns the default readOnly property.
      int getDefaultTransactionIsolation()
      Returns the default transaction isolation state of returned connections.
      java.util.Set<java.lang.String> getDisconnectionSqlCodes()
      Returns the set of SQL_STATE codes considered to signal fatal conditions.
      java.lang.String[] getDisconnectionSqlCodesAsArray()
      Provides the same data as getDisconnectionSqlCodes() but in an array so it is accessible via JMX.
      java.sql.Driver getDriver()
      Returns the JDBC Driver that has been configured for use by this pool.
      java.lang.ClassLoader getDriverClassLoader()
      Returns the class loader specified for loading the JDBC driver.
      java.lang.String getDriverClassName()
      Returns the jdbc driver class name.
      boolean getEnableAutoCommitOnReturn()
      Returns 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.
      java.lang.String getEvictionPolicyClassName()
      Gets the EvictionPolicy implementation in use with this connection pool.
      boolean getFastFailValidation()
      True means that validation will fail immediately for connections that have previously thrown SQLExceptions with SQL_STATE indicating fatal disconnection errors.
      int getInitialSize()
      Returns the initial size of the connection pool.
      java.lang.String getJmxName()
      Returns the JMX name that has been requested for this DataSource.
      boolean getLifo()
      Returns the LIFO property.
      boolean getLogAbandoned()
      Flag to log stack traces for application code which abandoned a Statement or Connection.
      boolean getLogExpiredConnections()
      When getMaxConnLifetimeMillis() 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.
      int getLoginTimeout()
      BasicDataSource does NOT support this method.
      java.io.PrintWriter getLogWriter()
      Returns the log writer being used by this data source.
      long getMaxConnLifetimeMillis()
      Returns the maximum permitted lifetime of a connection in milliseconds.
      int getMaxIdle()
      Returns the maximum number of connections that can remain idle in the pool.
      int getMaxOpenPreparedStatements()
      Gets the value of the maxOpenPreparedStatements property.
      int getMaxTotal()
      Returns the maximum number of active connections that can be allocated at the same time.
      long getMaxWaitMillis()
      Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.
      long getMinEvictableIdleTimeMillis()
      Returns the minEvictableIdleTimeMillis property.
      int getMinIdle()
      Returns the minimum number of idle connections in the pool.
      int getNumActive()
      [Read Only] The current number of active connections that have been allocated from this data source.
      int getNumIdle()
      [Read Only] The current number of idle connections that are waiting to be allocated from this data source.
      int getNumTestsPerEvictionRun()
      Returns the value of the numTestsPerEvictionRun property.
      java.util.logging.Logger getParentLogger()  
      java.lang.String getPassword()
      Returns the password passed to the JDBC driver to establish connections.
      boolean getRemoveAbandonedOnBorrow()
      Flag to remove abandoned connections if they exceed the removeAbandonedTimeout when borrowObject is invoked.
      boolean getRemoveAbandonedOnMaintenance()
      Flag to remove abandoned connections if they exceed the removeAbandonedTimeout during pool maintenance.
      int getRemoveAbandonedTimeout()
      Timeout in seconds before an abandoned connection can be removed.
      boolean getRollbackOnReturn()
      Gets the current value of 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.
      long getSoftMinEvictableIdleTimeMillis()
      Returns 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.
      boolean getTestOnBorrow()
      Returns the testOnBorrow property.
      boolean getTestOnCreate()
      Returns the testOnCreate property.
      boolean getTestOnReturn()
      Returns the value of the testOnReturn property.
      boolean getTestWhileIdle()
      Returns the value of the testWhileIdle property.
      long getTimeBetweenEvictionRunsMillis()
      Returns the value of the timeBetweenEvictionRunsMillis property.
      java.lang.String getUrl()
      Returns the JDBC connection url property.
      java.lang.String getUsername()
      Returns the JDBC connection username property.
      java.lang.String getValidationQuery()
      Returns the validation query used to validate connections before returning them.
      int getValidationQueryTimeout()
      Returns the validation query timeout.
      void invalidateConnection​(java.sql.Connection connection)
      Manually invalidates a connection, effectively requesting the pool to try to close it, remove it from the pool and reclaim pool capacity.
      boolean isAccessToUnderlyingConnectionAllowed()
      Returns the value of the accessToUnderlyingConnectionAllowed property.
      boolean isClosed()
      If true, this data source is closed and no more connections can be retrieved from this datasource.
      boolean isPoolPreparedStatements()
      Returns true if we are pooling statements.
      boolean isWrapperFor​(java.lang.Class<?> iface)  
      void postDeregister()  
      void postRegister​(java.lang.Boolean registrationDone)  
      void preDeregister()  
      javax.management.ObjectName preRegister​(javax.management.MBeanServer server, javax.management.ObjectName name)  
      void removeConnectionProperty​(java.lang.String name)
      Remove a custom connection property.
      void setAbandonedLogWriter​(java.io.PrintWriter logWriter)
      Sets the log writer to be used by this configuration to log information on abandoned objects.
      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.
      void setAccessToUnderlyingConnectionAllowed​(boolean allow)
      Sets the value of the accessToUnderlyingConnectionAllowed property.
      void setCacheState​(boolean cacheState)
      Sets the state caching flag.
      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.
      void setConnectionProperties​(java.lang.String connectionProperties)
      Sets the connection properties passed to driver.connect(...).
      void setDefaultAutoCommit​(java.lang.Boolean defaultAutoCommit)
      Sets default auto-commit state of connections returned by this datasource.
      void setDefaultCatalog​(java.lang.String defaultCatalog)
      Sets the default catalog.
      void setDefaultQueryTimeout​(java.lang.Integer defaultQueryTimeout)
      Set the default query timeout that will be used for Statements created from this connection.
      void setDefaultReadOnly​(java.lang.Boolean defaultReadOnly)
      Sets defaultReadonly property.
      void setDefaultTransactionIsolation​(int defaultTransactionIsolation)
      Sets the default transaction isolation state for returned connections.
      void setDisconnectionSqlCodes​(java.util.Collection<java.lang.String> disconnectionSqlCodes)
      Sets the SQL_STATE codes considered to signal fatal conditions.
      void setDriver​(java.sql.Driver driver)
      Sets the JDBC Driver instance to use for this pool.
      void setDriverClassLoader​(java.lang.ClassLoader driverClassLoader)
      Sets the class loader to be used to load the JDBC driver.
      void setDriverClassName​(java.lang.String driverClassName)
      Sets the jdbc driver class name.
      void setEnableAutoCommitOnReturn​(boolean enableAutoCommitOnReturn)
      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.
      void setEvictionPolicyClassName​(java.lang.String evictionPolicyClassName)
      Sets the EvictionPolicy implementation to use with this connection pool.
      void setFastFailValidation​(boolean fastFailValidation)  
      void setInitialSize​(int initialSize)
      Sets the initial size of the connection pool.
      void setJmxName​(java.lang.String jmxName)
      Sets the JMX name that has been requested for this DataSource.
      void setLifo​(boolean lifo)
      Sets the LIFO property.
      void setLogAbandoned​(boolean logAbandoned)  
      void setLogExpiredConnections​(boolean logExpiredConnections)
      When getMaxConnLifetimeMillis() 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.
      void setLoginTimeout​(int loginTimeout)
      BasicDataSource does NOT support this method.
      void setLogWriter​(java.io.PrintWriter logWriter)
      Sets the log writer being used by this data source.
      void setMaxConnLifetimeMillis​(long maxConnLifetimeMillis)
      Sets the maximum permitted lifetime of a connection in milliseconds.
      void setMaxIdle​(int maxIdle)
      Sets the maximum number of connections that can remain idle in the pool.
      void setMaxOpenPreparedStatements​(int maxOpenStatements)
      Sets the value of the maxOpenPreparedStatements property.
      void setMaxTotal​(int maxTotal)
      Sets the maximum total number of idle and borrows connections that can be active at the same time.
      void setMaxWaitMillis​(long maxWaitMillis)
      Sets the MaxWaitMillis property.
      void setMinEvictableIdleTimeMillis​(long minEvictableIdleTimeMillis)
      Sets the minEvictableIdleTimeMillis property.
      void setMinIdle​(int minIdle)
      Sets the minimum number of idle connections in the pool.
      void setNumTestsPerEvictionRun​(int numTestsPerEvictionRun)
      Sets the value of the numTestsPerEvictionRun property.
      void setPassword​(java.lang.String password)
      Sets the password.
      void setPoolPreparedStatements​(boolean poolingStatements)
      Sets whether to pool statements or not.
      void setRemoveAbandonedOnBorrow​(boolean removeAbandonedOnBorrow)  
      void setRemoveAbandonedOnMaintenance​(boolean removeAbandonedOnMaintenance)  
      void setRemoveAbandonedTimeout​(int removeAbandonedTimeout)
      Sets the timeout in seconds before an abandoned connection can be removed.
      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.
      void setSoftMinEvictableIdleTimeMillis​(long 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.
      void setTestOnBorrow​(boolean testOnBorrow)
      Sets the testOnBorrow property.
      void setTestOnCreate​(boolean testOnCreate)
      Sets the testOnCreate property.
      void setTestOnReturn​(boolean testOnReturn)
      Sets the testOnReturn property.
      void setTestWhileIdle​(boolean testWhileIdle)
      Sets the testWhileIdle property.
      void setTimeBetweenEvictionRunsMillis​(long timeBetweenEvictionRunsMillis)
      Sets the timeBetweenEvictionRunsMillis property.
      void setUrl​(java.lang.String url)
      Sets the url.
      void setUsername​(java.lang.String username)
      Sets the username.
      void setValidationQuery​(java.lang.String validationQuery)
      Sets the validationQuery.
      void setValidationQueryTimeout​(int timeout)
      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.
      <T> T unwrap​(java.lang.Class<T> iface)  

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface javax.sql.CommonDataSource

        createShardingKeyBuilder

      • Methods inherited from interface javax.sql.DataSource

        createConnectionBuilder

    • Constructor Detail

      • BasicDataSource

        public BasicDataSource()

    • Method Detail

      • getDefaultAutoCommit

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

      • 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

      • getDefaultReadOnly

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

      • 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

      • getDefaultTransactionIsolation

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

      • 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()

      • getDefaultQueryTimeout

        public java.lang.Integer getDefaultQueryTimeout()
        Obtain the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.

      • setDefaultQueryTimeout

        public void setDefaultQueryTimeout​(java.lang.Integer defaultQueryTimeout)
        Set the default query timeout that will be used for Statements created from this connection. null means that the driver default will be used.

      • getDefaultCatalog

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

      • 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

      • getCacheState

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

      • setCacheState

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

      • getDriver

        public java.sql.Driver getDriver()
        Returns 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

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

      • 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

      • getDriverClassLoader

        public java.lang.ClassLoader getDriverClassLoader()
        Returns 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).

      • 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

      • getLifo

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

      • 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

      • getMaxTotal

        public int getMaxTotal()

        Returns 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 BasicDataSourceMXBean
        Returns:
        the maximum number of active connections

      • 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()

      • getMaxIdle

        public int getMaxIdle()

        Returns 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 BasicDataSourceMXBean
        Returns:
        the maximum number of idle connections

      • 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()

      • getMinIdle

        public int getMinIdle()
        Returns 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 timeBetweenEvictionRunsMillis has a positive value.
        Specified by:
        getMinIdle in interface BasicDataSourceMXBean
        Returns:
        the minimum number of idle connections
        See Also:
        GenericObjectPool.getMinIdle()

      • 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 timeBetweenEvictionRunsMillis has a positive value.
        Parameters:
        minIdle - the new value for minIdle
        See Also:
        GenericObjectPool.setMinIdle(int)

      • getInitialSize

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

      • 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

      • getMaxWaitMillis

        public long getMaxWaitMillis()
        Returns 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 BasicDataSourceMXBean
        Returns:
        the maxWaitMillis property value

      • setMaxWaitMillis

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

      • isPoolPreparedStatements

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

      • 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

      • getMaxOpenPreparedStatements

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

      • 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

      • getTestOnCreate

        public boolean getTestOnCreate()
        Returns the testOnCreate property.
        Specified by:
        getTestOnCreate in interface BasicDataSourceMXBean
        Returns:
        true if objects are validated immediately after they are created by the pool
        See Also:
        testOnCreate

      • setTestOnCreate

        public void setTestOnCreate​(boolean testOnCreate)
        Sets the 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

      • getTestOnBorrow

        public boolean getTestOnBorrow()
        Returns the testOnBorrow property.
        Specified by:
        getTestOnBorrow in interface BasicDataSourceMXBean
        Returns:
        true if objects are validated before being borrowed from the pool
        See Also:
        testOnBorrow

      • setTestOnBorrow

        public void setTestOnBorrow​(boolean testOnBorrow)
        Sets the 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

      • getTestOnReturn

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

      • 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

      • getTimeBetweenEvictionRunsMillis

        public long getTimeBetweenEvictionRunsMillis()
        Returns the value of the timeBetweenEvictionRunsMillis property.
        Specified by:
        getTimeBetweenEvictionRunsMillis in interface BasicDataSourceMXBean
        Returns:
        the time (in milliseconds) between evictor runs
        See Also:
        timeBetweenEvictionRunsMillis

      • setTimeBetweenEvictionRunsMillis

        public void setTimeBetweenEvictionRunsMillis​(long timeBetweenEvictionRunsMillis)
        Sets the timeBetweenEvictionRunsMillis property.
        Parameters:
        timeBetweenEvictionRunsMillis - the new time between evictor runs
        See Also:
        timeBetweenEvictionRunsMillis

      • getNumTestsPerEvictionRun

        public int getNumTestsPerEvictionRun()
        Returns the value of the numTestsPerEvictionRun property.
        Specified by:
        getNumTestsPerEvictionRun in interface BasicDataSourceMXBean
        Returns:
        the number of objects to examine during idle object evictor runs
        See Also:
        numTestsPerEvictionRun

      • setNumTestsPerEvictionRun

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

      • getMinEvictableIdleTimeMillis

        public long getMinEvictableIdleTimeMillis()
        Returns the minEvictableIdleTimeMillis property.
        Specified by:
        getMinEvictableIdleTimeMillis in interface BasicDataSourceMXBean
        Returns:
        the value of the minEvictableIdleTimeMillis property
        See Also:
        minEvictableIdleTimeMillis

      • setMinEvictableIdleTimeMillis

        public void setMinEvictableIdleTimeMillis​(long minEvictableIdleTimeMillis)
        Sets the minEvictableIdleTimeMillis property.
        Parameters:
        minEvictableIdleTimeMillis - the minimum amount of time an object may sit idle in the pool
        See Also:
        minEvictableIdleTimeMillis

      • setSoftMinEvictableIdleTimeMillis

        public void setSoftMinEvictableIdleTimeMillis​(long 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.
        See Also:
        getSoftMinEvictableIdleTimeMillis()

      • getSoftMinEvictableIdleTimeMillis

        public long getSoftMinEvictableIdleTimeMillis()

        Returns 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 miniEvictableIdleTimeMillis is set to a positive value, miniEvictableIdleTimeMillis 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 BasicDataSourceMXBean
        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

      • getEvictionPolicyClassName

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

      • 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

      • getTestWhileIdle

        public boolean getTestWhileIdle()
        Returns the value of the testWhileIdle property.
        Specified by:
        getTestWhileIdle in interface BasicDataSourceMXBean
        Returns:
        true if objects examined by the idle object evictor are validated
        See Also:
        testWhileIdle

      • 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

      • 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 BasicDataSourceMXBean
        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 BasicDataSourceMXBean
        Returns:
        the current number of idle connections

      • getPassword

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

      • setPassword

        public void setPassword​(java.lang.String password)

        Sets the 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

      • getUrl

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

      • setUrl

        public void setUrl​(java.lang.String url)

        Sets the 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

      • getUsername

        public java.lang.String getUsername()
        Returns the JDBC connection username property.
        Specified by:
        getUsername in interface BasicDataSourceMXBean
        Returns:
        the username passed to the JDBC driver to establish connections

      • setUsername

        public void setUsername​(java.lang.String username)

        Sets the 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 username

      • getValidationQuery

        public java.lang.String getValidationQuery()
        Returns the validation query used to validate connections before returning them.
        Specified by:
        getValidationQuery in interface BasicDataSourceMXBean
        Returns:
        the SQL validation query
        See Also:
        validationQuery

      • setValidationQuery

        public void setValidationQuery​(java.lang.String validationQuery)

        Sets the 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

      • getValidationQueryTimeout

        public int getValidationQueryTimeout()
        Returns the validation query timeout.
        Specified by:
        getValidationQueryTimeout in interface BasicDataSourceMXBean
        Returns:
        the timeout in seconds before connection validation queries fail.

      • setValidationQueryTimeout

        public void setValidationQueryTimeout​(int timeout)
        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:
        timeout - new validation query timeout value in seconds

      • getConnectionInitSqls

        public java.util.List<java.lang.String> getConnectionInitSqls()
        Returns 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

      • 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

      • isAccessToUnderlyingConnectionAllowed

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

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

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

      • setLogExpiredConnections

        public void setLogExpiredConnections​(boolean logExpiredConnections)
        When getMaxConnLifetimeMillis() 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.

      • getJmxName

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

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

      • getEnableAutoCommitOnReturn

        public boolean getEnableAutoCommitOnReturn()
        Returns 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.

      • setEnableAutoCommitOnReturn

        public void setEnableAutoCommitOnReturn​(boolean enableAutoCommitOnReturn)
        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.

      • getRollbackOnReturn

        public boolean getRollbackOnReturn()
        Gets the current value of 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.

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

      • getDisconnectionSqlCodes

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

      • 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

      • 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 BasicDataSourceMXBean
        Returns:
        true if connections created by this datasource will fast fail validation.
        Since:
        2.1
        See Also:
        setDisconnectionSqlCodes(Collection)

      • 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()

      • getConnection

        public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
        Create (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
        java.sql.SQLException - if a database access error occurs

      • getLoginTimeout

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

        Returns 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

        Returns 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

      • 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

      • setRemoveAbandonedOnMaintenance

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

      • 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()

      • 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 BasicDataSourceMXBean
        Returns:
        getLogAbandoned()

      • setLogAbandoned

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

      • getAbandonedLogWriter

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

      • setAbandonedLogWriter

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

      • 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 BasicDataSourceMXBean
        Returns:
        true if usage tracking is enabled

      • 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

      • addConnectionProperty

        public void addConnectionProperty​(java.lang.String name,
                                  java.lang.String value)
        Add 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

      • removeConnectionProperty

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

      • 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

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

        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

      • isClosed

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

      • isWrapperFor

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

      • 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

      • getParentLogger

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

      • 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.
        Throws:
        java.lang.IllegalStateException - if invalidating the connection failed.
        Since:
        2.1

      • preRegister

        public javax.management.ObjectName preRegister​(javax.management.MBeanServer server,
                                               javax.management.ObjectName name)
        Specified by:
        preRegister 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

      • postDeregister

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