Connection Pool Management

/**
 * The HikariCP pooled DataSource providing high-performance connection pooling
 */
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
    /**
     * Default constructor with lazy initialization. Setters must be used to configure the pool.
     * Using this constructor results in slightly lower getConnection() performance due to lazy checks.
     */
    public HikariDataSource();
    
    /**
     * Construct a HikariDataSource with the specified configuration.
     * @param configuration a HikariConfig instance with validated settings
     */
    public HikariDataSource(HikariConfig configuration);
}

// Lazy initialization (slightly lower performance)
HikariDataSource dataSource = new HikariDataSource();
dataSource.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
dataSource.setUsername("user");
dataSource.setPassword("password");

// Eager initialization (recommended for production)
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
config.setUsername("user");
config.setPassword("password");
config.setMaximumPoolSize(20);
HikariDataSource dataSource = new HikariDataSource(config);

/**
 * Obtain a connection from the pool. If the pool is closed, throws SQLException.
 * Blocks for up to connectionTimeout milliseconds if no connections are available.
 * @return a Connection from the pool
 * @throws SQLException if the DataSource is closed or connection timeout is reached
 */
public Connection getConnection() throws SQLException;

/**
 * This method is not supported and throws SQLFeatureNotSupportedException
 * @param username not used
 * @param password not used
 * @throws SQLFeatureNotSupportedException always thrown
 */
public Connection getConnection(String username, String password) throws SQLException;

// Basic connection usage
try (Connection conn = dataSource.getConnection()) {
    PreparedStatement stmt = conn.prepareStatement("SELECT * FROM users WHERE id = ?");
    stmt.setInt(1, userId);
    ResultSet rs = stmt.executeQuery();
    // Process results
} // Connection automatically returned to pool

// Connection with timeout handling
try {
    Connection conn = dataSource.getConnection();
    // Use connection
    conn.close(); // Return to pool
} catch (SQLException e) {
    if (e.getMessage().contains("timeout")) {
        // Handle connection timeout
    }
}

/**
 * Shutdown the DataSource and its associated pool. This method is idempotent.
 * All connections will be closed and the pool will be shut down gracefully.
 */
public void close();

/**
 * Determine whether the HikariDataSource has been closed.
 * @return true if the HikariDataSource has been closed, false otherwise
 */
public boolean isClosed();

/**
 * @deprecated This method has been deprecated, please use close() instead
 */
@Deprecated
public void shutdown();

// Graceful shutdown
if (!dataSource.isClosed()) {
    dataSource.close();
}

// Application shutdown hook
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    if (!dataSource.isClosed()) {
        dataSource.close();
    }
}));

/**
 * Evict a connection from the pool. If the connection has already been closed (returned to the pool)
 * this may result in a "soft" eviction; the connection will be evicted sometime in the future if it is
 * currently in use. If the connection has not been closed, the eviction is immediate.
 * @param connection the connection to evict from the pool
 */
public void evictConnection(Connection connection);

/**
 * @deprecated Call the HikariPoolMXBean.suspendPool() method on the HikariPoolMXBean
 *             obtained by getHikariPoolMXBean() or JMX lookup.
 */
@Deprecated
public void suspendPool();

/**
 * @deprecated Call the HikariPoolMXBean.resumePool() method on the HikariPoolMXBean
 *             obtained by getHikariPoolMXBean() or JMX lookup.
 */
@Deprecated
public void resumePool();

// Evict a problematic connection
Connection conn = dataSource.getConnection();
try {
    // If connection test fails, evict it
    if (!conn.isValid(1)) {
        dataSource.evictConnection(conn);
    }
} finally {
    conn.close();
}

// Pool suspension (use JMX methods instead)
HikariPoolMXBean poolBean = dataSource.getHikariPoolMXBean();
poolBean.suspendPool();
// Perform maintenance
poolBean.resumePool();

/**
 * Get the HikariPoolMXBean for this HikariDataSource instance. If this method is called on
 * a HikariDataSource that has been constructed without a HikariConfig instance,
 * and before an initial call to getConnection(), the return value will be null.
 * @return the HikariPoolMXBean instance, or null
 */
public HikariPoolMXBean getHikariPoolMXBean();

/**
 * Get the HikariConfigMXBean for this HikariDataSource instance.
 * @return the HikariConfigMXBean instance
 */
public HikariConfigMXBean getHikariConfigMXBean();

// Monitor pool statistics
HikariPoolMXBean poolBean = dataSource.getHikariPoolMXBean();
if (poolBean != null) {
    System.out.println("Active connections: " + poolBean.getActiveConnections());
    System.out.println("Idle connections: " + poolBean.getIdleConnections());
    System.out.println("Total connections: " + poolBean.getTotalConnections());
    System.out.println("Threads awaiting: " + poolBean.getThreadsAwaitingConnection());
}

// Runtime configuration changes
HikariConfigMXBean configBean = dataSource.getHikariConfigMXBean();
configBean.setMaximumPoolSize(30); // Increase pool size at runtime

/**
 * Return an object that implements the given interface to allow access to non-standard methods,
 * or standard methods not exposed by the proxy.
 * @param iface the interface that the result will implement
 * @return an object that implements the interface
 * @throws SQLException if no object found that implements the interface
 */
public <T> T unwrap(Class<T> iface) throws SQLException;

/**
 * Returns true if this either implements the interface argument or is directly or indirectly
 * a wrapper for an object that does.
 * @param iface the interface to check
 * @return true if this implements the interface or wraps an object that does
 * @throws SQLException if an error occurs while determining whether this is a wrapper
 */
public boolean isWrapperFor(Class<?> iface) throws SQLException;

/**
 * Gets the log writer for this DataSource object.
 * @return the log writer for this data source or null if logging is disabled
 * @throws SQLException if a database access error occurs
 */
public PrintWriter getLogWriter() throws SQLException;

/**
 * Sets the log writer for this DataSource object.
 * @param out the new log writer; to disable logging, set to null
 * @throws SQLException if a database access error occurs
 */
public void setLogWriter(PrintWriter out) throws SQLException;

/**
 * Sets the maximum time in seconds that this data source will wait while attempting to connect.
 * @param seconds the data source login time limit in seconds; zero means there is no limit
 * @throws SQLException if a database access error occurs
 */
public void setLoginTimeout(int seconds) throws SQLException;

/**
 * Gets the maximum time in seconds that this data source can wait while attempting to connect.
 * @return the data source login time limit in seconds, or zero if there is no limit
 * @throws SQLException if a database access error occurs
 */
public int getLoginTimeout() throws SQLException;

/**
 * Return the parent Logger of all the Loggers used by this data source.
 * @return the parent Logger for this data source
 * @throws SQLFeatureNotSupportedException always thrown as this feature is not supported
 */
public java.util.logging.Logger getParentLogger() throws SQLFeatureNotSupportedException;