Interface ConnectionPool

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

ConnectionPoolImpl

public interface ConnectionPool
extends AutoCloseable

Connection pool for managing TCP connections to multiple endpoints.

This interface provides connection pooling with automatic connection reuse, health checking, and resource management. Connections are pooled per endpoint (host:port combination).

Pooling Benefits

• Reduced latency: Reuse existing connections instead of TCP handshake
• Resource efficiency: Limit connections per host to prevent exhaustion
• Health management: Automatic removal of unhealthy connections
• Thread safety: Safe for concurrent acquire/release from multiple threads

Connection Lifecycle

1. Acquire: Get a connection via acquire(SocketAddress, ConnectionHandler)
   • Returns existing idle connection if available
   • Creates new connection if under limit
   • Fails if pool exhausted
2. Use: Perform I/O operations on the connection
3. Release: Return via release(Transport)
   • Healthy connections return to idle pool
   • Unhealthy connections are closed

Usage Example

ConnectionPool pool = TransportFactory.createPool(config);

pool.acquire(new InetSocketAddress("api.example.com", 443),
    new ConnectionHandler() {
        @Override
        public void onConnectionAcquired(Transport conn, long token) {
            try {
                // Use connection...
                conn.send(request);
            } finally {
                pool.release(conn);
            }
        }

        @Override
        public void onConnectionFailed(Throwable cause, long token) {
            System.err.println("Connection failed: " + cause);
        }
    });

See Also:

• ConnectionHandler
• Transport
• TransportFactory.createPool(TransportConfig)

Method Summary

Modifier and Type	Method	Description
long	acquire(SocketAddress endpoint, ConnectionHandler handler)	Acquires a connection to the specified endpoint.
void	close()	Closes all connections and shuts down the pool.
int	getActiveConnectionCount()	Returns the total number of active (in-use) connections.
int	getIdleConnectionCount()	Returns the total number of idle (available) connections.
void	release(Transport connection)	Releases a connection back to the pool.

Method Details

acquire

long acquire(SocketAddress endpoint,
 ConnectionHandler handler)

Acquires a connection to the specified endpoint.

This method attempts to provide a connection in the following order:

1. Return an existing idle connection if one is available and healthy
2. Create a new connection if below the per-host limit
3. Fail with an error if the pool is exhausted

The result is delivered asynchronously via the handler.

Parameters:

endpoint - the remote endpoint to connect to (e.g., InetSocketAddress)

handler - the handler to notify when connection is ready or failed

Returns:

a token identifying this operation for correlation

Throws:

IllegalStateException - if the pool is closed

release

void release(Transport connection)

Releases a connection back to the pool.

The connection is evaluated and either returned to the idle pool (if healthy) or closed (if unhealthy). Released connections become available for future acquire(SocketAddress, ConnectionHandler) calls.

This method is idempotent; releasing an already-released connection has no effect.

Parameters:

connection - the connection to release (may be null, which is ignored)

getActiveConnectionCount

int getActiveConnectionCount()

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

Active connections are those acquired but not yet released.

Returns:

the active connection count across all endpoints

getIdleConnectionCount

int getIdleConnectionCount()

Returns the total number of idle (available) connections.

Idle connections are ready for immediate reuse.

Returns:

the idle connection count across all endpoints

close

void close()

Closes all connections and shuts down the pool.

After closing:

• All active and idle connections are closed
• acquire(SocketAddress, ConnectionHandler) will fail immediately
• The pool cannot be restarted

Specified by:

close in interface AutoCloseable