Interface ConnectionPoolMBean

All Superinterfaces:

PoolConfiguration

All Known Implementing Classes:

ConnectionPool, DataSource, XADataSource

public interface ConnectionPoolMBean
extends PoolConfiguration

JMX MBean interface for monitoring and managing a JDBC connection pool.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FAILED_QUERY_NOTIFICATION	Notification type sent when the SlowQueryReportJmx interceptor reports a query that failed.
static final String	NOTIFY_ABANDON	Notification type sent when a connection that has been checked out longer than the remove-abandoned timeout is abandoned and removed from the pool.
static final String	NOTIFY_CONNECT	Notification type sent when the pool cannot establish a physical connection to the database.
static final String	NOTIFY_INIT	Notification type sent when the initialization of the pool fails, because an interceptor could not be started or because an initial connection of the pool could not be created and the failure is not ignored through ignoreExceptionOnPreLoad.
static final String	POOL_EMPTY	Notification type sent when a borrow from the pool fails because the pool is empty: the borrower was not willing to wait for a connection or its wait timed out.
static final String	SLOW_QUERY_NOTIFICATION	Notification type sent when the SlowQueryReportJmx interceptor reports a query that took longer than its configured threshold.
static final String	SUSPECT_ABANDONED_NOTIFICATION	Notification type sent when the pool marks a connection as suspect because it has been checked out longer than the suspect timeout and is therefore suspected of having been abandoned.
static final String	SUSPECT_RETURNED_NOTIFICATION	Notification type sent when a connection that the pool had marked as suspect is returned to the pool.

Fields inherited from interface PoolConfiguration

PKG_PREFIX

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
void	checkAbandoned()	Checks for and removes abandoned connections from the pool.
void	checkIdle()	Checks and cleans up idle connections in the pool.
int	getActive()	Returns the number of active (in-use) connections.
long	getBorrowedCount()	Returns the total number of connections borrowed since pool creation.
long	getCreatedCount()	Returns the total number of connections created since pool creation.
int	getIdle()	Returns the number of idle connections in the pool.
int	getNumActive()	Returns the number of active (in-use) connections.
int	getNumIdle()	Returns the number of idle connections in the pool.
long	getReconnectedCount()	Returns the total number of reconnections since pool creation.
long	getReleasedCount()	Returns the total number of connections released since pool creation.
long	getReleasedIdleCount()	Returns the total number of idle connections released by the pool cleaner.
long	getRemoveAbandonedCount()	Returns the total number of connections removed due to abandonment.
long	getReturnedCount()	Returns the total number of connections returned since pool creation.
int	getSize()	Returns the total number of connections in the pool.
int	getWaitCount()	Returns the number of threads waiting for a connection.
void	purge()	Purges all connections in the pool.
void	purgeOnReturn()	Purges connections when they are returned from the pool.
void	resetStats()	reset the statistics of this pool.
void	testIdle()	Validates all idle connections in the pool.

Methods inherited from interface PoolConfiguration

getAbandonWhenPercentageFull, getCommitOnReturn, getConnectionProperties, getDataSource, getDataSourceJNDI, getDbProperties, getDefaultAutoCommit, getDefaultCatalog, getDefaultReadOnly, getDefaultTransactionIsolation, getDriverClassName, getInitialSize, getInitSQL, getJdbcInterceptors, getJdbcInterceptorsAsArray, getLogValidationErrors, getMaxActive, getMaxAge, getMaxIdle, getMaxWait, getMinEvictableIdleTimeMillis, getMinIdle, getName, getNumTestsPerEvictionRun, getPassword, getPoolName, getPropagateInterruptState, getRemoveAbandonedTimeout, getRollbackOnReturn, getSuspectTimeout, getTimeBetweenEvictionRunsMillis, getUrl, getUseDisposableConnectionFacade, getUseLock, getUsername, getUseStatementFacade, getValidationInterval, getValidationQuery, getValidationQueryTimeout, getValidator, getValidatorClassName, isAccessToUnderlyingConnectionAllowed, isAlternateUsernameAllowed, isDefaultAutoCommit, isDefaultReadOnly, isFairQueue, isIgnoreExceptionOnPreLoad, isJmxEnabled, isLogAbandoned, isPoolSweeperEnabled, isRemoveAbandoned, isTestOnBorrow, isTestOnConnect, isTestOnReturn, isTestWhileIdle, isUseEquals, setAbandonWhenPercentageFull, setAccessToUnderlyingConnectionAllowed, setAlternateUsernameAllowed, setCommitOnReturn, setConnectionProperties, setDataSource, setDataSourceJNDI, setDbProperties, setDefaultAutoCommit, setDefaultCatalog, setDefaultReadOnly, setDefaultTransactionIsolation, setDriverClassName, setFairQueue, setIgnoreExceptionOnPreLoad, setInitialSize, setInitSQL, setJdbcInterceptors, setJmxEnabled, setLogAbandoned, setLogValidationErrors, setMaxActive, setMaxAge, setMaxIdle, setMaxWait, setMinEvictableIdleTimeMillis, setMinIdle, setName, setNumTestsPerEvictionRun, setPassword, setPropagateInterruptState, setRemoveAbandoned, setRemoveAbandonedTimeout, setRollbackOnReturn, setSuspectTimeout, setTestOnBorrow, setTestOnConnect, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRunsMillis, setUrl, setUseDisposableConnectionFacade, setUseEquals, setUseLock, setUsername, setUseStatementFacade, setValidationInterval, setValidationQuery, setValidationQueryTimeout, setValidator, setValidatorClassName

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()	Returns whether the pool commits any pending transaction when a connection is returned.
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 PoolConfiguration.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 PoolConfiguration.isPoolSweeperEnabled() returns false.
int	getMaxWait()	The maximum number of milliseconds that the pool will wait (when there are no available connections and the PoolConfiguration.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()	Returns the name of the connection pool.
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()	Returns whether the pool rolls back any pending transaction when a connection is returned.
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()	Deprecated. The disposable connection facade is always used, so this property no longer has any effect.
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()	Deprecated. The statement facade is always used, so this property no longer has any effect.
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()	Returns the validator object used for connection validation.
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()	Returns whether exceptions during connection creation at pool initialization should be ignored.
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 PoolConfiguration.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 PoolConfiguration.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 PoolConfiguration.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 PoolConfiguration.setRemoveAbandonedTimeout(int) but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if PoolConfiguration.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)	Deprecated. The disposable connection facade is always used, so this property no longer has any effect.
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)	Deprecated. The statement facade is always used, so this property no longer has any effect.
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

NOTIFY_INIT

static final String NOTIFY_INIT

Notification type sent when the initialization of the pool fails, because an interceptor could not be started or because an initial connection of the pool could not be created and the failure is not ignored through ignoreExceptionOnPreLoad. The notification message carries the stack trace of the failure.

See Also:

• Constant Field Values

NOTIFY_CONNECT

static final String NOTIFY_CONNECT

Notification type sent when the pool cannot establish a physical connection to the database. The notification message carries the stack trace of the connection failure.

See Also:

• Constant Field Values

NOTIFY_ABANDON

static final String NOTIFY_ABANDON

Notification type sent when a connection that has been checked out longer than the remove-abandoned timeout is abandoned and removed from the pool. The notification message carries the stack trace of where the connection was borrowed, when the pool records those with logAbandoned.

See Also:

• Constant Field Values

SLOW_QUERY_NOTIFICATION

static final String SLOW_QUERY_NOTIFICATION

Notification type sent when the SlowQueryReportJmx interceptor reports a query that took longer than its configured threshold. This pool MBean sends it only when the interceptor is configured with notifyPool=true; otherwise the interceptor's own MBean sends the notification.

See Also:

• Constant Field Values

FAILED_QUERY_NOTIFICATION

static final String FAILED_QUERY_NOTIFICATION

Notification type sent when the SlowQueryReportJmx interceptor reports a query that failed. This pool MBean sends it only when the interceptor is configured with notifyPool=true; otherwise the interceptor's own MBean sends the notification.

See Also:

• Constant Field Values

SUSPECT_ABANDONED_NOTIFICATION

static final String SUSPECT_ABANDONED_NOTIFICATION

Notification type sent when the pool marks a connection as suspect because it has been checked out longer than the suspect timeout and is therefore suspected of having been abandoned. Unlike NOTIFY_ABANDON the connection is not removed from the pool. The notification message carries the stack trace of where the connection was borrowed, when the pool records those with logAbandoned.

See Also:

• Constant Field Values

POOL_EMPTY

static final String POOL_EMPTY

Notification type sent when a borrow from the pool fails because the pool is empty: the borrower was not willing to wait for a connection or its wait timed out. It is sent once per failed borrow, so a pool that stays exhausted sends one per failed borrow attempt.

See Also:

• Constant Field Values

SUSPECT_RETURNED_NOTIFICATION

static final String SUSPECT_RETURNED_NOTIFICATION

Notification type sent when a connection that the pool had marked as suspect is returned to the pool.

See Also:

• Constant Field Values

Method Details

getSize

int getSize()

Returns the total number of connections in the pool.

Returns:

total connection count

getIdle

int getIdle()

Returns the number of idle connections in the pool.

Returns:

idle connection count

getActive

int getActive()

Returns the number of active (in-use) connections.

Returns:

active connection count

getNumIdle

int getNumIdle()

Returns the number of idle connections in the pool.

Returns:

idle connection count

getNumActive

int getNumActive()

Returns the number of active (in-use) connections.

Returns:

active connection count

getWaitCount

int getWaitCount()

Returns the number of threads waiting for a connection.

Returns:

wait count

getBorrowedCount

long getBorrowedCount()

Returns the total number of connections borrowed since pool creation.

Returns:

borrowed count

getReturnedCount

long getReturnedCount()

Returns the total number of connections returned since pool creation.

Returns:

returned count

getCreatedCount

long getCreatedCount()

Returns the total number of connections created since pool creation.

Returns:

created count

getReleasedCount

long getReleasedCount()

Returns the total number of connections released since pool creation.

Returns:

released count

getReconnectedCount

long getReconnectedCount()

Returns the total number of reconnections since pool creation.

Returns:

reconnected count

getRemoveAbandonedCount

long getRemoveAbandonedCount()

Returns the total number of connections removed due to abandonment.

Returns:

abandoned count

getReleasedIdleCount

long getReleasedIdleCount()

Returns the total number of idle connections released by the pool cleaner.

Returns:

released idle count

checkIdle

void checkIdle()

Checks and cleans up idle connections in the pool.

checkAbandoned

void checkAbandoned()

Checks for and removes abandoned connections from the pool.

testIdle

void testIdle()

Validates all idle connections in the pool.

purge

void purge()

Purges all connections in the pool. For connections currently in use, these connections will be purged when returned on the pool. This call also purges connections that are idle and in the pool To only purge used/active connections see purgeOnReturn()

purgeOnReturn

void purgeOnReturn()

Purges connections when they are returned from the pool. This call does not purge idle connections until they are used. To purge idle connections see purge()

resetStats

void resetStats()

reset the statistics of this pool.