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

Fields

Modifier and Type	Field	Description
static final String	PKG_PREFIX	JMX prefix for interceptors that register themselves with JMX

Method Summary

Modifier and Type	Method	Description
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.
boolean	getCommitOnReturn()
String	getConnectionProperties()	The connection properties that will be sent to the JDBC driver when establishing new connections.
Object	getDataSource()	Returns a datasource, if one exists that is being used to create connections.
String	getDataSourceJNDI()	Returns the JNDI string configured for data source usage.
Properties	getDbProperties()	Returns the database properties that are passed into the Driver.connect(String, Properties) method.
Boolean	getDefaultAutoCommit()	The default auto-commit state of connections created by this pool.
String	getDefaultCatalog()	If non null, during connection creation the method Connection.setCatalog(String) will be called with the set value.
Boolean	getDefaultReadOnly()	If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value.
int	getDefaultTransactionIsolation()	Returns the default transaction isolation level.
String	getDriverClassName()	The fully qualified Java class name of the JDBC driver to be used.
int	getInitialSize()	Returns the number of connections that will be established when the connection pool is started.
String	getInitSQL()	A custom query to be run when a connection is first created.
String	getJdbcInterceptors()	A semicolon separated list of classnames extending JdbcInterceptor class.
PoolProperties.InterceptorDefinition[]	getJdbcInterceptorsAsArray()	Returns the getJdbcInterceptors() as an array of objects with properties and the classes.
boolean	getLogValidationErrors()	Returns true if errors that happen during validation will be logged
int	getMaxActive()	The maximum number of active connections that can be allocated from this pool at the same time.
long	getMaxAge()	Time in milliseconds to keep this connection before reconnecting.
int	getMaxIdle()	The maximum number of connections that should be kept in the idle pool if isPoolSweeperEnabled() returns false.
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.
int	getMinEvictableIdleTimeMillis()	The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
int	getMinIdle()	The minimum number of established connections that should be kept in the pool at all times.
String	getName()	Returns the name of the connection pool.
int	getNumTestsPerEvictionRun()	Property not used
String	getPassword()	Returns the password used when establishing connections to the database.
String	getPoolName()
boolean	getPropagateInterruptState()	Returns true if the pool is configured to propagate interrupt state of a thread.
int	getRemoveAbandonedTimeout()	The time in seconds before a connection can be considered abandoned.
boolean	getRollbackOnReturn()
int	getSuspectTimeout()	Returns the time in seconds to pass before a connection is marked an abandoned suspect.
int	getTimeBetweenEvictionRunsMillis()	The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing.
String	getUrl()	The URL used to connect to the database
boolean	getUseDisposableConnectionFacade()	Returns true if this connection pool is configured to use a connection facade to prevent re-use of connection after Connection.close() has been invoked
boolean	getUseLock()	Return true if a lock should be used when operations are performed on the connection object.
String	getUsername()	Returns the username used to establish the connection with
boolean	getUseStatementFacade()	Returns true if 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.
long	getValidationInterval()	avoid excess validation, only run validation at most at this frequency - time in milliseconds.
String	getValidationQuery()	The SQL query that will be used to validate connections from this pool before returning them to the caller or pool.
int	getValidationQueryTimeout()	The timeout in seconds before a connection validation queries fail.
Validator	getValidator()
String	getValidatorClassName()	Return the name of the optional validator class - may be null.
boolean	isAccessToUnderlyingConnectionAllowed()	Property not used.
boolean	isAlternateUsernameAllowed()	Returns true if the call getConnection(username,password) is allowed.
Boolean	isDefaultAutoCommit()	The default auto-commit state of connections created by this pool.
Boolean	isDefaultReadOnly()	If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value.
boolean	isFairQueue()	Returns true if a fair queue is being used by the connection pool
boolean	isIgnoreExceptionOnPreLoad()
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.
boolean	isLogAbandoned()	boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
boolean	isPoolSweeperEnabled()	Returns true if the pool sweeper is enabled for the connection pool.
boolean	isRemoveAbandoned()	boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout.
boolean	isTestOnBorrow()	The indication of whether objects will be validated before being borrowed from the pool.
boolean	isTestOnConnect()	Returns true if we should run the validation query when connecting to the database for the first time on a connection.
boolean	isTestOnReturn()	The indication of whether objects will be validated after being returned to the pool.
boolean	isTestWhileIdle()	Set to true if query validation should take place while the connection is idle.
boolean	isUseEquals()	Set to true if you wish the ProxyConnection class to use String.equals instead of == when comparing method names.
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.
void	setAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed)	No-op
void	setAlternateUsernameAllowed(boolean alternateUsernameAllowed)	Set to true if the call getConnection(username,password) is allowed and honored..
void	setCommitOnReturn(boolean commitOnReturn)	Set to true if you want the connection pool to commit any pending transaction when a connection is returned.
void	setConnectionProperties(String connectionProperties)	The properties that will be passed into Driver.connect(String, Properties) method.
void	setDataSource(Object ds)	Injects a datasource that will be used to retrieve/create connections.
void	setDataSourceJNDI(String jndiDS)	Configure the connection pool to use a DataSource according to setDataSource(Object) But instead of injecting the object, specify the JNDI location.
void	setDbProperties(Properties dbProperties)	Overrides the database properties passed into the Driver.connect(String, Properties) method.
void	setDefaultAutoCommit(Boolean defaultAutoCommit)	The default auto-commit state of connections created by this pool.
void	setDefaultCatalog(String defaultCatalog)	If non null, during connection creation the method Connection.setCatalog(String) will be called with the set value.
void	setDefaultReadOnly(Boolean defaultReadOnly)	If non null, during connection creation the method Connection.setReadOnly(boolean) will be called with the set value.
void	setDefaultTransactionIsolation(int defaultTransactionIsolation)	If set to DataSourceFactory.UNKNOWN_TRANSACTIONISOLATION the method Connection.setTransactionIsolation(int) will not be called during connection creation.
void	setDriverClassName(String driverClassName)	The fully qualified Java class name of the JDBC driver to be used.
void	setFairQueue(boolean fairQueue)	Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion.
void	setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad)	Set to true if you want to ignore error of connection creation while initializing the pool.
void	setInitialSize(int initialSize)	Set the number of connections that will be established when the connection pool is started.
void	setInitSQL(String initSQL)	A custom query to be run when a connection is first created.
void	setJdbcInterceptors(String jdbcInterceptors)	A semicolon separated list of classnames extending JdbcInterceptor class.
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.
void	setLogAbandoned(boolean logAbandoned)	boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
void	setLogValidationErrors(boolean logValidationErrors)	Set to true if you wish that errors from validation should be logged as error messages.
void	setMaxActive(int maxActive)	The maximum number of active connections that can be allocated from this pool at the same time.
void	setMaxAge(long maxAge)	Time in milliseconds to keep this connection before reconnecting.
void	setMaxIdle(int maxIdle)	The maximum number of connections that should be kept in the idle pool if isPoolSweeperEnabled() returns false.
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.
void	setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)	The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
void	setMinIdle(int minIdle)	The minimum number of established connections that should be kept in the pool at all times.
void	setName(String name)	Sets the name of the connection pool
void	setNumTestsPerEvictionRun(int numTestsPerEvictionRun)	Property not used
void	setPassword(String password)	Sets the password to establish the connection with.
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 PoolExhaustedException If set to true, this behavior will change, while the PoolExhaustedException is still thrown, the threads interrupted state is still set.
void	setRemoveAbandoned(boolean removeAbandoned)	boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout.
void	setRemoveAbandonedTimeout(int removeAbandonedTimeout)	The time in seconds before a connection can be considered abandoned.
void	setRollbackOnReturn(boolean rollbackOnReturn)	Set to true if you want the connection pool to rollback any pending transaction when a connection is returned.
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.
void	setTestOnBorrow(boolean testOnBorrow)	The indication of whether objects will be validated before being borrowed from the pool.
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.
void	setTestOnReturn(boolean testOnReturn)	The indication of whether objects will be validated after being returned to the pool.
void	setTestWhileIdle(boolean testWhileIdle)	Set to true if query validation should take place while the connection is idle.
void	setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)	The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner and idle pool resizing.
void	setUrl(String url)	Sets the URL used to connect to the database
void	setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade)	If set to true, the connection will be wrapped with facade that will disallow the connection to be used after Connection.close() is called.
void	setUseEquals(boolean useEquals)	Set to true if you wish the ProxyConnection class to use String.equals instead of == when comparing method names.
void	setUseLock(boolean useLock)	Set to true if a lock should be used when operations are performed on the connection object.
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.
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.
void	setValidationInterval(long validationInterval)	avoid excess validation, only run validation at most at this frequency - time in milliseconds.
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.
void	setValidationQueryTimeout(int validationQueryTimeout)	The timeout in seconds before a connection validation queries fail.
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.
void	setValidatorClassName(String className)	Set the name for an optional validator class which will be used in place of test queries.

Field Details

PKG_PREFIX

static final String PKG_PREFIX

JMX prefix for interceptors that register themselves with JMX

See Also:

• Constant Field Values

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

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.

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 the Driver.connect(String, Properties) method.

Returns:

database properties that are passed into the Driver.connect(String, Properties) method.

setDbProperties

void setDbProperties(Properties dbProperties)

Overrides the database properties passed into the Driver.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 the Connection.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 the Connection.setAutoCommit(boolean) method will not be called.)

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

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.

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.

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.

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.

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.

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.

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.

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 the If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() 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 if isPoolSweeperEnabled() returns false. If the If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() 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 the getMaxActive() 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 the getMaxActive() 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 from getInitialSize() (also see setTestWhileIdle(boolean) The idle pool will not shrink below this value during an eviction run, hence the number of actual connections can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive()

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 from getInitialSize() (also see setTestWhileIdle(boolean) The idle pool will not shrink below this value during an eviction run, hence the number of actual connections can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive()

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

void setName(String name)

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

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

Parameters:

password - The password

See Also:

• getDbProperties()

getPoolName

String getPoolName()

Returns:

the pool name

See Also:

• getName()

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.

Parameters:

username - The user name

See Also:

• getDbProperties()

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:

• ResetAbandonedTimer

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:

• ResetAbandonedTimer

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, see setValidationInterval(long)

Returns:

true if the connection is to be validated upon borrowing a connection from the pool

See Also:

• getValidationInterval()

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, see setValidationInterval(long)

Parameters:

testOnBorrow - set to true if validation should take place before a connection is handed out to the application

See Also:

• getValidationInterval()

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, see setValidationInterval(long)

Returns:

true if validation should take place after a connection is returned to the pool

See Also:

• getValidationInterval()

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, see setValidationInterval(long)

Parameters:

testOnReturn - true if validation should take place after a connection is returned to the pool

See Also:

• getValidationInterval()

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:

• setTimeBetweenEvictionRunsMillis(int)

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:

• setTimeBetweenEvictionRunsMillis(int)

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:

• Driver.connect(String, Properties)

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:

• Driver.connect(String, Properties)

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

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

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

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.

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 every operation on the connection or a statement. ConnectionState caches 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

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 every operation on the connection or a statement. ConnectionState caches 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 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 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 on boolean 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 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 false.

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

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.

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 DataSource to be used for creating connections to be pooled or null if a Driver is used.

setDataSourceJNDI

void setDataSourceJNDI(String jndiDS)

Configure the connection pool to use a DataSource according to setDataSource(Object) But instead of injecting the object, specify the JNDI location. After a successful JNDI look, the getDataSource() 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 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 only looked at if the getDefaultAutoCommit() returns false

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:

true if the pool should commit when a connection is returned to it

See Also:

• setCommitOnReturn(boolean)

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 the getDefaultAutoCommit() returns false

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:

true if the pool should rollback when a connection is returned to it

See Also:

• setRollbackOnReturn(boolean)

setUseDisposableConnectionFacade

void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade)

If set to true, the connection will be wrapped with facade that will disallow the connection to be used after Connection.close() is called. If set to true, after Connection.close() all calls except Connection.close() and Connection.isClosed() will throw an exception.

Parameters:

useDisposableConnectionFacade - true to use a facade

getUseDisposableConnectionFacade

boolean getUseDisposableConnectionFacade()

Returns true if this connection pool is configured to use a connection facade to prevent re-use of connection after Connection.close() has been invoked

Returns:

true if Connection.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 a PoolExhaustedException

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 PoolExhaustedException If set to true, this behavior will change, while the PoolExhaustedException 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:

true to ignore exceptions

See Also:

• setIgnoreExceptionOnPreLoad(boolean)

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 to true to wrap statements

getUseStatementFacade

boolean getUseStatementFacade()

Returns true if 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:

true if the statements are wrapped