Module is.codion.common.db
Package is.codion.common.db.pool

Interface ConnectionPoolWrapper

All Known Implementing Classes:
AbstractConnectionPoolWrapper
public interface ConnectionPoolWrapper
A connection pool wrapper, providing statistics from the underlying pool and allowing some configuration.

  • Field Details

    • MAXIMUM_POOL_SIZE

      static final PropertyValue<Integer> MAXIMUM_POOL_SIZE
      Specifies the default maximum connection pool size. This determines the maximum number of concurrent database connections that can be created. Higher values allow more concurrent operations but consume more database resources.
      • Value type: Integer
      • Default value: 8
      • Property name: codion.db.pool.maximumPoolSize

    • MINIMUM_POOL_SIZE

      static final PropertyValue<Integer> MINIMUM_POOL_SIZE
      Specifies the default minimum connection pool size. This determines the number of connections that remain open even when idle. Higher values reduce connection creation overhead but consume more database resources.
      • Value type: Integer
      • Default value: 4
      • Property name: codion.db.pool.minimumPoolSize

    • IDLE_TIMEOUT

      static final PropertyValue<Integer> IDLE_TIMEOUT
      Specifies the default idle timeout in milliseconds. This determines how long a connection can remain idle before being eligible for eviction. Lower values free up database resources faster but may cause more connection churn.
      • Value type: Integer
      • Default value: 60000 (1 minute)
      • Property name: codion.db.pool.idleTimeout

    • CHECK_OUT_TIMEOUT

      static final PropertyValue<Integer> CHECK_OUT_TIMEOUT
      Specifies the default maximum connection check out timeout in milliseconds. This determines how long to wait for an available connection before throwing an exception. Lower values fail faster but may cause premature timeouts under load.
      • Value type: Integer
      • Default value: 30000 (30 seconds)
      • Property name: codion.db.pool.checkOutTimeout

  • Method Details

    • connection

      Connection connection(User user)
      Fetches a connection from the pool. Close the connection to return it to the pool.

      Note that user is a credentials check, not a selector: the pool serves a single user(), and the given credentials are verified against it (username case-insensitively, password exactly) before a connection is handed out.

      Parameters:
      user - the credentials to verify against the pool user
      Returns:
      a database connection retrieved from the pool
      Throws:
      DatabaseException - in case of an exception while fetching the connection
      AuthenticationException - in case the given credentials do not match the pool user
      IllegalStateException - if the pool is closed
      See Also:

    • user

      User user()
      Returns:
      the user this connection pool is based on.

    • close

      void close()
      Closes this connection pool, connections subsequently checked in are disconnected

    • statistics

      ConnectionPoolStatistics statistics(long since)
      Retrieves usage statistics for the connection pool.

      Note that this is a destructive read: it resets the per-second counters and consumes the collected check-out times. The since parameter only filters the snapshot statistics list; the counters ignore it. Concurrent monitoring clients polling the same pool will steal each other's data.

      Parameters:
      since - the time from which the snapshot statistics should be retrieved
      Returns:
      connection pool usage statistics

    • resetStatistics

      void resetStatistics()
      Resets the collected usage statistics

    • collectSnapshotStatistics

      boolean collectSnapshotStatistics()
      Returns true if snapshot statistics are being collected.
      Returns:
      true if pool usage statistics for a snapshot should be collected
      See Also:

    • collectSnapshotStatistics

      void collectSnapshotStatistics(boolean collectSnapshotStatistics)
      Specifies whether to collect usage statistics for a snapshot.
      Parameters:
      collectSnapshotStatistics - the value
      See Also:

    • collectCheckOutTimes

      boolean collectCheckOutTimes()
      Returns true if connection check out times are being collected.
      Returns:
      true if connection check out times should be collected
      See Also:

    • collectCheckOutTimes

      void collectCheckOutTimes(boolean collectCheckOutTimes)
      Specifies whether to collect connection check out times.
      Parameters:
      collectCheckOutTimes - the value
      See Also:

    • cleanupInterval

      int cleanupInterval()
      Returns the pool cleanup interval in milliseconds. This determines how often the pool checks for and removes idle/expired connections.
      Returns:
      the pool cleanup interval in milliseconds

    • cleanupInterval

      void cleanupInterval(int poolCleanupInterval)
      Sets the pool cleanup interval in milliseconds. Controls how frequently the pool performs maintenance operations like removing expired connections.
      Parameters:
      poolCleanupInterval - the pool cleanup interval in milliseconds (typically 30000-300000)
      Throws:
      IllegalArgumentException - if the value is less than 1000

    • idleTimeout

      int idleTimeout()
      Returns the connection idle timeout in milliseconds. This is the time a connection can remain idle before being eligible for eviction.
      Returns:
      the pooled connection timeout in milliseconds

    • idleTimeout

      void idleTimeout(int idleTimeout)
      Sets the connection idle timeout in milliseconds. Connections idle longer than this timeout may be closed to free up database resources.
      Parameters:
      idleTimeout - the pooled connection timeout in milliseconds (typically 30000-300000)
      Throws:
      IllegalArgumentException - if the value is less than 1000

    • minimumPoolSize

      int minimumPoolSize()
      Returns the minimum number of connections to keep in the pool. These connections remain open even when idle to reduce connection creation overhead.
      Returns:
      the minimum number of connections to keep in the pool

    • minimumPoolSize

      void minimumPoolSize(int minimumPoolSize)
      Sets the minimum number of connections to keep in the pool. Higher values reduce latency but consume more database resources.
      Parameters:
      minimumPoolSize - the minimum number of connections to keep in the pool (typically 1-10)
      Throws:
      IllegalArgumentException - if the value is less than 0 or larger than maximum pool size

    • maximumPoolSize

      int maximumPoolSize()
      Returns the maximum number of connections this pool can create. This limits the total number of concurrent database connections to prevent resource exhaustion.
      Returns:
      the maximum number of connections this pool can create

    • maximumPoolSize

      void maximumPoolSize(int maximumPoolSize)
      Sets the maximum number of connections to keep in this pool. Higher values support more concurrent operations but consume more database resources. Note that if the current number of connections exceeds this value when set, excess connections are not actively discarded.
      Parameters:
      maximumPoolSize - the maximum number of connections this pool can create (typically 5-50)
      Throws:
      IllegalArgumentException - if the value is less than 1 or less than minimum pool size

    • maximumCheckOutTime

      int maximumCheckOutTime()
      Returns the maximum time to wait for a connection checkout in milliseconds. This prevents threads from waiting indefinitely when the pool is exhausted.
      Returns:
      the maximum number of milliseconds to retry connection checkout before throwing an exception

    • maximumCheckOutTime

      void maximumCheckOutTime(int maximumCheckOutTime)
      Sets the maximum time to wait for a connection checkout in milliseconds. Lower values fail faster under load, higher values may cause application timeouts.
      Parameters:
      maximumCheckOutTime - the maximum number of milliseconds to retry connection checkout (typically 10000-60000)
      Throws:
      IllegalArgumentException - if the value is less than 0