Module com.darkcollective.relix.connectors.std
Package com.darkcollective.relix.connectors.std.internal

Class ConnectionPool

java.lang.Object
com.darkcollective.relix.connectors.std.internal.ConnectionPool
All Implemented Interfaces:
AutoCloseable
public final class ConnectionPool extends Object implements AutoCloseable
A small pool of reusable JDBC Connections, keyed by DatabaseConnectionConfig, so repeated scans and queries against the same connection avoid the cost of opening a fresh physical connection each time.

Usage is borrow/release: borrow(com.darkcollective.relix.lang.ast.ConnectionDeclaration) hands out a validated idle connection (or opens a new one), and release(com.darkcollective.relix.lang.ast.ConnectionDeclaration, java.sql.Connection) returns it for reuse. A released connection that is broken — or that would exceed the per-config idle bound — is closed rather than pooled. close() closes every idle connection; it should be called once the owning connector is done.

The pool itself never closes a borrowed connection: the caller decides via release(com.darkcollective.relix.lang.ast.ConnectionDeclaration, java.sql.Connection) (reuse) versus closing it directly (e.g. after a setup failure, where the connection may be in an unknown state).

Fresh connections come from a ConnectionProvider, so what a connection is stays out of the pool. A provider that manages its own pooling is not pooled again on top: those connections are opened on demand and closed on release, which is what returns them to the pool that actually owns them. The idle map is keyed by the JDBC coordinates rather than by the declaration, so two declarations naming the same database still share, exactly as before — and a provider-pooled connection needs no key at all, since nothing is retained.

Thread safety

Backed by concurrent collections and safe for concurrent borrow/release. The per-config idle bound is a soft limit (a brief concurrent overshoot is harmless). close() is intended to run once, after execution has finished using the pool.

  • Constructor Details

    • ConnectionPool

      public ConnectionPool()
      Creates a pool with the default per-config idle bound (8), opening fresh connections from ConnectionProvider.FROM_URL.

    • ConnectionPool

      public ConnectionPool(ConnectionProvider provider)
      Creates a pool with the default idle bound, opening fresh connections from provider.
      Parameters:
      provider - the source of new connections; must not be null

    • ConnectionPool

      public ConnectionPool(int maxIdlePerConfig)
      Creates a pool keeping at most maxIdlePerConfig idle connections per distinct connection config.
      Parameters:
      maxIdlePerConfig - the per-config idle bound; must be positive

    • ConnectionPool

      public ConnectionPool(int maxIdlePerConfig, ConnectionProvider provider)
      Creates a pool keeping at most maxIdlePerConfig idle connections per distinct connection config, opening fresh ones from provider.
      Parameters:
      maxIdlePerConfig - the per-config idle bound; must be positive
      provider - the source of new connections; must not be null

  • Method Details

    • borrow

      public Connection borrow(ConnectionDeclaration connection) throws SQLException
      Borrows a usable connection for connection: a validated idle one if available, otherwise a freshly opened one from the provider.

      When the provider manages its own pooling for this declaration, nothing idle is consulted and a connection is opened on demand.

      Parameters:
      connection - the declared connection; must not be null
      Returns:
      an open connection the caller must release(com.darkcollective.relix.lang.ast.ConnectionDeclaration, java.sql.Connection) or close
      Throws:
      SQLException - if the pool is closed or a new connection cannot be opened

    • release

      public void release(ConnectionDeclaration connection, Connection conn)
      Returns a connection for reuse. A broken connection, or one beyond the idle bound, is closed instead of pooled. Passing null is a no-op.

      When the provider manages its own pooling for this declaration the connection is closed rather than retained — that is what returns it to the pool that owns it.

      Parameters:
      connection - the declaration the connection belongs to
      conn - the connection to release; may be null

    • close

      public void close()
      Closes every idle connection. Borrowed connections are unaffected.
      Specified by:
      close in interface AutoCloseable