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;
}
Java 池技术 - commons-pool
猜你喜欢
转载自my.oschina.net/u/206123/blog/1560781
今日推荐
周排行