Interface ObjectPool<T>

Type Parameters:
T - the type of object being pooled - 池化对象类型
All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
GenericObjectPool, SoftReferencePool, ThreadLocalPool, VirtualThreadPool
public interface ObjectPool<T> extends AutoCloseable
ObjectPool - Object Pool Interface ObjectPool - 对象池接口

Core interface for object pooling, providing borrow/return semantics with automatic resource management.

对象池化的核心接口，提供借用/归还语义和自动资源管理。

Features | 主要功能:

  • Object borrowing with timeout - 带超时的对象借用
  • Object returning - 对象归还
  • Object invalidation - 对象失效
  • Pool metrics access - 池指标访问
  • Execute pattern for auto-return - 自动归还的执行模式

Usage Examples | 使用示例:

// PoolLease pattern (recommended, try-with-resources)
try (PoolLease<Connection> lease = pool.borrowLease()) {
    Connection conn = lease.get();
    // use connection
} // auto-return

// Execute pattern (also recommended)
String result = pool.execute(conn -> {
    return conn.executeQuery("SELECT...");
});

// Manual borrow/return
Connection conn = pool.borrowObject();
try {
    // use connection
} finally {
    pool.returnObject(conn);
}

Security | 安全性:

  • Thread-safe: Implementation dependent - 线程安全: 取决于实现
Since:
JDK 25, opencode-base-pool V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • borrowObject

      T borrowObject() throws OpenPoolException
      Borrows an object from the pool. 从池中借用对象。

      Uses default timeout from pool configuration.

      使用池配置的默认超时。

      Returns:
      the borrowed object - 借用的对象
      Throws:
      OpenPoolException - if borrowing fails - 如果借用失败

    • borrowObject

      T borrowObject(Duration timeout) throws OpenPoolException
      Borrows an object from the pool with timeout. 带超时从池中借用对象。
      Parameters:
      timeout - the maximum wait time - 最大等待时间
      Returns:
      the borrowed object - 借用的对象
      Throws:
      OpenPoolException - if borrowing fails or times out - 如果借用失败或超时

    • returnObject

      void returnObject(T obj)
      Returns an object to the pool. 将对象归还到池中。
      Parameters:
      obj - the object to return - 要归还的对象

    • invalidateObject

      void invalidateObject(T obj)
      Invalidates an object (will not be returned to pool). 使对象失效（不会返回池中）。
      Parameters:
      obj - the object to invalidate - 要失效的对象

    • addObject

      void addObject() throws OpenPoolException
      Adds a new object to the pool. 向池中添加新对象。
      Throws:
      OpenPoolException - if adding fails - 如果添加失败

    • getNumIdle

      int getNumIdle()
      Gets the number of idle objects. 获取空闲对象数。
      Returns:
      the idle count - 空闲数

    • getNumActive

      int getNumActive()
      Gets the number of active (borrowed) objects. 获取活跃（借出）对象数。
      Returns:
      the active count - 活跃数

    • clear

      void clear()
      Clears all idle objects from the pool. 清除池中所有空闲对象。

    • getMetrics

      PoolMetrics getMetrics()
      Gets the pool metrics. 获取池指标。
      Returns:
      the metrics - 指标

    • execute

      default <R> R execute(Function<T,R> action) throws OpenPoolException
      Executes an action with a pooled object (auto-return). 使用池化对象执行操作（自动归还）。

      Example | 示例:

      String result = pool.execute(conn -> {
    return conn.executeQuery("SELECT...");
});
      Type Parameters:
      R - the result type - 结果类型
      Parameters:
      action - the action to execute - 要执行的操作
      Returns:
      the action result - 操作结果
      Throws:
      OpenPoolException - if execution fails - 如果执行失败

    • execute

      default void execute(Consumer<T> action) throws OpenPoolException
      Executes a void action with a pooled object (auto-return). 使用池化对象执行无返回值操作（自动归还）。

      Example | 示例:

      pool.execute(conn -> {
    conn.executeUpdate("UPDATE...");
});
      Parameters:
      action - the action to execute - 要执行的操作
      Throws:
      OpenPoolException - if execution fails - 如果执行失败

    • borrowLease

      default PoolLease<T> borrowLease() throws OpenPoolException
      Borrows an object wrapped in a PoolLease for try-with-resources. 借用对象并包装在 PoolLease 中，用于 try-with-resources。

      Example | 示例:

      try (PoolLease<Connection> lease = pool.borrowLease()) {
    Connection conn = lease.get();
    // use connection
} // auto-return
      Returns:
      a pool lease wrapping the borrowed object - 包装借用对象的池租约
      Throws:
      OpenPoolException - if borrowing fails - 如果借用失败

    • borrowLease

      default PoolLease<T> borrowLease(Duration timeout) throws OpenPoolException
      Borrows an object wrapped in a PoolLease with timeout for try-with-resources. 带超时借用对象并包装在 PoolLease 中，用于 try-with-resources。
      Parameters:
      timeout - the maximum wait time - 最大等待时间
      Returns:
      a pool lease wrapping the borrowed object - 包装借用对象的池租约
      Throws:
      OpenPoolException - if borrowing fails or times out - 如果借用失败或超时

    • preparePool

      default void preparePool(int count) throws OpenPoolException
      Pre-creates objects to warm up the pool. 预创建对象以预热池。

      Creates the specified number of objects and adds them to the pool. Useful for avoiding cold-start latency.

      创建指定数量的对象并添加到池中。适用于避免冷启动延迟。

      Parameters:
      count - the number of objects to pre-create - 要预创建的对象数量
      Throws:
      OpenPoolException - if object creation fails - 如果对象创建失败