Package org.apache.tomcat.jdbc.pool
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final StringJMX prefix for interceptors that register themselves with JMX -
Method Summary
Modifier and TypeMethodDescriptionintConnections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull.booleanThe connection properties that will be sent to the JDBC driver when establishing new connections.Returns a datasource, if one exists that is being used to create connections.Returns the JNDI string configured for data source usage.Returns the database properties that are passed into theDriver.connect(String, Properties)method.The default auto-commit state of connections created by this pool.If non null, during connection creation the methodConnection.setCatalog(String)will be called with the set value.If non null, during connection creation the methodConnection.setReadOnly(boolean)will be called with the set value.intReturns the default transaction isolation level.The fully qualified Java class name of the JDBC driver to be used.intReturns the number of connections that will be established when the connection pool is started.A custom query to be run when a connection is first created.A semicolon separated list of classnames extendingJdbcInterceptorclass.Returns thegetJdbcInterceptors()as an array of objects with properties and the classes.booleanReturns true if errors that happen during validation will be loggedintThe maximum number of active connections that can be allocated from this pool at the same time.longTime in milliseconds to keep this connection before reconnecting.intThe maximum number of connections that should be kept in the idle pool ifisPoolSweeperEnabled()returns false.intThe maximum number of milliseconds that the pool will wait (when there are no available connections and thegetMaxActive()has been reached) for a connection to be returned before throwing an exception.intThe minimum amount of time an object must sit idle in the pool before it is eligible for eviction.intThe minimum number of established connections that should be kept in the pool at all times.getName()Returns the name of the connection pool.intProperty not usedReturns the password used when establishing connections to the database.booleanReturns true if the pool is configured to propagate interrupt state of a thread.intThe time in seconds before a connection can be considered abandoned.booleanintReturns the time in seconds to pass before a connection is marked an abandoned suspect.intThe number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing.getUrl()The URL used to connect to the databasebooleanReturnstrueif this connection pool is configured to use a connection facade to prevent re-use of connection afterConnection.close()has been invokedbooleanReturn true if a lock should be used when operations are performed on the connection object.Returns the username used to establish the connection withbooleanReturnstrueif this connection pool is configured to wrap statements in order to enable equals() and hashCode() methods to be called on the closed statements if any statement proxy is set.longavoid excess validation, only run validation at most at this frequency - time in milliseconds.The SQL query that will be used to validate connections from this pool before returning them to the caller or pool.intThe timeout in seconds before a connection validation queries fail.Return the name of the optional validator class - may be null.booleanProperty not used.booleanReturns true if the callgetConnection(username,password)is allowed.The default auto-commit state of connections created by this pool.If non null, during connection creation the methodConnection.setReadOnly(boolean)will be called with the set value.booleanReturnstrueif a fair queue is being used by the connection poolbooleanbooleanIf set to true, the connection pool creates aConnectionPoolMBeanobject that can be registered with JMX to receive notifications and state about the pool.booleanboolean flag to set if stack traces should be logged for application code which abandoned a Connection.booleanReturns true if the pool sweeper is enabled for the connection pool.booleanboolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout.booleanThe indication of whether objects will be validated before being borrowed from the pool.booleanReturns true if we should run the validation query when connecting to the database for the first time on a connection.booleanThe indication of whether objects will be validated after being returned to the pool.booleanSet to true if query validation should take place while the connection is idle.booleanSet to true if you wish theProxyConnectionclass to useString.equalsinstead of==when comparing method names.voidsetAbandonWhenPercentageFull(int percentage) Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull.voidsetAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed) No-opvoidsetAlternateUsernameAllowed(boolean alternateUsernameAllowed) Set to true if the callgetConnection(username,password)is allowed and honored..voidsetCommitOnReturn(boolean commitOnReturn) Set to true if you want the connection pool to commit any pending transaction when a connection is returned.voidsetConnectionProperties(String connectionProperties) The properties that will be passed intoDriver.connect(String, Properties)method.voidsetDataSource(Object ds) Injects a datasource that will be used to retrieve/create connections.voidsetDataSourceJNDI(String jndiDS) Configure the connection pool to use a DataSource according tosetDataSource(Object)But instead of injecting the object, specify the JNDI location.voidsetDbProperties(Properties dbProperties) Overrides the database properties passed into theDriver.connect(String, Properties)method.voidsetDefaultAutoCommit(Boolean defaultAutoCommit) The default auto-commit state of connections created by this pool.voidsetDefaultCatalog(String defaultCatalog) If non null, during connection creation the methodConnection.setCatalog(String)will be called with the set value.voidsetDefaultReadOnly(Boolean defaultReadOnly) If non null, during connection creation the methodConnection.setReadOnly(boolean)will be called with the set value.voidsetDefaultTransactionIsolation(int defaultTransactionIsolation) If set toDataSourceFactory.UNKNOWN_TRANSACTIONISOLATIONthe methodConnection.setTransactionIsolation(int)will not be called during connection creation.voidsetDriverClassName(String driverClassName) The fully qualified Java class name of the JDBC driver to be used.voidsetFairQueue(boolean fairQueue) Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion.voidsetIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad) Set to true if you want to ignore error of connection creation while initializing the pool.voidsetInitialSize(int initialSize) Set the number of connections that will be established when the connection pool is started.voidsetInitSQL(String initSQL) A custom query to be run when a connection is first created.voidsetJdbcInterceptors(String jdbcInterceptors) A semicolon separated list of classnames extendingJdbcInterceptorclass.voidsetJmxEnabled(boolean jmxEnabled) If set to true, the connection pool creates aConnectionPoolMBeanobject that can be registered with JMX to receive notifications and state about the pool.voidsetLogAbandoned(boolean logAbandoned) boolean flag to set if stack traces should be logged for application code which abandoned a Connection.voidsetLogValidationErrors(boolean logValidationErrors) Set to true if you wish that errors from validation should be logged as error messages.voidsetMaxActive(int maxActive) The maximum number of active connections that can be allocated from this pool at the same time.voidsetMaxAge(long maxAge) Time in milliseconds to keep this connection before reconnecting.voidsetMaxIdle(int maxIdle) The maximum number of connections that should be kept in the idle pool ifisPoolSweeperEnabled()returns false.voidsetMaxWait(int maxWait) The maximum number of milliseconds that the pool will wait (when there are no available connections and thegetMaxActive()has been reached) for a connection to be returned before throwing an exception.voidsetMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis) The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.voidsetMinIdle(int minIdle) The minimum number of established connections that should be kept in the pool at all times.voidSets the name of the connection poolvoidsetNumTestsPerEvictionRun(int numTestsPerEvictionRun) Property not usedvoidsetPassword(String password) Sets the password to establish the connection with.voidsetPropagateInterruptState(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 aPoolExhaustedExceptionIf set to true, this behavior will change, while thePoolExhaustedExceptionis still thrown, the threads interrupted state is still set.voidsetRemoveAbandoned(boolean removeAbandoned) boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout.voidsetRemoveAbandonedTimeout(int removeAbandonedTimeout) The time in seconds before a connection can be considered abandoned.voidsetRollbackOnReturn(boolean rollbackOnReturn) Set to true if you want the connection pool to rollback any pending transaction when a connection is returned.voidsetSuspectTimeout(int seconds) Similar tosetRemoveAbandonedTimeout(int)but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning ifisLogAbandoned()returns true.voidsetTestOnBorrow(boolean testOnBorrow) The indication of whether objects will be validated before being borrowed from the pool.voidsetTestOnConnect(boolean testOnConnect) Set to true if we should run the validation query when connecting to the database for the first time on a connection.voidsetTestOnReturn(boolean testOnReturn) The indication of whether objects will be validated after being returned to the pool.voidsetTestWhileIdle(boolean testWhileIdle) Set to true if query validation should take place while the connection is idle.voidsetTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis) The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing.voidSets the URL used to connect to the databasevoidsetUseDisposableConnectionFacade(boolean useDisposableConnectionFacade) If set totrue, the connection will be wrapped with facade that will disallow the connection to be used afterConnection.close()is called.voidsetUseEquals(boolean useEquals) Set to true if you wish theProxyConnectionclass to useString.equalsinstead of==when comparing method names.voidsetUseLock(boolean useLock) Set to true if a lock should be used when operations are performed on the connection object.voidsetUsername(String username) Sets the username used to establish the connection with It will also be a property called 'user' in the database properties.voidsetUseStatementFacade(boolean useStatementFacade) Set this to true if you wish to wrap statements in order to enable equals() and hashCode() methods to be called on the closed statements if any statement proxy is set.voidsetValidationInterval(long validationInterval) avoid excess validation, only run validation at most at this frequency - time in milliseconds.voidsetValidationQuery(String validationQuery) The SQL query that will be used to validate connections from this pool before returning them to the caller or pool.voidsetValidationQueryTimeout(int validationQueryTimeout) The timeout in seconds before a connection validation queries fail.voidsetValidator(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.voidsetValidatorClassName(String className) Set the name for an optional validator class which will be used in place of test queries.
-
Field Details
-
PKG_PREFIX
JMX prefix for interceptors that register themselves with JMX- See Also:
-
-
Method Details
-
setAbandonWhenPercentageFull
void setAbandonWhenPercentageFull(int percentage) Connections that have been abandoned (timed out) wont 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) wont 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()Returnstrueif a fair queue is being used by the connection pool- Returns:
trueif 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 theFairBlockingQueueimplementation 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-trueto 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. seeDataSourceinterface or call getConnection through reflection or cast the object asPooledConnection- 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
The properties that will be passed intoDriver.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.- Parameters:
connectionProperties- properties - Format of the string is [propertyName=property;]* Example: prop1=value1;prop2=value2
-
getDbProperties
Properties getDbProperties()Returns the database properties that are passed into theDriver.connect(String, Properties)method.- Returns:
- database properties that are passed into the
Driver.connect(String, Properties)method.
-
setDbProperties
Overrides the database properties passed into theDriver.connect(String, Properties)method.- Parameters:
dbProperties- The database properties
-
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 theConnection.setAutoCommit(boolean)method will not be called.)- 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 theConnection.setAutoCommit(boolean)method will not be called.)- Returns:
- the default auto commit setting, null is Driver default.
-
setDefaultAutoCommit
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 theConnection.setAutoCommit(boolean)method will not be called.)- Parameters:
defaultAutoCommit- default auto commit setting, null is Driver default.
-
getDefaultCatalog
String getDefaultCatalog()If non null, during connection creation the methodConnection.setCatalog(String)will be called with the set value.- Returns:
- the default catalog, null if not set and accepting the driver default.
-
setDefaultCatalog
If non null, during connection creation the methodConnection.setCatalog(String)will be called with the set value.- Parameters:
defaultCatalog- null if not set and accepting the driver default.
-
isDefaultReadOnly
Boolean isDefaultReadOnly()If non null, during connection creation the methodConnection.setReadOnly(boolean)will be called with the set value.- 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 methodConnection.setReadOnly(boolean)will be called with the set value.- Returns:
- null if not set and accepting the driver default otherwise the read only value
-
setDefaultReadOnly
If non null, during connection creation the methodConnection.setReadOnly(boolean)will be called with the set value.- Parameters:
defaultReadOnly- null if not set and accepting the driver default.
-
getDefaultTransactionIsolation
int getDefaultTransactionIsolation()Returns the default transaction isolation level. If set toDataSourceFactory.UNKNOWN_TRANSACTIONISOLATIONthe methodConnection.setTransactionIsolation(int)will not be called during connection creation.- Returns:
- driver transaction isolation level, or -1
DataSourceFactory.UNKNOWN_TRANSACTIONISOLATIONif not set.
-
setDefaultTransactionIsolation
void setDefaultTransactionIsolation(int defaultTransactionIsolation) If set toDataSourceFactory.UNKNOWN_TRANSACTIONISOLATIONthe methodConnection.setTransactionIsolation(int)will not be called during connection creation. Otherwise the method will be called with the isolation level set by this property.- Parameters:
defaultTransactionIsolation- a value ofConnection.TRANSACTION_NONE,Connection.TRANSACTION_READ_COMMITTED,Connection.TRANSACTION_READ_UNCOMMITTED,Connection.TRANSACTION_REPEATABLE_READ,Connection.TRANSACTION_SERIALIZABLEorDataSourceFactory.UNKNOWN_TRANSACTIONISOLATIONThe 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
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 aDriverimplementation.
-
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 exceedssetMaxActive(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 whenDataSourceProxy.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 ifisPoolSweeperEnabled()returns false. If the IfisPoolSweeperEnabled()returns true, then the idle pool can grow up togetMaxActive()and will be shrunk according togetMinEvictableIdleTimeMillis()setting. Default value is maxActive:100- 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 ifisPoolSweeperEnabled()returns false. If the IfisPoolSweeperEnabled()returns true, then the idle pool can grow up togetMaxActive()and will be shrunk according togetMinEvictableIdleTimeMillis()setting. Default value is maxActive:100- 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 thegetMaxActive()has been reached) for a connection to be returned before throwing an exception. 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 thegetMaxActive()has been reached) for a connection to be returned before throwing an exception. 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. Default value is derived fromgetInitialSize()(also seesetTestWhileIdle(boolean)The idle pool will not shrink below this value during an eviction run, hence the number of actual connections can be betweengetMinIdle()and somewhere betweengetMaxIdle()andgetMaxActive()- 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. Default value is derived fromgetInitialSize()(also seesetTestWhileIdle(boolean)The idle pool will not shrink below this value during an eviction run, hence the number of actual connections can be betweengetMinIdle()and somewhere betweengetMaxIdle()andgetMaxActive()- Parameters:
minIdle- the minimum number of idle or established connections
-
getName
String getName()Returns the name of the connection pool. By default a JVM unique random name is assigned.- Returns:
- the name of the pool, should be unique in a JVM
-
setName
Sets the name of the connection pool- Parameters:
name- the name of the pool, should be unique in a runtime JVM
-
getNumTestsPerEvictionRun
int getNumTestsPerEvictionRun()Property not used- Returns:
- unknown value
-
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.- Returns:
- the password in string format
-
setPassword
Sets the password to establish the connection with. The password will be included as a database property with the name 'password'.- Parameters:
password- The password- See Also:
-
getPoolName
String getPoolName()- Returns:
- the pool name
- See Also:
-
getUsername
String getUsername()Returns the username used to establish the connection with- Returns:
- the username used to establish the connection with
-
setUsername
Sets the username used to establish the connection with It will also be a property called 'user' in the database properties.- 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 thegetRemoveAbandonedTimeout()and the condition forgetAbandonWhenPercentageFull()is met. Setting this to true can recover db connections from applications that fail to close a connection. See alsoisLogAbandoned()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 thegetRemoveAbandonedTimeout()and the condition forgetAbandonWhenPercentageFull()is met. Setting this to true can recover db connections from applications that fail to close a connection. See alsoisLogAbandoned()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, it will be dropped from the pool, and we will attempt to borrow another. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. Default value is false In order to have a more efficient validation, seesetValidationInterval(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, it will be dropped from the pool, and we will attempt to borrow another. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. Default value is false In order to have a more efficient validation, seesetValidationInterval(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 - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. Default value is false In order to have a more efficient validation, seesetValidationInterval(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 - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. Default value is false In order to have a more efficient validation, seesetValidationInterval(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
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. 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
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. 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 if no validation is performed
-
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
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 optional validator object - may be null
-
setValidator
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.- Returns:
- the init SQL used to run against the DB or null if not set
-
setInitSQL
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.- 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 ansetInitSQL(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 extendingJdbcInterceptorclass. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. Example interceptors areStatementFinalizerto close all used statements during the session.ResetAbandonedTimerresets the timer upon every operation on the connection or a statement.ConnectionStatecaches the auto commit, read only 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
A semicolon separated list of classnames extendingJdbcInterceptorclass. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. Example interceptors areStatementFinalizerto close all used statements during the session.ResetAbandonedTimerresets the timer upon every operation on the connection or a statement.ConnectionStatecaches the auto commit, read only 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 thegetJdbcInterceptors()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 aConnectionPoolMBeanobject 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 aConnectionPoolMBeanobject 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 to 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 onboolean result = getTimeBetweenEvictionRunsMillis()>0; result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); result = result || (isTestWhileIdle() && getValidationQuery()!=null); return result;- Returns:
- true if a background thread is or will be enabled for this pool
-
isUseEquals
boolean isUseEquals()Set to true if you wish theProxyConnectionclass to useString.equalsinstead of==when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value isfalse.- Returns:
- true if pool uses
String.equals(Object)instead of == when comparing method names onConnectionmethods
-
setUseEquals
void setUseEquals(boolean useEquals) Set to true if you wish theProxyConnectionclass to useString.equalsinstead of==when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value isfalse.- Parameters:
useEquals- set to true if the pool should useString.equals(Object)instead of == when comparing method names onConnectionmethods
-
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 ifgetTimeBetweenEvictionRunsMillis()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 ifgetTimeBetweenEvictionRunsMillis()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 tosetRemoveAbandonedTimeout(int)but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning ifisLogAbandoned()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
Injects a datasource that will be used to retrieve/create connections. If a data source is set, thegetUrl()andgetDriverClassName()methods are ignored and not used by the pool. If thegetUsername()andgetPassword()values are set, the methodDataSource.getConnection(String, String)method will be called instead of theDataSource.getConnection()method. If the data source implementsXADataSourcethe methodsXADataSource.getXAConnection()andXADataSource.getXAConnection(String,String)will be invoked.- Parameters:
ds- theDataSourceto 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 aDriver- Returns:
- the
DataSourceto be used for creating connections to be pooled or null if a Driver is used.
-
setDataSourceJNDI
Configure the connection pool to use a DataSource according tosetDataSource(Object)But instead of injecting the object, specify the JNDI location. After a successful JNDI look, thegetDataSource()will not return null.- Parameters:
jndiDS- -the JNDI string @TODO specify the rules here.
-
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 callgetConnection(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 callgetConnection(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 ifgetConnection(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 only looked at if thegetDefaultAutoCommit()returns false- Parameters:
commitOnReturn- set to true if the pool should callConnection.commit()when a connection is returned to the pool. Default is false
-
getCommitOnReturn
boolean getCommitOnReturn()- Returns:
trueif the pool should commit when a connection is returned to it- See Also:
-
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 committing data. This parameter is only looked at if thegetDefaultAutoCommit()returns false- Parameters:
rollbackOnReturn- set to true if the pool should callConnection.rollback()when a connection is returned to the pool. Default is false
-
getRollbackOnReturn
boolean getRollbackOnReturn()- Returns:
trueif the pool should rollback when a connection is returned to it- See Also:
-
setUseDisposableConnectionFacade
void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade) If set totrue, the connection will be wrapped with facade that will disallow the connection to be used afterConnection.close()is called. If set totrue, afterConnection.close()all calls exceptConnection.close()andConnection.isClosed()will throw an exception.- Parameters:
useDisposableConnectionFacade-trueto use a facade
-
getUseDisposableConnectionFacade
boolean getUseDisposableConnectionFacade()Returnstrueif this connection pool is configured to use a connection facade to prevent re-use of connection afterConnection.close()has been invoked- Returns:
trueifConnection.close()has been invoked.
-
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 aPoolExhaustedException- 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 aPoolExhaustedExceptionIf set to true, this behavior will change, while thePoolExhaustedExceptionis 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:
trueto ignore exceptions- See Also:
-
setUseStatementFacade
void setUseStatementFacade(boolean useStatementFacade) Set this to true if you wish to wrap statements in order to enable equals() and hashCode() methods to be called on the closed statements if any statement proxy is set.- Parameters:
useStatementFacade- set totrueto wrap statements
-
getUseStatementFacade
boolean getUseStatementFacade()Returnstrueif this connection pool is configured to wrap statements in order to enable equals() and hashCode() methods to be called on the closed statements if any statement proxy is set.- Returns:
trueif the statements are wrapped
-