Java 池技術 － commons－pool

public interface ObjectPool<T> {
    /**
     * 從對象池中獲取到一個對象。
     *
     * 該對象能夠是經過 PoolableObjectFactory 的 makeObject方法 建立，
     * 也能夠是以前建立的，如今處於閒置狀態的對象。並且該對象還經過了 PoolableObjectFactory
     * 的activateObject激活和validateObject方法的校驗
     *
     * 這裏約定，客戶端歸還借的對象必須使用 returnObject invalidateObject，或者是子類中
     * 定義的一個相關的方法
     *
     * 當對象池的資源耗盡的時候（對象借光啦），這個方法並無嚴格的規定其行爲。老的版本中會返回null
       新的版本中鼓勵拋出NoSuchElementException異常
     */
    T borrowObject() throws Exception, NoSuchElementException, IllegalStateException;

    /**
     * Return an instance to the pool.
     * By contract, <code>obj</code> <strong>must</strong> have been obtained
     * using {@link #borrowObject() borrowObject}
     * or a related method as defined in an implementation
     * or sub-interface.
     *
     * @param obj a {@link #borrowObject borrowed} instance to be returned.
     * @throws Exception 
     */
    void returnObject(T obj) throws Exception;

    /**
     * <p>Invalidates an object from the pool.</p>
     * 
     * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
     * using {@link #borrowObject borrowObject} or a related method as defined in
     * an implementation or sub-interface.</p>
     *
     * <p>This method should be used when an object that has been borrowed
     * is determined (due to an exception or other problem) to be invalid.</p>
     *
     * @param obj a {@link #borrowObject borrowed} instance to be disposed.
     * @throws Exception
     */
    void invalidateObject(T obj) throws Exception;

    /**
     * Create an object using the {@link PoolableObjectFactory factory} or other
     * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
     * <code>addObject</code> is useful for "pre-loading" a pool with idle objects.
     * (Optional operation).
     *
     * @throws Exception when {@link PoolableObjectFactory#makeObject} fails.
     * @throws IllegalStateException after {@link #close} has been called on this pool.
     * @throws UnsupportedOperationException when this pool cannot add new idle objects.
     */
    void addObject() throws Exception, IllegalStateException, UnsupportedOperationException;

    /**
     * Return the number of instances
     * currently idle in this pool (optional operation).
     * This may be considered an approximation of the number
     * of objects that can be {@link #borrowObject borrowed}
     * without creating any new instances.
     * Returns a negative value if this information is not available.
     *
     * @return the number of instances currently idle in this pool or a negative value if unsupported
     * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
     */
    int getNumIdle() throws UnsupportedOperationException;

    /**
     * Return the number of instances
     * currently borrowed from this pool
     * (optional operation).
     * Returns a negative value if this information is not available.
     *
     * @return the number of instances currently borrowed from this pool or a negative value if unsupported
     * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
     */
    int getNumActive() throws UnsupportedOperationException;

    /**
     * Clears any objects sitting idle in the pool, releasing any
     * associated resources (optional operation).
     * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
     *
     * @throws UnsupportedOperationException if this implementation does not support the operation
     */
    void clear() throws Exception, UnsupportedOperationException;

    /**
     * Close this pool, and free any resources associated with it.
     * <p>
     * Calling {@link #addObject} or {@link #borrowObject} after invoking
     * this method on a pool will cause them to throw an
     * {@link IllegalStateException}.
     * </p>
     *
     * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed.
     */
    void close() throws Exception;

    /**
     * Sets the {@link PoolableObjectFactory factory} this pool uses
     * to create new instances (optional operation). Trying to change
     * the <code>factory</code> after a pool has been used will frequently
     * throw an {@link UnsupportedOperationException}. It is up to the pool
     * implementation to determine when it is acceptable to call this method.
     *
     * @param factory the {@link PoolableObjectFactory} used to create new instances.
     * @throws IllegalStateException when the factory cannot be set at this time
     * @throws UnsupportedOperationException if this implementation does not support the operation
     * @deprecated to be removed in pool 2.0
     */
    @Deprecated
    void setFactory(PoolableObjectFactory<T> factory) throws IllegalStateException, UnsupportedOperationException;
}