org.apache.commons.pool
インタフェース KeyedObjectPool

既知の実装クラスの一覧:

BaseKeyedObjectPool, GenericKeyedObjectPool, StackKeyedObjectPool

public interface KeyedObjectPool

キーに対応するプーリングを行うためのインターフェイスです。

A "keyed" pooling interface.

KeyedObjectPool は複数の型のインスタンスをプールします。 各型のオブジェクトに任意のキーを使用してアクセスすることが可能です。

A keyed pool pools instances of multiple types. Each type may be accessed using an arbitrary key.

以下に使用方法を示します:

Example of use:

Object obj = null;
Object key = "Key";

try{
obj = pool.borrowObject(key);
//...オブジェクトを使用...

//...use the object...

} catch(Exception e) {
//...例外をハンドル...

//...handle any exceptions...

} finally {
// 確実にオブジェクトをプールに返す

// make sure the object is returned to the pool

if(null != obj) {
pool.returnObject(key,obj);
}
}

KeyedObjectPool の実装はキー毎に選択された1つのインスタンスを保持するか、 キー毎にプールするインスタンスの管理を行うことができます。 (実際には pool の Map を生成します)。

{@link KeyedObjectPool} implementations may choose to store at most one instance per key value, or may choose to maintain a pool of instances for each key (essentially creating a {@link java.util.Map Map} of {@link ObjectPool pools}).

バージョン:

$Revision: 1.1 $ $Date: 2004/02/22 11:58:26 $

作成者:

Rodney Waldhoff

関連項目:

KeyedPoolableObjectFactory, KeyedObjectPoolFactory, ObjectPool

翻訳者:

日置 聡

翻訳状況:

初稿(校正者募集中)

翻訳更新日:

2004/02/21

メソッドの概要

void	addObject(Object key) 自身のファクトリまたは他の実装に依存する機能によってプール内にオブジェクトを配置します。
Object	borrowObject(Object key) プールから指定された key に対応するインスタンスを取り出します。
void	clear() 全てのプールされたすべてのインスタンスを削除し、プールをクリアします(オプショナルな処理)。
void	clear(Object key) 全てのプールされたインスタンスを削除し、プールをクリアします(オプショナルな処理)。
void	close() このプールを閉じ、関連する全てのリソースを開放します。
int	getNumActive() このプールから取得され、まだ戻されていないインスタンスの数を返します(オプショナルな処理)。
int	getNumActive(Object key) このプールから取得され、まだ戻されていない指定された key に対応するインスタンスの数を返します(オプショナルな処理)。
int	getNumIdle() 現在プール内にある使用されていないインスタンスの数を返します(オプショナルな処理)。
int	getNumIdle(Object key) 現在プール内にある使用されていない指定された key に対応するインスタンスの数を返します(オプショナルな処理)。
void	invalidateObject(Object key, Object obj) プール内で管理されるオブジェクトを無効にします。
void	returnObject(Object key, Object obj) プールにインスタンスを返します。
void	setFactory(KeyedPoolableObjectFactory factory) 新たなインスタンスを生成するために使用する ファクトリ を設定します(オプショナルな処理)。

メソッドの詳細

addObject

public void addObject(Object key)
               throws Exception

自身のファクトリまたは他の実装に依存する機能によってプール内にオブジェクトを配置します。 addObject() は事前に準備されたオブジェクトをプール内に用意する際に有用です(オプショナルな処理)。

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).

例外:

Exception

borrowObject

public Object borrowObject(Object key)
                    throws Exception

プールから指定された key に対応するインスタンスを取り出します。 プールからインスタンスを取得したクライアントは必ず returnObject または実装クラスやサブインターフェイスのそれと関連するメソッドを使用して インスタンスをプールに返さなくてはなりません。 また、 key には返すインスタンスを取得した際と同じ値を設定しなくてはなりません。

Obtain an instance from my pool for the specified key. By contract, clients MUST return the borrowed object using {@link #returnObject(java.lang.Object,java.lang.Object) returnObject}, or a related method as defined in an implementation or sub-interface, using a key that is equivalent to the one used to borrow the instance in the first place.

パラメータ:

key - オブジェクトを取得する際に使用するキー

the key used to obtain the object

戻り値:

プールから取得したインスタンス

an instance from my pool.

例外:

Exception

clear

public void clear()
           throws Exception,
                  UnsupportedOperationException

全てのプールされたすべてのインスタンスを削除し、プールをクリアします(オプショナルな処理)。 このプールが削除の機能を持たない場合 UnsupportedOperationException が投げられます。

Clears my pool, removing all pooled instances (optional operation). Throws {@link UnsupportedOperationException} if the pool cannot be cleared.

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

Exception

clear

public void clear(Object key)
           throws Exception,
                  UnsupportedOperationException

全てのプールされたインスタンスを削除し、プールをクリアします(オプショナルな処理)。 このプールが削除の機能を持たない場合 UnsupportedOperationException が投げられます。

Clears my pool, removing all pooled instances (optional operation). Throws {@link UnsupportedOperationException} if the pool cannot be cleared.

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

Exception

close

public void close()
           throws Exception

このプールを閉じ、関連する全てのリソースを開放します。

Close this pool, and free any resources associated with it.

例外:

Exception

getNumActive

public int getNumActive()
                 throws UnsupportedOperationException

このプールから取得され、まだ戻されていないインスタンスの数を返します(オプショナルな処理)。 この情報を取得する機能を持たない場合 UnsupportedOperationException が投げられます。

Returns the total number of instances current borrowed from my pool but not yet returned (optional operation). Throws {@link UnsupportedOperationException} if this information is not available.

戻り値:

現在プールから貸し出されているインスタンスの数

the total number of instances currently borrowed from my pool

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

getNumActive

public int getNumActive(Object key)
                 throws UnsupportedOperationException

このプールから取得され、まだ戻されていない指定された key に対応するインスタンスの数を返します(オプショナルな処理)。 この情報を取得する機能を持たない場合 UnsupportedOperationException が投げられます。

Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation). Throws {@link UnsupportedOperationException} if this information is not available.

パラメータ:

key - 対象となるキー

the key

戻り値:

現在プールから貸し出されている指定された key に対応するインスタンスの数

the number of instances corresponding to the given key currently borrowed in my pool

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

getNumIdle

public int getNumIdle()
               throws UnsupportedOperationException

現在プール内にある使用されていないインスタンスの数を返します(オプショナルな処理)。 この情報を取得する機能を持たない場合 UnsupportedOperationException が投げられます。

Returns the total number of instances currently idle in my pool (optional operation). Throws {@link UnsupportedOperationException} if this information is not available.

戻り値:

プール内にある使用されていないインスタンスの数

the total number of instances currently idle in my pool

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

getNumIdle

public int getNumIdle(Object key)
               throws UnsupportedOperationException

現在プール内にある使用されていない指定された key に対応するインスタンスの数を返します(オプショナルな処理)。 この情報を取得する機能を持たない場合 UnsupportedOperationException が投げられます。

Returns the number of instances corresponding to the given key currently idle in my pool (optional operation). Throws {@link UnsupportedOperationException} if this information is not available.

パラメータ:

key - 対象となるキー

the key

戻り値:

プール内にある使用されていない指定された key に対応するインスタンスの数

the number of instances corresponding to the given key currently idle in my pool

例外:

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation

invalidateObject

public void invalidateObject(Object key,
                             Object obj)
                      throws Exception

プール内で管理されるオブジェクトを無効にします。 対象となる obj は borrowObject か、実装クラスに定義された関連するメソッドか、 key を用いたサブインターフェイスの同等の機能を持つメソッドによって取得されたものでなくてはなりません。

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 using a key that is equivalent to the one used to borrow the Object in the first place.

このメソッドはプールから取得されたオブジェクトが(例外等で)無効であるとみなされた場合に使用するべきです。 オブジェクト取得の前、もしくは戻された後にオブジェクトの評価を行う場合には PoolableObjectFactory.validateObject(java.lang.Object) を使用して下さい。

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.

パラメータ:

obj - プールから取得 されたインスタンス

a {@link #borrowObject borrowed} instance to be returned.

例外:

Exception

returnObject

public void returnObject(Object key,
                         Object obj)
                  throws Exception

プールにインスタンスを返します。 プールに返される obj は必ず borrowObject または実装クラスやサブインターフェイスのそれと関連するメソッドを使用して 取得されたインスタンスでなくてはなりません。 また、 key には返すインスタンスを取得した際と同じ値を設定しなくてはなりません。

Return an instance to my pool. By contract, obj MUST have been obtained using {@link #borrowObject(java.lang.Object) borrowObject} or a related method as defined in an implementation or sub-interface using a key that is equivalent to the one used to borrow the Object in the first place.

パラメータ:

key - オブジェクトを取得する際に使用するキー

the key used to obtain the object

obj - プールに返す borrowObject(java.lang.Object) にて取得されたインスタンス

a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.

例外:

Exception

setFactory

public void setFactory(KeyedPoolableObjectFactory factory)
                throws IllegalStateException,
                       UnsupportedOperationException

新たなインスタンスを生成するために使用する ファクトリ を設定します(オプショナルな処理)。

Sets the {@link KeyedPoolableObjectFactory factory} I use to create new instances (optional operation).

パラメータ:

factory - 新たなインスタンスを生成するために使用する KeyedPoolableObjectFactory

the {@link KeyedPoolableObjectFactory} I use to create new instances.

例外:

IllegalStateException - ファクトリを設定できる状態でない場合

IllegalStateException when the factory cannot be set at this time

UnsupportedOperationException - この実装がこの処理をサポートしない場合

when this implementation doesn't support the operation