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.

Inheriting PoolConfiguration brings this surface the boxed-Boolean accessors isDefaultAutoCommit() and isDefaultReadOnly(), and the JDK's MBean analyzer treats an is... method as a getter only when it returns the primitive boolean: those two are therefore published as operations alongside the DefaultAutoCommit and DefaultReadOnly attributes their get... pair provides. Making either one a primitive boolean getter would hand that attribute two getters, and the MBean could no longer be registered.

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

    • NOTIFY_CONNECT

      static final String NOTIFY_CONNECT
      Notification type sent when the pool cannot establish a physical connection to the database through the driver it instantiated itself, that being the only route on which the pool meets the failure. A pool that takes its sessions from a DataSource - one set through dataSource or resolved from dataSourceJNDI - asks that data source for a session instead, and never sends this notification. The notification message carries the stack trace of the connection failure.
      See Also:

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

    • 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. Nothing reaches a listener that the interceptor does not report, so its logSlow flag - on by default - switches this notification off as well, and a negative threshold keeps every execution out of the slow report. 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:

    • FAILED_QUERY_NOTIFICATION

      static final String FAILED_QUERY_NOTIFICATION
      Notification type sent when the SlowQueryReportJmx interceptor reports a query that failed - a failed execution is reported whatever the threshold is. Nothing reaches a listener that the interceptor does not report, so its logFailed flag, which is off by default, switches this notification off with it. 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:

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

    • 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 reports one per failed borrow attempt. Delivery is best effort: the notification is accepted for delivery or dropped whole, and the queue it is handed to has a fixed capacity, so a pool that reports these faster than its listeners drain them loses notifications - logging each loss - rather than holding them up or growing without limit.
      See Also:

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

  • Method Details

    • getSize

      int getSize()
      Returns the number of connection slots the pool holds right now - the idle ones and the checked out ones together.

      This counts slots, not database sessions, and each of these counts reads the live state for itself. While the pool is establishing connections a slot is claimed before its session is signed on, and releasing a connection to a waiting borrower leaves a wake-up placeholder in the idle queue, so this count - and the idle count - can include an entry with no session behind it. Two of these attributes read at the same moment can still disagree: a Size against Idle plus Active, or an Idle against a NumIdle, is a comparison of samples taken one after the other, not of one state read once.

      Returns:
      the number of connections the pool holds a slot for

    • getIdle

      int getIdle()
      Returns the number of idle connections in the pool, meaning the entries that sit in the idle queue - among which there can be a wake-up placeholder with no session behind it. Like the other counts of this interface this is one sample of live state, so getSize() and getActive() are read separately and need not add up to it.
      Returns:
      idle connection count

    • getActive

      int getActive()
      Returns the number of active (in-use) connections: the entries of the pool's busy set, which is what the pool counts as checked out rather than idle. Like the other counts of this interface this is one sample of live state, so it need not add up against getSize() and getIdle(), which are read separately.
      Returns:
      active connection count

    • getNumIdle

      int getNumIdle()
      Returns the number of idle connections in the pool. This is another name for getIdle() - the commons-dbcp naming - and reads the same count.
      Returns:
      idle connection count

    • getNumActive

      int getNumActive()
      Returns the number of active (in-use) connections. This is another name for getActive() - the commons-dbcp naming - and reads the same count.
      Returns:
      active connection count

    • getWaitCount

      int getWaitCount()
      Returns the number of threads waiting for a connection. This is the count of borrowers parked in the wait loop of the synchronous getConnection: a caller of getConnectionAsync is counted only while that call is still running, and once it has been handed a future and waits on the queue behind it, that caller is no longer counted here - the pool's own wake-up logic has to ask the queue about those waiters separately, because this counter does not see them.
      Returns:
      wait count

    • getBorrowedCount

      long getBorrowedCount()
      Returns the total number of connections borrowed since the pool was created or since the last call to resetStats(), whichever is more recent.
      Returns:
      borrowed count

    • getReturnedCount

      long getReturnedCount()
      Returns the total number of connections returned since the pool was created or since the last call to resetStats(), whichever is more recent.
      Returns:
      returned count

    • getCreatedCount

      long getCreatedCount()
      Returns the total number of connections created since the pool was created or since the last call to resetStats(), whichever is more recent. This counts pooled objects the pool took into service, not sessions that came up: an attempt to establish a connection that the database refused is counted here, and its teardown is counted by getReleasedCount().
      Returns:
      created count

    • getReleasedCount

      long getReleasedCount()
      Returns the total number of connections released since the pool was created or since the last call to resetStats(), whichever is more recent. This is the counterpart of getCreatedCount(): it counts each pooled object once as it goes out of service, whether or not it ever established a session.
      Returns:
      released count

    • getReconnectedCount

      long getReconnectedCount()
      Returns the total number of reconnections since the pool was created or since the last call to resetStats(), whichever is more recent. A reconnection is one session the pool replaced under a pooled object it already had: the borrower came with different credentials, the session had passed its maxAge, or it could not be handed out as it stood.
      Returns:
      reconnected count

    • getRemoveAbandonedCount

      long getRemoveAbandonedCount()
      Returns the total number of connections removed due to abandonment since the pool was created or since the last call to resetStats(), whichever is more recent. Only the connections the pool actually took away are counted here; a connection that was merely marked as suspect is not counted.
      Returns:
      abandoned count

    • getReleasedIdleCount

      long getReleasedIdleCount()
      Returns the total number of idle connections released since the pool was created or since the last call to resetStats(), whichever is more recent. Any pass that takes an idle connection out of the pool counts here - evicting one the configuration had kept idle too long, taking back one a purge had made stale, or dropping one that did not survive the idle validation or reconnection - and that pass may be the pool cleaner working on its own timer or an explicit checkIdle(), testIdle() or purge() call.
      Returns:
      released idle count

    • checkIdle

      void checkIdle()
      Runs the idle-eviction pass over the connections that are currently idle. An idle connection the configuration says should be evicted - one that has been idle past minEvictableIdleTimeMillis, or one a purgeOnReturn() or purge() call made stale - is released, and the pass normally stops at the minIdle floor. A connection a purge made stale is released regardless of that floor, so an explicit call after a purge can take the pool below it. An idle connection a borrower claims while this runs is left to that borrower. This is the pass the pool cleaner runs on its own timer, run on demand, and what it releases is counted by getReleasedIdleCount().

    • checkAbandoned

      void checkAbandoned()
      Looks through the connections that are currently checked out for ones that have been held too long. A connection past the remove-abandoned timeout is taken from its borrower and removed only while removeAbandoned is enabled and abandonWhenPercentageFull lets the pool's occupancy allow an abandon; each such removal is counted by getRemoveAbandonedCount() and reported through NOTIFY_ABANDON. A checked-out connection that is not removed - because removal is not allowed, or because it has not passed that timeout - keeps its borrower: one held longer than suspectTimeout is only marked as suspect and reported through SUSPECT_ABANDONED_NOTIFICATION. With suspectTimeout unset and removal off, this operation reports nothing at all.

    • testIdle

      void testIdle()
      Runs the pass over the idle connections that validates them and takes out of the pool the ones that do not survive it. The validation only runs when testWhileIdle is set; with that flag unset nothing is put to the database. Whatever the flag, a connection whose maxAge has expired is reconnected first, and a connection is released when that reconnection fails, when the validation runs and fails it, or when it reaches the validation with no session behind it at all. Those releases are counted by getReleasedIdleCount(), and an idle connection a borrower claims while this runs is left to that borrower.

    • 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()
      Resets the statistics of this pool: the seven counters of this interface - getBorrowedCount(), getReturnedCount(), getCreatedCount(), getReleasedCount(), getReconnectedCount(), getRemoveAbandonedCount() and getReleasedIdleCount() - are brought back to zero. Everything else about the pool - its connections, its configuration, its notifications - is left as it is.