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

    • DEFAULT_MAX_POOL_SIZE_VALUE

      static final int DEFAULT_MAX_POOL_SIZE_VALUE
      See Also:

    • DEFAULT_MIN_POOL_SIZE_VALUE

      static final int DEFAULT_MIN_POOL_SIZE_VALUE
      See Also:

    • DEFAULT_IDLE_TIMEOUT_MS

      static final int DEFAULT_IDLE_TIMEOUT_MS
      See Also:

    • DEFAULT_CHECK_OUT_TIMEOUT_MS

      static final int DEFAULT_CHECK_OUT_TIMEOUT_MS
      See Also:

    • DEFAULT_MAXIMUM_POOL_SIZE

      static final PropertyValue<Integer> DEFAULT_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.defaultMaximumPoolSize
      • Valid range: 1-1000 (typically 5-50 for most applications)

    • DEFAULT_MINIMUM_POOL_SIZE

      static final PropertyValue<Integer> DEFAULT_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.defaultMinimumPoolSize
      • Valid range: 0 to maximum pool size (typically 2-10 for most applications)

    • DEFAULT_IDLE_TIMEOUT

      static final PropertyValue<Integer> DEFAULT_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: 60.000 (1 minute)
      • Property name: codion.db.pool.defaultIdleTimeout
      • Valid range: 1000-3600000 (1 second to 1 hour, typically 30-300 seconds)

    • DEFAULT_CHECK_OUT_TIMEOUT

      static final PropertyValue<Integer> DEFAULT_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: 30.000 (30 seconds)
      • Property name: codion.db.pool.defaultCheckOutTimeout
      • Valid range: 1000-300000 (1 second to 5 minutes, typically 10-60 seconds)

    • VALIDATE_CONNECTIONS_ON_CHECKOUT

      static final PropertyValue<Boolean> VALIDATE_CONNECTIONS_ON_CHECKOUT
      Specifies whether connections should be validated when checked out from the pool. Enables additional safety by checking connection validity before use, at the cost of performance. Recommended for production environments with unreliable network connections.
      • Value type: Boolean
      • Default value: false (disabled for performance)
      • Property name: codion.db.pool.validateConnectionsOnCheckout
      • Performance impact: Small overhead per connection checkout (~1-5ms)

  • Method Details

    • connection

      Connection connection(User user)
      Fetches a connection from the pool. Close the connection to return it to the pool.
      Parameters:
      user - the user credentials
      Returns:
      a database connection retrieved from the pool
      Throws:
      DatabaseException - in case of an exception while fetching the connection
      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 since time since.
      Parameters:
      since - the time from which statistics should be retrieved
      Returns:
      connection pool usage statistics

    • resetStatistics

      void resetStatistics()
      Resets the collected usage statistics

    • isCollectSnapshotStatistics

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

    • setCollectSnapshotStatistics

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

    • isCollectCheckOutTimes

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

    • setCollectCheckOutTimes

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

    • getCleanupInterval

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

    • setCleanupInterval

      void setCleanupInterval(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

    • getIdleTimeout

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

    • setIdleTimeout

      void setIdleTimeout(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

    • getMinimumPoolSize

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

    • setMinimumPoolSize

      void setMinimumPoolSize(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

    • getMaximumPoolSize

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

    • setMaximumPoolSize

      void setMaximumPoolSize(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

    • getMaximumCheckOutTime

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

    • setMaximumCheckOutTime

      void setMaximumCheckOutTime(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. Note that this also modifies the new connection threshold, keeping its value to 1/4 of this one.
      Parameters:
      maximumCheckOutTime - the maximum number of milliseconds to retry connection checkout (typically 10000-60000)
      Throws:
      IllegalArgumentException - if the value is less than 0