Document connection pooling recommendations (#19)

Add comprehensive documentation for connection management and pooling best practices.

Changes:
- DatabaseClassSource: Add connection pooling documentation
  - Recommend using pooled DataSource (HikariCP, Apache DBCP)
  - Document performance impact (200 connections vs 10 pooled)
  - Provide HikariCP configuration example
  - Explain connection overhead for production use

- SftpClassSource: Document connection reuse and concurrency
  - Explain single connection reuse across loads
  - Document synchronized bottleneck for concurrent access
  - Provide lifecycle examples with try-with-resources
  - Note limitation for high-concurrency scenarios

This addresses #19 by guiding users to proper connection management
without adding complex pooling dependencies.

Fixes #19

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Flossy

src/main/java/org/flossware/jclassloader/DatabaseClassSource.java

@@ -11,6 +11,41 @@
 /**
  * ClassSource implementation for loading classes from a JDBC database.
  * Class bytecode is stored in a table with columns for class name and class bytes.
+ *
+ * <h2>Performance: Connection Pooling</h2>
+ * <p><b>IMPORTANT:</b> This class creates a new database connection for every class load operation.
+ * For production use, always provide a pooled DataSource (HikariCP, Apache DBCP, etc.) to avoid
+ * connection overhead and resource exhaustion.</p>
+ *
+ * <h3>Recommended Setup (HikariCP)</h3>
+ * <pre>{@code
+ * // Create a connection pool
+ * HikariConfig config = new HikariConfig();
+ * config.setJdbcUrl("jdbc:postgresql://localhost/classes");
+ * config.setUsername("user");
+ * config.setPassword("password");
+ * config.setMaximumPoolSize(10);
+ * config.setMinimumIdle(2);
+ * config.setConnectionTimeout(30000);
+ *
+ * DataSource pooledDataSource = new HikariDataSource(config);
+ *
+ * // Pass the pooled DataSource to DatabaseClassSource
+ * DatabaseClassSource source = new DatabaseClassSource(
+ *     pooledDataSource,  // Reuses connections from pool
+ *     "class_table",
+ *     "class_name",
+ *     "class_bytes"
+ * );
+ * }</pre>
+ *
+ * <h3>Performance Impact</h3>
+ * <ul>
+ *   <li><b>Without pooling:</b> Loading 100 classes = ~200 new connections (slow)</li>
+ *   <li><b>With pooling:</b> Loading 100 classes = reuses 10 pooled connections (fast)</li>
+ * </ul>
+ *
+ * @see javax.sql.DataSource
  */
 public class DatabaseClassSource implements ClassSource {
     private final DataSource dataSource;

src/main/java/org/flossware/jclassloader/SftpClassSource.java

@@ -19,6 +19,35 @@
  * Supports both password and private key authentication with retry logic.
  * Requires the JSch library dependency.
  * Implements AutoCloseable for proper resource management - call close() when done.
+ *
+ * <h2>Connection Management</h2>
+ * <p>This class reuses a single SFTP connection across multiple class loads for efficiency.
+ * The connection is established on first use and maintained until close() is called.</p>
+ *
+ * <h3>Concurrency Limitation</h3>
+ * <p><b>NOTE:</b> Connection establishment is synchronized, which creates a bottleneck for
+ * concurrent access. All threads share the same SFTP channel. For high-concurrency scenarios,
+ * consider creating multiple SftpClassSource instances or using a different protocol.</p>
+ *
+ * <h3>Connection Lifecycle</h3>
+ * <pre>{@code
+ * try (SftpClassSource source = SftpClassSource.builder()
+ *         .host("sftp.example.com")
+ *         .username("deploy")
+ *         .password("secret")
+ *         .build()) {
+ *
+ *     // Connection established on first load
+ *     byte[] class1 = source.loadClassData("com.example.Class1");
+ *
+ *     // Reuses existing connection (fast)
+ *     byte[] class2 = source.loadClassData("com.example.Class2");
+ *
+ * }  // Connection closed automatically
+ * }</pre>
+ *
+ * @see #close()
+ * @see #disconnect()
  */
 public class SftpClassSource implements ClassSource, AutoCloseable {
     private static final int DEFAULT_SESSION_TIMEOUT_MS = 30000;