このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring LDAP 3.3.3 を使用してください！

プーリングのサポート

LDAP 接続をプールすると、LDAP の対話ごとに新しい LDAP 接続を作成するオーバーヘッドを軽減できます。Java LDAP プーリングのサポート (英語) は存在しますが、接続の検証やプールのメンテナンスなど、構成オプションと機能が制限されています。Spring LDAP は、ContextSource ごとに詳細なプール構成をサポートします。

プーリングのサポートは、アプリケーションコンテキスト構成で <ldap:context-source /> 要素に <ldap:pooling /> 子要素を提供することによって提供されます。読み取り専用および読み取り / 書き込み DirContext オブジェクトは別々にプールされます (anonymous-read-only が指定されている場合)。Jakarta コモンズプール [Apache] (英語) は、基礎となるプールの実装を提供するために使用されます。

`DirContext` 検証

JDK が提供する LDAP プーリング機能ではなく、カスタムプーリングライブラリを使用する主な動機は、プールされた接続の検証です。検証により、プールされた DirContext 接続をチェックして、プールからチェックアウトするとき、プールにチェックインするとき、プール内でアイドル状態になっているときに、それらが適切に接続および構成されていることを確認できます。

接続検証が構成されている場合、プールされた接続は DefaultDirContextValidator を使用して検証されます。DefaultDirContextValidator は、空の名前、"objectclass=*" のフィルター、および objectclass 属性のみと 500 ミリ秒のタイムアウトで単一の結果を制限するように設定された SearchControls を使用して DirContext.search(String, String, SearchControls) を実行します。返された NamingEnumeration に結果がある場合、DirContext は検証に合格します。結果が返されないか、例外がスローされた場合、DirContext は検証に失敗します。デフォルト設定は、ほとんどの LDAP サーバーで構成を変更しなくても機能し、DirContext を検証する最速の方法を提供します。カスタマイズが必要な場合は、プール構成で説明されている検証構成属性を使用して実行できます。

非一時的と見なされる例外をスローすると、接続は自動的に無効になります。例: DirContext インスタンスが javax.naming.CommunicationException をスローすると、一時的でないエラーとして解釈され、追加の testOnReturn 操作のオーバーヘッドなしでインスタンスが自動的に無効になります。非一時的であると解釈される例外は、PoolingContextSource の nonTransientExceptions プロパティを使用して構成されます。

プール構成

DirContext プールの構成のために、<ldap:pooling /> エレメントで以下の属性を使用できます。

表 1: プーリング構成属性
属性	デフォルト	説明
`max-active`	`8`	このプールから同時に割り当てることができる各型 (読み取り専用または読み取り / 書き込み) のアクティブな接続の最大数。正でない数値を無制限に使用できます。
`max-total`	`-1`	このプールから同時に割り当てることができる (すべての型の) アクティブな接続の全体的な最大数。正でない数値を無制限に使用できます。
`max-idle`	`8`	追加の接続が解放されることなくプール内でアイドル状態を維持できる、各型 (読み取り専用または読み取り / 書き込み) のアクティブな接続の最大数。正でない数値を無制限に使用できます。
`min-idle`	`0`	追加の接続を作成せずにプール内でアイドル状態を維持できる、各型 (読み取り専用または読み取り / 書き込み) のアクティブな接続の最小数。ゼロ (デフォルト) を使用して、何も作成しないようにすることができます。
`max-wait`	`-1`	例外をスローする前に接続が返されるのをプールが (接続が使用できない場合に) 待機する最大ミリ秒数。正でない数値を使用して、無期限に待機できます。
`when-exhausted`	`BLOCK`	プールが使い果たされたときの動作を指定します。 `FAIL` オプションは、プールが使い果たされると `NoSuchElementException` をスローします。 `BLOCK` オプションは、新しいオブジェクトが使用可能になるまで待機します。`max-wait` が正で、`max-wait` 時間の経過後に新しいオブジェクトが使用できない場合、`NoSuchElementException` がスローされます。 `GROW` オプションは、新しいオブジェクトを作成して返します (基本的に `max-active` は無意味になります)。
`test-on-borrow`	`false`	プールから借用する前にオブジェクトを検証するかどうか。オブジェクトの検証に失敗した場合、そのオブジェクトはプールから削除され、別のオブジェクトを借用しようとします。
`test-on-return`	`false`	オブジェクトがプールに返される前に検証されるかどうか。
`test-while-idle`	`false`	オブジェクトがアイドルオブジェクト evictor (存在する場合) によって検証されるかどうか。検証に失敗したオブジェクトは、プールから削除されます。
`eviction-run-interval-millis`	`-1`	アイドル状態のオブジェクト evictor スレッドの実行の間にスリープするミリ秒数。正でない場合、アイドルオブジェクトの Evictor スレッドは実行されません。
`tests-per-eviction-run`	`3`	アイドル状態のオブジェクト Evictor スレッド (存在する場合) の各実行中に検査するオブジェクトの数。
`min-evictable-time-millis`	`1000 * 60 * 30` (30 minutes)	The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
`validation-query-base`	`LdapUtils.emptyName()`	接続を検証するときに使用する検索ベース。`test-on-borrow`、`test-on-return`、または `test-while-idle` が指定されている場合にのみ使用されます。
`validation-query-filter`	`objectclass=*`	接続を検証するときに使用する検索フィルター。`test-on-borrow`、`test-on-return`、または `test-while-idle` が指定されている場合にのみ使用されます。
`validation-query-search-controls-ref`	`null`; default search control settings are described above.	The ID of a `SearchControls` instance to be used when validating connections. Only used if `test-on-borrow`, `test-on-return`, or `test-while-idle` is specified.
`non-transient-exceptions`	`javax.naming.CommunicationException`	`Exception` クラスのカンマ区切りリスト。リストされた例外は、積極的な無効化に関して非一時的であると見なされます。リストされた例外 (またはそれらのサブクラス) のいずれかが、プールされた `DirContext` インスタンスへの呼び出しによってスローされた場合、そのオブジェクトは追加の testOnReturn 操作なしで自動的に無効になります。

プール 2 の構成

DirContext プールを構成するために、<ldap:pooling2 /> 要素で次の属性を使用できます。

表 2: プーリング構成属性
属性	デフォルト	説明
`max-total`	`-1`	このプールから同時に割り当てることができる (すべての型の) アクティブな接続の全体的な最大数。正でない数値を無制限に使用できます。
`max-total-per-key`	`8`	キーごとに、プール (チェックアウトまたはアイドル) によって割り当てられるオブジェクトインスタンスの数の制限。制限に達すると、サブプールが使い果たされます。負の値は制限がないことを示します。
`max-idle-per-key`	`8`	余分な接続が解放されることなく、プール内でアイドル状態を維持できる各型 (読み取り専用または読み取り / 書き込み) のアクティブな接続の最大数。負の値は制限がないことを示します。
`min-idle-per-key`	`0`	追加の接続を作成せずにプール内でアイドル状態を維持できる、各型 (読み取り専用または読み取り / 書き込み) のアクティブな接続の最小数。ゼロ (デフォルト) を使用して、何も作成しないようにすることができます。
`max-wait`	`-1`	例外をスローする前に接続が返されるのをプールが (使用可能な接続がない場合に) 待機する最大ミリ秒数。正でない数値を使用して、無期限に待機できます。
`block-when-exhausted`	`true`	新しいオブジェクトが利用可能になるまで待機するかどうか。max-wait が正の場合、`maxWait` 時間の期限が切れた後に新しいオブジェクトが利用できない場合、`NoSuchElementException` がスローされます。
`test-on-create`	`false`	オブジェクトを借用する前に検証するかどうか。オブジェクトの検証に失敗すると、借用は失敗します。
`test-on-borrow`	`false`	オブジェクトがプールから借用される前に検証されるかどうかの指標。オブジェクトの検証に失敗した場合、そのオブジェクトはプールから削除され、別のオブジェクトを借用しようとします。
`test-on-return`	`false`	オブジェクトがプールに返される前に検証されるかどうかの指標。
`test-while-idle`	`false`	オブジェクトがアイドルオブジェクト evictor (存在する場合) によって検証されるかどうかのインジケーター。検証に失敗したオブジェクトは、プールから削除されます。
`eviction-run-interval-millis`	`-1`	アイドル状態のオブジェクト evictor スレッドの実行の間にスリープするミリ秒数。正でない場合、アイドルオブジェクトの Evictor スレッドは実行されません。
`tests-per-eviction-run`	`3`	アイドル状態のオブジェクト Evictor スレッド (存在する場合) の各実行中に検査するオブジェクトの数。
`min-evictable-time-millis`	`1000 * 60 * 30` (30 minutes)	The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
`soft-min-evictable-time-millis`	`-1`	アイドル状態のオブジェクト Evictor によるエビクションの対象となる前に、オブジェクトがプール内でアイドル状態を保つことができる最小時間。追加の条件として、少なくともキーごとの最小数のオブジェクトインスタンスがプール内に残っている必要があります。この設定は、正の値に設定されている場合、`min-evictable-time-millis` によってオーバーライドされます。
`eviction-policy-class`	`org.apache.commons.pool2.impl.DefaultEvictionPolicy`	このプールで使用されるエビクションポリシーの実装。プールは、スレッドコンテキストクラスローダーを使用してクラスを読み込もうとします。それが失敗した場合、プールは、このクラスをロードしたクラスローダーを使用してクラスをロードしようとします。
`fairness`	`false`	プールは、接続を公平に借用するのを待っているスレッドにサービスを提供します。`true` は、待機スレッドが FIFO キューで待機しているかのように処理されることを意味します。
`jmx-enable`	`true`	JMX は、プールのプラットフォーム MBean サーバーで有効になります。
`jmx-name-base`	`null`	JMX 対応プールに割り当てられる名前の一部として使用される JMX ネームベース。
`jmx-name-prefix`	`pool`	JMX 対応プールに割り当てられる名前の一部として使用される JMX 名のプレフィックス。
`lifo`	`true`	プールが、アイドル状態のオブジェクトに対して LIFO (後入れ先出し) 動作を行うか、FIFO (先入れ先出し) キューとして動作するかを示す指標。LIFO は常にプールから最後に使用されたオブジェクトを返しますが、FIFO は常にアイドルオブジェクトプール内の最も古いオブジェクトを返します。
`validation-query-base`	`LdapUtils.emptyPath()`	検証検索に使用するベース DN。
`validation-query-filter`	`objectclass=*`	検証クエリに使用するフィルター。
`validation-query-search-controls-ref`	`null`; default search control settings are described above.	The ID of a `SearchControls` instance to be used when validating connections. Used only if `test-on-borrow`, `test-on-return`, or `test-while-idle` is specified
`non-transient-exceptions`	`javax.naming.CommunicationException`	`Exception` クラスのカンマ区切りリスト。リストされた例外は、積極的な無効化に関して非一時的であると見なされます。リストされた例外 (またはそれらのサブクラス) のいずれかが、プールされた `DirContext` インスタンスへの呼び出しによってスローされた場合、そのオブジェクトは追加の testOnReturn 操作なしで自動的に無効になります。

構成

プーリングを構成するには、次のように、<ldap:context-source> 要素にネストされた <ldap:pooling> 要素を追加する必要があります。

<beans>
   ...
    <ldap:context-source
        password="secret" url="ldap://localhost:389" username="cn=Manager">
        <ldap:pooling />
    </ldap:context-source>
   ...
</beans>

実際の状況では、おそらくプールオプションを構成し、接続の検証を有効にします。前の例は、一般的な考え方を示しています。

検証構成

次の例では、クライアントアプリケーションに渡される前に各 DirContext をテストし、プール内でアイドル状態になっている DirContext オブジェクトをテストします。

<beans>
   ...
    <ldap:context-source
        username="cn=Manager" password="secret" url="ldap://localhost:389" >
        <ldap:pooling
            test-on-borrow="true"
            test-while-idle="true" />
    </ldap:context-source>
   ...
</beans>

既知の問題

このセクションでは、Spring LDAP を使用するときに発生することがある課題について説明します。現在、以下の課題をカバーしています。

カスタム認証

カスタム認証

PoolingContextSource は、ContextSource.getReadOnlyContext() から取得されたすべての DirContext オブジェクトが同じ環境を持ち、同様に、ContextSource.getReadWriteContext() から取得されたすべての DirContext オブジェクトが同じ環境を持っていると想定します。これは、AuthenticationSource で構成された LdapContextSource を PoolingContextSource でラップしても、期待どおりに機能しないことを意味します。プールは最初のユーザーの資格情報を使用して設定され、新しい接続が必要でない限り、リクエスト元スレッドの AuthenticationSource によって指定されたユーザーの後続のコンテキストリクエストは満たされません。