* ObjectPool は一般的でシンプルなプーリングインターフェイスを定義します。
* 必須となるメソッドは {@link #borrowObject borrowObject} と {@link #returnObject returnObject} だけです。
* {@primary ObjectPool defines a trivially simple pooling interface. The only
* required methods are {@link #borrowObject borrowObject} and {@link #returnObject returnObject}.}
*
* 以下に使用方法を示します: * {@primary Example of use:} *
|
* Object obj = null; * * try { * obj = pool.borrowObject(); * //...オブジェクトを使用...{@primary * //...use the object...} * } catch(Exception e) { * //...例外をハンドル...{@primary * //...handle any exceptions...} * } finally { * // 確実にオブジェクトをプールに返す {@primary * // make sure the object is returned to the pool } * if(null != obj) { * pool.returnObject(obj); * } * } |
* プール内のインスタンスが空の場合のこのメソッドの振る舞いは明示されません * (各実装クラスで明示されるでしょう)。 * {@primary The behaviour of this method when the pool has been exhausted * is not specified (although it may be specified by implementations).} * * @return プールから取り出されたインスタンス * {@primary an instance from my pool.} */ Object borrowObject() throws Exception; /** * プールにインスタンスを返します。 * プールに返される obj は必ず * {@link #borrowObject() borrowObject} * または実装クラスやサブインターフェイスのそれと関連するメソッドを使用して * 取得されたインスタンスでなくてはなりません。 * {@primary Return an instance to my pool. * By contract, obj MUST have been obtained * using {@link #borrowObject() borrowObject} * or a related method as defined in an implementation * or sub-interface.} * * @param obj プールに返す {@link #borrowObject borrowed} にて取得されたインスタンス * {@primary a {@link #borrowObject borrowed} instance to be returned.} */ void returnObject(Object obj) throws Exception; /** * プール内で管理されるオブジェクトを無効にします。 * 対象となる obj は {@link #borrowObject borrowObject} * か、実装クラスに定義された関連するメソッドか、 key * を用いたサブインターフェイスの同等の機能を持つメソッドによって取得されたものでなくてはなりません。 * {@primary Invalidates an object from the pool * By contract, obj MUST have been obtained * using {@link #borrowObject() borrowObject} * or a related method as defined in an implementation * or sub-interface.} *
* このメソッドはプールから取得されたオブジェクトが(例外等で)無効であるとみなされた場合に使用するべきです。 * オブジェクト取得の前、もしくは戻された後にオブジェクトの評価を行う場合には * {@link PoolableObjectFactory#validateObject} を使用して下さい。 * {@primary This method should be used when an object that has been borrowed * is determined (due to an exception or other problem) to be invalid. * If the connection should be validated before or after borrowing, * then the {@link PoolableObjectFactory#validateObject} method should be * used instead.} * * @param obj プールから{@link #borrowObject 取得} されたインスタンス * {@primary a {@link #borrowObject borrowed} instance to be returned.} */ void invalidateObject(Object obj) throws Exception; /** * 自身の{@link #setFactory ファクトリ}または他の実装に依存する機能によってプール内にオブジェクトを配置します。 * addObject() は事前に準備されたオブジェクトをプール内に用意する際に有用です(オプショナルな処理)。 * {@primary Create an object using my {@link #setFactory factory} or other * implementation dependent mechanism, and place it into the pool. * addObject() is useful for "pre-loading" a pool with idle objects. * (Optional operation).} */ void addObject() throws Exception; /** * 現在プール内にある使用されていないインスタンスの数を返します(オプショナルな処理)。 * これは新たなインスタンスを生成せずに {@link #borrowObject 取得} * することのできるオブジェクトの数を対象とします。 * {@primary Return the number of instances * currently idle in my 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.} * * @return プール内にある使用されていないインスタンスの数 * {@primary the number of instances currently idle in my pool} * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合 * {@primary if this implementation does not support the operation} */ int getNumIdle() throws UnsupportedOperationException; /** * 現在プールから貸し出されているインスタンスの数を返します(オプショナルな処理)。 * {@primary Return the number of instances * currently borrowed from my pool * (optional operation).} * * @return 現在プールから貸し出されているインスタンスの数 * {@primary the number of instances currently borrowed in my pool} * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合 * {@primary if this implementation does not support the operation} */ int getNumActive() throws UnsupportedOperationException; /** * プール内にある使用されていないオブジェクトを削除し、関連するリソースを開放します(オプショナルな処理)。 * {@primary Clears any objects sitting idle in the pool, releasing any * associated resources (optional operation).} * * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合 * {@primary if this implementation does not support the operation} */ void clear() throws Exception, UnsupportedOperationException; /** * このプールを閉じ、関連する全てのリソースを開放します。 * {@primary Close this pool, and free any resources associated with it.} */ void close() throws Exception; /** * 新たなインスタンスを生成するために使用する * {@link PoolableObjectFactory factory} を設定します(オプショナルな処理)。 * {@primary Sets the {@link PoolableObjectFactory ファクトリ} I use * to create new instances (optional operation).} * * @param factory 新たなインスタンスを生成するために使用する {@link PoolableObjectFactory} * {@primary the {@link PoolableObjectFactory} I use to create new instances.} * @throws IllegalStateException ファクトリを設定できる状態でない場合 * {@primary IllegalStateException when the factory cannot be set at this time} * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合 * {@primary if this implementation does not support the operation} */ void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException; }