Interface PoolConfiguration

All Known Subinterfaces:
ConnectionPoolMBean
All Known Implementing Classes:
ConnectionPool, DataSource, DataSourceProxy, PoolProperties, XADataSource
public interface PoolConfiguration
A list of properties that are configurable for a connection pool. The DataSource object also implements this interface so that it can be easily configured through an IoC container without having to specify a secondary object with a setter method.

  • Field Details

  • Method Details

    • setAbandonWhenPercentageFull

      void setAbandonWhenPercentageFull(int percentage)
      Connections that have been abandoned (timed out) won't get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached.
      Parameters:
      percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned

    • getAbandonWhenPercentageFull

      int getAbandonWhenPercentageFull()
      Connections that have been abandoned (timed out) won't get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached.
      Returns:
      percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned

    • isFairQueue

      boolean isFairQueue()
      Returns true if a fair queue is being used by the connection pool
      Returns:
      true if a fair waiting queue is being used

    • setFairQueue

      void setFairQueue(boolean fairQueue)
      Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion. This uses the FairBlockingQueue implementation for the list of the idle connections. The default value is true. This flag is required when you want to use asynchronous connection retrieval.
      Parameters:
      fairQueue - true to use a fair queue

    • isAccessToUnderlyingConnectionAllowed

      boolean isAccessToUnderlyingConnectionAllowed()
      Property not used. Access is always allowed. Access can be achieved by calling unwrap on the pooled connection. see DataSource interface or call getConnection through reflection or cast the object as PooledConnection
      Returns:
      true

    • setAccessToUnderlyingConnectionAllowed

      void setAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed)
      No-op
      Parameters:
      accessToUnderlyingConnectionAllowed - parameter ignored

    • getConnectionProperties

      String getConnectionProperties()
      The connection properties that will be sent to the JDBC driver when establishing new connections. Format of the string is [propertyName=property;]
      NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. The default value is null.
      Returns:
      the connection properties

    • setConnectionProperties

      void setConnectionProperties(String connectionProperties)
      The properties that will be passed into Driver.connect(String, Properties) method. Username and password do not need to be stored here, they will be passed into the properties right before the connection is established.

      Re-setting the string re-applies it: the pairs the previous value of the string contributed are removed from the driver properties before the new ones are parsed in, so a reconfigure that drops a pair really stops sending it, while entries contributed from elsewhere - the explicitly passed user and password among them - are kept. A null value clears the string and takes its contributed pairs with it.

      Parameters:
      connectionProperties - properties - Format of the string is [propertyName=property;]* Example: prop1=value1;prop2=value2, may be null

    • getDbProperties

      Properties getDbProperties()
      Returns the database properties that are passed into the Driver.connect(String, Properties) method.
      Returns:
      database properties that are passed into the Driver.connect(String, Properties) method, or null when the configuration has none

    • setDbProperties

      void setDbProperties(Properties dbProperties)
      Overrides the database properties passed into the Driver.connect(String, Properties) method. A null collection is accepted as a configuration state, and it means what it says: the configuration has no driver properties. The credential setters then have no property to mirror into and getDbProperties() returns null. It is not a configuration that cannot connect - the URL and the user name and password still establish connections, with no extra properties sent along - and connections made through a configured DataSource do not consult the database properties at all.
      Parameters:
      dbProperties - The database properties, may be null

    • isDefaultAutoCommit

      Boolean isDefaultAutoCommit()
      The default auto-commit state of connections created by this pool. If not set (null), default is JDBC driver default (If set to null then the Connection.setAutoCommit(boolean) method will not be called.) When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Returns:
      the default auto commit setting, null is Driver default.

    • getDefaultAutoCommit

      Boolean getDefaultAutoCommit()
      The default auto-commit state of connections created by this pool. If not set (null), default is JDBC driver default (If set to null then the Connection.setAutoCommit(boolean) method will not be called.) When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Returns:
      the default auto commit setting, null is Driver default.

    • setDefaultAutoCommit

      void setDefaultAutoCommit(Boolean defaultAutoCommit)
      The default auto-commit state of connections created by this pool. If not set (null), default is JDBC driver default (If set to null then the Connection.setAutoCommit(boolean) method will not be called.) When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Parameters:
      defaultAutoCommit - default auto commit setting, null is Driver default.

    • getDefaultCatalog

      String getDefaultCatalog()
      If non null, during connection creation the method Connection.setCatalog(String) will be called with the set value. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Returns:
      the default catalog, null if not set and accepting the driver default.

    • setDefaultCatalog

      void setDefaultCatalog(String defaultCatalog)
      If non null, during connection creation the method Connection.setCatalog(String) will be called with the set value. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Parameters:
      defaultCatalog - null if not set and accepting the driver default.

    • isDefaultReadOnly

      Boolean isDefaultReadOnly()
      If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Returns:
      null if not set and accepting the driver default otherwise the read only value

    • getDefaultReadOnly

      Boolean getDefaultReadOnly()
      If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Returns:
      null if not set and accepting the driver default otherwise the read only value

    • setDefaultReadOnly

      void setDefaultReadOnly(Boolean defaultReadOnly)
      If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it.
      Parameters:
      defaultReadOnly - null if not set and accepting the driver default.

    • getDefaultTransactionIsolation

      int getDefaultTransactionIsolation()
      Returns the default transaction isolation level. If set to DataSourceFactory.UNKNOWN_TRANSACTIONISOLATION the method Connection.setTransactionIsolation(int) will not be called during connection creation. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it; a level the driver refuses on a session is the one documented exception to that enforcement - the session stays in service and that level is not retried on it.
      Returns:
      driver transaction isolation level, or -1 DataSourceFactory.UNKNOWN_TRANSACTIONISOLATION if not set.

    • setDefaultTransactionIsolation

      void setDefaultTransactionIsolation(int defaultTransactionIsolation)
      If set to DataSourceFactory.UNKNOWN_TRANSACTIONISOLATION the method Connection.setTransactionIsolation(int) will not be called during connection creation. Otherwise the method will be called with the isolation level set by this property. When the ConnectionState interceptor is configured, it applies this setting on every borrow rather than at connection creation, and re-applies it whenever a borrower has changed it (see getDefaultTransactionIsolation() for the refused-level exception).
      Parameters:
      defaultTransactionIsolation - a value of Connection.TRANSACTION_NONE, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE or DataSourceFactory.UNKNOWN_TRANSACTIONISOLATION The last value will not be set on the connection.

    • getDriverClassName

      String getDriverClassName()
      The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar
      Returns:
      fully qualified JDBC driver name.

    • setDriverClassName

      void setDriverClassName(String driverClassName)
      The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar
      Parameters:
      driverClassName - a fully qualified Java class name of a Driver implementation.

    • getInitialSize

      int getInitialSize()
      Returns the number of connections that will be established when the connection pool is started. Default value is 10
      Returns:
      number of connections to be started when pool is started

    • setInitialSize

      void setInitialSize(int initialSize)
      Set the number of connections that will be established when the connection pool is started. Default value is 10. If this value exceeds setMaxActive(int) it will automatically be lowered.
      Parameters:
      initialSize - the number of connections to be established.

    • isLogAbandoned

      boolean isLogAbandoned()
      boolean flag to set if stack traces should be logged for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false.
      Returns:
      true if the connection pool logs stack traces when connections are borrowed from the pool.

    • setLogAbandoned

      void setLogAbandoned(boolean logAbandoned)
      boolean flag to set if stack traces should be logged for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false.
      Parameters:
      logAbandoned - set to true if stack traces should be recorded when DataSourceProxy.getConnection() is called.

    • getMaxActive

      int getMaxActive()
      The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
      Returns:
      the maximum number of connections used by this pool

    • setMaxActive

      void setMaxActive(int maxActive)
      The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
      Parameters:
      maxActive - hard limit for number of managed connections by this pool

    • getMaxIdle

      int getMaxIdle()
      The maximum number of connections that should be kept in the idle pool if isPoolSweeperEnabled() returns false. If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() setting. Default value is getMaxActive() (100 with the default configuration)
      Returns:
      the maximum number of idle connections.

    • setMaxIdle

      void setMaxIdle(int maxIdle)
      The maximum number of connections that should be kept in the idle pool if isPoolSweeperEnabled() returns false. If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() setting. Default value is getMaxActive() (100 with the default configuration)
      Parameters:
      maxIdle - the maximum size of the idle pool

    • getMaxWait

      int getMaxWait()
      The maximum number of milliseconds that the pool will wait (when there are no available connections and the getMaxActive() has been reached) for a connection to be returned before throwing an exception. A value less than or equal to zero makes the pool wait indefinitely for a connection to be returned instead of timing out. Default value is 30000 (30 seconds)
      Returns:
      the number of milliseconds to wait for a connection to become available if the pool is maxed out.

    • setMaxWait

      void setMaxWait(int maxWait)
      The maximum number of milliseconds that the pool will wait (when there are no available connections and the getMaxActive() has been reached) for a connection to be returned before throwing an exception. A value less than or equal to zero makes the pool wait indefinitely for a connection to be returned instead of timing out. Default value is 30000 (30 seconds)
      Parameters:
      maxWait - the maximum number of milliseconds to wait.

    • getMinEvictableIdleTimeMillis

      int getMinEvictableIdleTimeMillis()
      The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).
      Returns:
      the minimum amount of idle time in milliseconds before a connection is considered idle and eligible for eviction.

    • setMinEvictableIdleTimeMillis

      void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
      The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).
      Parameters:
      minEvictableIdleTimeMillis - the number of milliseconds a connection must be idle to be eligible for eviction.

    • getMinIdle

      int getMinIdle()
      The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail and connections get closed. The default is the value getInitialSize() had when this configuration was constructed; changing initialSize later does not move it, so set this explicitly to change the floor (also see setTestWhileIdle(boolean)). The eviction run normally keeps the total number of connections in the pool - idle plus busy - at or above this value, hence the number of actual connections can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive(). A connection left over from an earlier pool generation is released regardless, so an explicit idle check after a purge can take the pool below the floor.
      Returns:
      the minimum number of idle or established connections

    • setMinIdle

      void setMinIdle(int minIdle)
      The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail and connections get closed. The default is the value getInitialSize() had when this configuration was constructed; changing initialSize later does not move it, so set this explicitly to change the floor (also see setTestWhileIdle(boolean)). The eviction run normally keeps the total number of connections in the pool - idle plus busy - at or above this value, hence the number of actual connections can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive(). A connection left over from an earlier pool generation is released regardless, so an explicit idle check after a purge can take the pool below the floor.
      Parameters:
      minIdle - the minimum number of idle or established connections

    • getName

      String getName()
      Returns the name of the connection pool. Tomcat gives every pool it manages a name of its own. By default a name unique within this class loader is assigned; it is a counter, so it is unique but predictable, not random. Two class loaders that each load this module can therefore produce the same default name, which the pool's statistics and JMX registration treat as the same name: give pools that must coexist a name of their own. A duplicate name among live pools is reported as an error by the query reporting interceptors.
      Returns:
      the name of the pool, unique within this class loader by default

    • setName

      void setName(String name)
      Sets the name of the connection pool
      Parameters:
      name - the name of the pool, unique among the live pools that share its statistics and JMX space

    • getNumTestsPerEvictionRun

      int getNumTestsPerEvictionRun()
      Property not used
      Returns:
      the stored value, which the pool never reads

    • setNumTestsPerEvictionRun

      void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
      Property not used
      Parameters:
      numTestsPerEvictionRun - parameter ignored.

    • getPassword

      String getPassword()
      Returns the password used when establishing connections to the database. Some implementations mask the value - the DataSourceProxy and the JMX bean return a placeholder instead of the password so that it cannot be read out through JMX - so a consumer of this contract must not treat the returned string as the configured password.
      Returns:
      the password in string format, or a masking placeholder in implementations that hide it

    • setPassword

      void setPassword(String password)
      Sets the password to establish the connection with. The password will be included as a database property with the name 'password'. A null password removes that entry instead, so that a credential which has been taken away is not left behind in the database properties to keep authenticating connections - the connect path lets a non-null password override the database property, but a removed one has nothing to override with. A configuration whose database properties are null has no property collection to hold the entry.
      Parameters:
      password - The password
      See Also:

    • getPoolName

      String getPoolName()
      Returns the name of the connection pool. This is the same value as returned by getName().
      Returns:
      the pool name

    • getUsername

      String getUsername()
      Returns the username used to establish the connection with
      Returns:
      the username used to establish the connection with

    • setUsername

      void setUsername(String username)
      Sets the username used to establish the connection with It will also be a property called 'user' in the database properties. A null user name removes that entry instead, as setPassword(String) does its password, and for the same reason.
      Parameters:
      username - The user name
      See Also:

    • isRemoveAbandoned

      boolean isRemoveAbandoned()
      boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the getRemoveAbandonedTimeout() and the condition for getAbandonWhenPercentageFull() is met. Setting this to true can recover db connections from applications that fail to close a connection. See also isLogAbandoned() The default value is false.
      Returns:
      true if abandoned connections can be closed and expelled out of the pool

    • setRemoveAbandoned

      void setRemoveAbandoned(boolean removeAbandoned)
      boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the getRemoveAbandonedTimeout() and the condition for getAbandonWhenPercentageFull() is met. Setting this to true can recover db connections from applications that fail to close a connection. See also isLogAbandoned() The default value is false.
      Parameters:
      removeAbandoned - set to true if abandoned connections can be closed and expelled out of the pool

    • setRemoveAbandonedTimeout

      void setRemoveAbandonedTimeout(int removeAbandonedTimeout)
      The time in seconds before a connection can be considered abandoned. The timer can be reset upon queries using an interceptor.
      Parameters:
      removeAbandonedTimeout - the time in seconds before a used connection can be considered abandoned
      See Also:

    • getRemoveAbandonedTimeout

      int getRemoveAbandonedTimeout()
      The time in seconds before a connection can be considered abandoned. The timer can be reset upon queries using an interceptor.
      Returns:
      the time in seconds before a used connection can be considered abandoned
      See Also:

    • isTestOnBorrow

      boolean isTestOnBorrow()
      The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, a reconnection of the same pooled connection is attempted and validated again; if that also fails, the object is dropped from the pool and the borrow fails with an SQLException. NOTE - if no validationQuery is set, Connection.isValid(int) is used to validate the connection. Default value is false In order to have a more efficient validation, see setValidationInterval(long)
      Returns:
      true if the connection is to be validated upon borrowing a connection from the pool
      See Also:

    • setTestOnBorrow

      void setTestOnBorrow(boolean testOnBorrow)
      The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, a reconnection of the same pooled connection is attempted and validated again; if that also fails, the object is dropped from the pool and the borrow fails with an SQLException. NOTE - if no validationQuery is set, Connection.isValid(int) is used to validate the connection. Default value is false In order to have a more efficient validation, see setValidationInterval(long)
      Parameters:
      testOnBorrow - set to true if validation should take place before a connection is handed out to the application
      See Also:

    • isTestOnReturn

      boolean isTestOnReturn()
      The indication of whether objects will be validated after being returned to the pool. If the object fails to validate, it will be dropped from the pool. NOTE - if no validationQuery is set, Connection.isValid(int) is used to validate the connection. Default value is false In order to have a more efficient validation, see setValidationInterval(long)
      Returns:
      true if validation should take place after a connection is returned to the pool
      See Also:

    • setTestOnReturn

      void setTestOnReturn(boolean testOnReturn)
      The indication of whether objects will be validated after being returned to the pool. If the object fails to validate, it will be dropped from the pool. NOTE - if no validationQuery is set, Connection.isValid(int) is used to validate the connection. Default value is false In order to have a more efficient validation, see setValidationInterval(long)
      Parameters:
      testOnReturn - true if validation should take place after a connection is returned to the pool
      See Also:

    • isTestWhileIdle

      boolean isTestWhileIdle()
      Set to true if query validation should take place while the connection is idle.
      Returns:
      true if validation should take place during idle checks
      See Also:

    • setTestWhileIdle

      void setTestWhileIdle(boolean testWhileIdle)
      Set to true if query validation should take place while the connection is idle.
      Parameters:
      testWhileIdle - true if validation should take place during idle checks
      See Also:

    • getTimeBetweenEvictionRunsMillis

      int getTimeBetweenEvictionRunsMillis()
      The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool. The default value is 5000 (5 seconds)
      Returns:
      the sleep time in between validations in milliseconds

    • setTimeBetweenEvictionRunsMillis

      void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)
      The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool. The default value is 5000 (5 seconds)
      Parameters:
      timeBetweenEvictionRunsMillis - the sleep time in between validations in milliseconds

    • getUrl

      String getUrl()
      The URL used to connect to the database
      Returns:
      the configured URL for this connection pool
      See Also:

    • setUrl

      void setUrl(String url)
      Sets the URL used to connect to the database
      Parameters:
      url - the configured URL for this connection pool
      See Also:

    • getValidationQuery

      String getValidationQuery()
      The SQL query that will be used to validate connections from this pool before returning them to the caller or pool. If specified, this query does not have to return any data, it just can't throw an SQLException. The default value is null. A blank query means the unset value: no statement, the built-in Connection.isValid(int) check runs instead. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server)
      Returns:
      the query used for validation or null if no validation is performed

    • setValidationQuery

      void setValidationQuery(String validationQuery)
      The SQL query that will be used to validate connections from this pool before returning them to the caller or pool. If specified, this query does not have to return any data, it just can't throw an SQLException. The default value is null. A blank query is stored as the unset value: a configuration surface that cannot express null is written empty to mean "no statement", and no statement can be blank. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server)
      Parameters:
      validationQuery - the query used for validation, or null or a blank string if no validation query is set

    • getValidationQueryTimeout

      int getValidationQueryTimeout()
      The timeout in seconds before a connection validation queries fail. A value less than or equal to zero will disable this feature. Defaults to -1.
      Returns:
      the timeout value in seconds

    • setValidationQueryTimeout

      void setValidationQueryTimeout(int validationQueryTimeout)
      The timeout in seconds before a connection validation queries fail. A value less than or equal to zero will disable this feature. Defaults to -1.
      Parameters:
      validationQueryTimeout - The timeout value

    • getValidatorClassName

      String getValidatorClassName()
      Return the name of the optional validator class - may be null.
      Returns:
      the name of the optional validator class - may be null

    • setValidatorClassName

      void setValidatorClassName(String className)
      Set the name for an optional validator class which will be used in place of test queries. If set to null, standard validation will be used.
      Parameters:
      className - the name of the optional validator class

    • getValidator

      Validator getValidator()
      Returns the validator object used for connection validation. May be null if the pool is using a standard validation query instead.
      Returns:
      the optional validator object - may be null

    • setValidator

      void setValidator(Validator validator)
      Sets the validator object If this is a non null object, it will be used as a validator instead of the validationQuery If this is null, remove the usage of the validator.
      Parameters:
      validator - The validator object

    • getValidationInterval

      long getValidationInterval()
      avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 3000 (3 seconds).
      Returns:
      the validation interval in milliseconds

    • setValidationInterval

      void setValidationInterval(long validationInterval)
      avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 3000 (3 seconds).
      Parameters:
      validationInterval - the validation interval in milliseconds

    • getInitSQL

      String getInitSQL()
      A custom query to be run when a connection is first created. The default value is null. This query only runs once per connection, and that is when a new connection is established to the database. If this value is non null, it will replace the validation query during connection creation.

      The query runs while the pool is initializing the freshly established session, and the pool terminates the transaction it executes into by commit, so its effects - a data change or a session setting - persist for the lifetime of the connection even when the pool runs with auto commit off. A validation query follows the opposite rule and terminates an open transaction by rollback, so a health check never commits application work. A pool configured with a custom Validator does not run this query at all: the validator replaces the validation itself.

      Returns:
      the init SQL used to run against the DB or null if not set

    • setInitSQL

      void setInitSQL(String initSQL)
      A custom query to be run when a connection is first created. The default value is null. This query only runs once per connection, and that is when a new connection is established to the database. If this value is non null, it will replace the validation query during connection creation.

      The query runs while the pool is initializing the freshly established session, and the pool terminates the transaction it executes into by commit, so its effects - a data change or a session setting - persist for the lifetime of the connection even when the pool runs with auto commit off. A validation query follows the opposite rule and terminates an open transaction by rollback, so a health check never commits application work. A pool configured with a custom Validator does not run this query at all: the validator replaces the validation itself.

      Parameters:
      initSQL - the init SQL used to run against the DB or null if no query should be executed

    • isTestOnConnect

      boolean isTestOnConnect()
      Returns true if we should run the validation query when connecting to the database for the first time on a connection. Normally this is always set to false, unless one wants to use the validationQuery as an init query.
      Returns:
      true if we should run the validation query upon connect

    • setTestOnConnect

      void setTestOnConnect(boolean testOnConnect)
      Set to true if we should run the validation query when connecting to the database for the first time on a connection. Normally this is always set to false, unless one wants to use the validationQuery as an init query. Setting an setInitSQL(String) will override this setting, as the init SQL will be used instead of the validation query
      Parameters:
      testOnConnect - set to true if we should run the validation query upon connect

    • getJdbcInterceptors

      String getJdbcInterceptors()
      A semicolon separated list of classnames extending JdbcInterceptor class. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. Example interceptors are StatementFinalizer to close all used statements during the session. ResetAbandonedTimer resets the timer upon any activity on the connection, upon any statement execution and upon any read of a result set, whether the operation succeeded or failed. ConnectionState caches the auto commit, read only, transaction isolation and catalog settings to avoid round trips to the DB. The default value is null.
      Returns:
      the interceptors that are used for connections. Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'

    • setJdbcInterceptors

      void setJdbcInterceptors(String jdbcInterceptors)
      A semicolon separated list of classnames extending JdbcInterceptor class. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. Example interceptors are StatementFinalizer to close all used statements during the session. ResetAbandonedTimer resets the timer upon any activity on the connection, upon any statement execution and upon any read of a result set, whether the operation succeeded or failed. ConnectionState caches the auto commit, read only, transaction isolation and catalog settings to avoid round trips to the DB. The default value is null.
      Parameters:
      jdbcInterceptors - the interceptors that are used for connections. Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'

    • getJdbcInterceptorsAsArray

      PoolProperties.InterceptorDefinition[] getJdbcInterceptorsAsArray()
      Returns the getJdbcInterceptors() as an array of objects with properties and the classes.
      Returns:
      an array of interceptors that have been configured

    • isJmxEnabled

      boolean isJmxEnabled()
      If set to true, the connection pool creates a ConnectionPoolMBean object that can be registered with JMX to receive notifications and state about the pool. The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
      Returns:
      true if the mbean object will be created upon startup.

    • setJmxEnabled

      void setJmxEnabled(boolean jmxEnabled)
      If set to true, the connection pool creates a ConnectionPoolMBean object that can be registered with JMX to receive notifications and state about the pool. The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
      Parameters:
      jmxEnabled - set to true if the mbean object should be created upon startup.

    • isPoolSweeperEnabled

      boolean isPoolSweeperEnabled()
      Returns true if the pool sweeper is enabled for the connection pool. The pool sweeper is enabled if any settings that require async intervention in the pool are turned on. Implementations are expected to run the background maintenance whenever boolean timer = getTimeBetweenEvictionRunsMillis()>0; boolean result = timer && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); result = result || (timer && getSuspectTimeout()>0); result = result || (timer && isTestWhileIdle()); result = result || (timer && getMinEvictableIdleTimeMillis()>0); result = result || (timer && getMaxAge()>0); return result; so enabling the maintenance when any one of these triggers is turned on satisfies the contract. With the defaults shipped by PoolProperties the sweeper is enabled. When it runs, the background cleaner thread checks for abandoned connections when isRemoveAbandoned() is set, marks and reports connections that exceeded getSuspectTimeout(), evicts idle connections towards getMinIdle(), validates idle connections when isTestWhileIdle() is set and reconnects idle connections that exceeded getMaxAge(). While the sweeper is enabled, the pool also takes the per-connection lock when borrowing and returning connections (the same lock getUseLock() forces on) and returned connections are kept beyond getMaxIdle(), letting the idle pool grow towards getMaxActive() as the cleaner trims it.
      Returns:
      true if a background thread is or will be enabled for this pool

    • isUseEquals

      boolean isUseEquals()
      Set to true if you wish the ProxyConnection class to use String.equals instead of == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true.
      Returns:
      true if pool uses String.equals(Object) instead of == when comparing method names on Connection methods

    • setUseEquals

      void setUseEquals(boolean useEquals)
      Set to true if you wish the ProxyConnection class to use String.equals instead of == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true.
      Parameters:
      useEquals - set to true if the pool should use String.equals(Object) instead of == when comparing method names on Connection methods

    • getMaxAge

      long getMaxAge()
      Time in milliseconds to keep this connection before reconnecting. When a connection is idle, returned to the pool or borrowed from the pool, the pool will check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, it reconnects. Note that the age of idle connections will only be checked if getTimeBetweenEvictionRunsMillis() returns a value greater than 0. The default value is 0, which implies that connections will be left open and no age checks will be done. This is a useful setting for database sessions that leak memory as it ensures that the session will have a finite life span.
      Returns:
      the time in milliseconds a connection will be open for when used

    • setMaxAge

      void setMaxAge(long maxAge)
      Time in milliseconds to keep this connection before reconnecting. When a connection is idle, returned to the pool or borrowed from the pool, the pool will check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, it reconnects. Note that the age of idle connections will only be checked if getTimeBetweenEvictionRunsMillis() returns a value greater than 0. The default value is 0, which implies that connections will be left open and no age checks will be done. This is a useful setting for database sessions that leak memory as it ensures that the session will have a finite life span.
      Parameters:
      maxAge - the time in milliseconds a connection will be open for when used

    • getUseLock

      boolean getUseLock()
      Return true if a lock should be used when operations are performed on the connection object. Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
      Returns:
      true if a lock is used.

    • setUseLock

      void setUseLock(boolean useLock)
      Set to true if a lock should be used when operations are performed on the connection object. Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
      Parameters:
      useLock - set to true if a lock should be used on connection operations

    • setSuspectTimeout

      void setSuspectTimeout(int seconds)
      Similar to setRemoveAbandonedTimeout(int) but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if isLogAbandoned() returns true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets logged and a JMX notification gets sent once.
      Parameters:
      seconds - - the amount of time in seconds that has to pass before a connection is marked suspect.

    • getSuspectTimeout

      int getSuspectTimeout()
      Returns the time in seconds to pass before a connection is marked an abandoned suspect. Any value lesser than or equal to 0 means the check is disabled.
      Returns:
      Returns the time in seconds to pass before a connection is marked an abandoned suspect.

    • setDataSource

      void setDataSource(Object ds)
      Injects a datasource that will be used to retrieve/create connections. If a data source is set, the getUrl() and getDriverClassName() methods are ignored and not used by the pool. If the getUsername() and getPassword() values are set, the method DataSource.getConnection(String, String) method will be called instead of the DataSource.getConnection() method. If the data source implements XADataSource the methods XADataSource.getXAConnection() and XADataSource.getXAConnection(String,String) will be invoked. If it implements ConnectionPoolDataSource the methods ConnectionPoolDataSource.getPooledConnection() and ConnectionPoolDataSource.getPooledConnection(String,String) will be invoked instead.
      Parameters:
      ds - the DataSource to be used for creating connections to be pooled.

    • getDataSource

      Object getDataSource()
      Returns a datasource, if one exists that is being used to create connections. This method will return null if the pool is using a Driver
      Returns:
      the backing object - a DataSource, XADataSource or ConnectionPoolDataSource - used for creating connections to be pooled, or null if a Driver is used.

    • setDataSourceJNDI

      void setDataSourceJNDI(String jndiDS)
      Configures a JNDI name for the backing data source. Instead of injecting the object through setDataSource(Object), this names it. The name is resolved by DataSourceFactory, which looks it up when the pool is created through the factory and JNDI path and injects the found object through setDataSource(Object); after that lookup, getDataSource() does not return null. Nothing else performs the lookup: set on a pool configured programmatically, the property never becomes a data source and the pool keeps connecting through the driver properties.
      Parameters:
      jndiDS - the JNDI name of the data source to wrap

    • getDataSourceJNDI

      String getDataSourceJNDI()
      Returns the JNDI string configured for data source usage.
      Returns:
      the JNDI string or null if not set

    • isAlternateUsernameAllowed

      boolean isAlternateUsernameAllowed()
      Returns true if the call getConnection(username,password) is allowed. This is used for when the pool is used by an application accessing multiple schemas. There is a performance impact turning this option on.
      Returns:
      true if getConnection(username,password) is honored, false if it is ignored.

    • setAlternateUsernameAllowed

      void setAlternateUsernameAllowed(boolean alternateUsernameAllowed)
      Set to true if the call getConnection(username,password) is allowed and honored. This is used for when the pool is used by an application accessing multiple schemas. There is a performance impact turning this option on, even when not used due to username checks.
      Parameters:
      alternateUsernameAllowed - - set true if getConnection(username,password) is honored, false if it is to be ignored.

    • setCommitOnReturn

      void setCommitOnReturn(boolean commitOnReturn)
      Set to true if you want the connection pool to commit any pending transaction when a connection is returned. The default value is false, as this could result in committing data. This parameter is ignored if setRollbackOnReturn(boolean) is also set to true. The commit is only performed when the returned connection is actually in a transaction.
      Parameters:
      commitOnReturn - set to true if the pool should call Connection.commit() when a connection is returned to the pool. Default is false

    • getCommitOnReturn

      boolean getCommitOnReturn()
      Returns whether the pool commits any pending transaction when a connection is returned. See setCommitOnReturn(boolean) for details.
      Returns:
      true if the pool should commit when a connection is returned to it

    • setRollbackOnReturn

      void setRollbackOnReturn(boolean rollbackOnReturn)
      Set to true if you want the connection pool to rollback any pending transaction when a connection is returned. The default value is false, as this could result in discarding data the application has not committed. The rollback is only performed when the returned connection is actually in a transaction.
      Parameters:
      rollbackOnReturn - set to true if the pool should call Connection.rollback() when a connection is returned to the pool. Default is false

    • getRollbackOnReturn

      boolean getRollbackOnReturn()
      Returns whether the pool rolls back any pending transaction when a connection is returned. See setRollbackOnReturn(boolean) for details.
      Returns:
      true if the pool should rollback when a connection is returned to it

    • setUseDisposableConnectionFacade

      @Deprecated void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade)
      Deprecated.
      The disposable connection facade is always used, so this property no longer has any effect. Setting it to false used to hand out connection handles that stayed usable, or worse, able to return and drive the connection of a later borrower.
      Stores the value of the deprecated useDisposableConnectionFacade property. The pool always wraps the connection handle in a facade that disallows use of the connection after Connection.close() has been called, whatever value is stored here.
      Parameters:
      useDisposableConnectionFacade - the configured value, retained but without effect

    • getUseDisposableConnectionFacade

      @Deprecated boolean getUseDisposableConnectionFacade()
      Deprecated.
      The disposable connection facade is always used, so this property no longer has any effect.
      Returns the value stored for the deprecated useDisposableConnectionFacade property. The pool always wraps the connection handle in a facade that disallows use of the connection after Connection.close() has been called, whatever value is returned here.
      Returns:
      the configured value, retained but without effect

    • setLogValidationErrors

      void setLogValidationErrors(boolean logValidationErrors)
      Set to true if you wish that errors from validation should be logged as error messages.
      Parameters:
      logValidationErrors - set to true to log validation errors

    • getLogValidationErrors

      boolean getLogValidationErrors()
      Returns true if errors that happen during validation will be logged
      Returns:
      true if errors that happen during validation will be logged

    • getPropagateInterruptState

      boolean getPropagateInterruptState()
      Returns true if the pool is configured to propagate interrupt state of a thread. A thread waiting for a connection, can have its wait interrupted, and by default will clear the interrupt flag and throw a SQLException reporting the interrupted wait, with the InterruptedException as its cause.
      Returns:
      true if the pool is configured to propagate and not clear the thread interrupt state

    • setPropagateInterruptState

      void setPropagateInterruptState(boolean propagateInterruptState)
      Configure the pool to propagate interrupt state for interrupted threads waiting for a connection A thread waiting for a connection, can have its wait interrupted, and by default will clear the interrupt flag and throw a SQLException reporting the interrupted wait, with the InterruptedException as its cause. If set to true, this behavior will change, while the SQLException is still thrown, the threads interrupted state is still set.
      Parameters:
      propagateInterruptState - - set to true to not clear, but propagate, a threads interrupted state.

    • setIgnoreExceptionOnPreLoad

      void setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad)
      Set to true if you want to ignore error of connection creation while initializing the pool. Set to false if you want to fail the initialization of the pool by throwing exception.
      Parameters:
      ignoreExceptionOnPreLoad - set to true if you want to ignore error of connection creation while initializing the pool.

    • isIgnoreExceptionOnPreLoad

      boolean isIgnoreExceptionOnPreLoad()
      Returns whether exceptions during connection creation at pool initialization should be ignored. See setIgnoreExceptionOnPreLoad(boolean) for details.
      Returns:
      true to ignore exceptions during pre-load

    • setUseStatementFacade

      @Deprecated void setUseStatementFacade(boolean useStatementFacade)
      Deprecated.
      The statement facade is always used, so this property no longer has any effect. Setting it to false used to leave statement and result set handles usable after the borrow they came from had ended, so a handle kept by the application could go on executing on the session the next borrower held, and Statement.getConnection() returned the driver's own connection, which survives the borrow and bypasses every configured interceptor.
      Stores the value of the deprecated useStatementFacade property. The pool always wraps the statements it hands out - and the result sets read from them - in a facade, whatever value is stored here. That facade answers equals(), hashCode() and toString() on closed statements, answers Statement.getConnection() with the pooled connection the statement was created from, and stops the statement and its result sets from working once that connection has been returned to the pool.
      Parameters:
      useStatementFacade - the configured value, retained but without effect

    • getUseStatementFacade

      @Deprecated boolean getUseStatementFacade()
      Deprecated.
      The statement facade is always used, so this property no longer has any effect.
      Returns the value stored for the deprecated useStatementFacade property. The pool always wraps the statements it hands out - and the result sets read from them - in a facade, whatever value is returned here.
      Returns:
      the configured value, retained but without effect