連線池支援

透過連線池處理 LDAP 連線有助於減輕每次 LDAP 互動建立新 LDAP 連線的開銷。Java LDAP 連線池支援雖然存在，但其配置選項和功能有限，例如連線驗證和池維護。Spring LDAP 支援對每個 ContextSource 進行詳細的池配置。

透過在應用程式上下文配置中為 <ldap:context-source /> 元素提供一個 <ldap:pooling /> 子元素來提供連線池支援。只讀和讀寫 DirContext 物件是單獨池化的（如果指定了 anonymous-read-only）。Jakarta Commons-Pool 用於提供底層的池實現。

`DirContext` 驗證

池化連線的驗證是使用自定義連線池庫而非 JDK 提供的 LDAP 連線池功能的主要動機。驗證允許在從池中取出、存入池中或在池中空閒時，檢查池化的 DirContext 連線，以確保它們仍然正確連線和配置。

如果配置了連線驗證，則使用 DefaultDirContextValidator 驗證池化連線。DefaultDirContextValidator 執行 DirContext.search(String, String, SearchControls)，其空名稱、過濾器為 "objectclass=*"，並且 SearchControls 設定為限制單個結果，僅包含 objectclass 屬性和 500ms 超時。如果返回的 NamingEnumeration 有結果，則 DirContext 透過驗證。如果沒有返回結果或丟擲異常，則 DirContext 驗證失敗。預設設定應適用於大多數 LDAP 伺服器，無需更改配置，並提供驗證 DirContext 的最快方式。如果需要自定義，可以使用驗證配置屬性進行，如池配置中所述。

如果連線丟擲被認為是非瞬時異常的異常，則會自動使連線失效。例如，如果 DirContext 例項丟擲 javax.naming.CommunicationException，則將其解釋為非瞬時錯誤，並且例項會自動失效，而無需額外的 testOnReturn 操作開銷。解釋為非瞬時異常的異常透過 PoolingContextSource 的 nonTransientExceptions 屬性進行配置。

池配置

<ldap:pooling /> 元素上提供以下屬性，用於配置 DirContext 池

表 1. 連線池配置屬性
屬性	預設值	描述
`max-active`	`8`	此池中可同時分配的每種型別（只讀或讀寫）的最大活動連線數。非正數表示無限制。
`max-total`	`-1`	此池中可同時分配的所有型別（總計）的最大活動連線數。非正數表示無限制。
`max-idle`	`8`	每種型別（只讀或讀寫）在池中可保持空閒的最大活動連線數，超出此數量的連線將被釋放。非正數表示無限制。
`min-idle`	`0`	每種型別（只讀或讀寫）在池中可保持空閒的最小活動連線數，超出此數量的連線將被建立。可以使用零（預設值）表示不建立。
`max-wait`	`-1`	池在丟擲異常之前（當沒有可用連線時）等待連線返回的最大毫秒數。非正數表示無限期等待。
`when-exhausted`	`阻塞`	指定池耗盡時的行為。 `FAIL` 選項在池耗盡時丟擲 `NoSuchElementException`。 `BLOCK` 選項等待直到新物件可用。如果 `max-wait` 為正，並且在 `max-wait` 時間到期後沒有新物件可用，則丟擲 `NoSuchElementException`。 `GROW` 選項建立並返回一個新物件（實際上使 `max-active` 失去意義）。
`test-on-borrow`	`假`	物件是否在從池中借用之前進行驗證。如果物件驗證失敗，則將其從池中刪除，並嘗試借用另一個物件。
`test-on-return`	`假`	物件是否在返回到池之前進行驗證。
`test-while-idle`	`假`	物件是否由空閒物件驅逐器（如果有）進行驗證。如果物件驗證失敗，則將其從池中刪除。
`eviction-run-interval-millis`	`-1`	空閒物件驅逐執行緒執行之間的休眠毫秒數。非正數表示不執行空閒物件驅逐執行緒。
`tests-per-eviction-run`	`3`	在空閒物件驅逐執行緒的每次執行期間（如果有）檢查的物件數。
`min-evictable-time-millis`	`1000 * 60 * 30` (30 分鐘)	物件在池中空閒的最短時間，此後它有資格被空閒物件驅逐器（如果有）驅逐。
`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`；預設搜尋控制設定如上所述。	驗證連線時要使用的 `SearchControls` 例項的 ID。僅當指定 `test-on-borrow`、`test-on-return` 或 `test-while-idle` 時使用。
`non-transient-exceptions`	`javax.naming.CommunicationException`	以逗號分隔的 `Exception` 類列表。所列異常被視為非瞬時異常，用於緊急失效。如果對池化 `DirContext` 例項的呼叫丟擲任何所列異常（或其子類），則該物件會自動失效，而無需執行任何額外的 testOnReturn 操作。

Pool2 配置

<ldap:pooling2 /> 元素上提供以下屬性，用於配置 DirContext 池

表 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`	`假`	物件是否在借用之前進行驗證。如果物件驗證失敗，則借用失敗。
`test-on-borrow`	`假`	指示物件是否在從池中借用之前進行驗證。如果物件驗證失敗，則將其從池中刪除，並嘗試借用另一個物件。
`test-on-return`	`假`	指示物件是否在返回到池之前進行驗證。
`test-while-idle`	`假`	指示物件是否由空閒物件驅逐器（如果有）進行驗證。如果物件驗證失敗，則將其從池中刪除。
`eviction-run-interval-millis`	`-1`	空閒物件驅逐執行緒執行之間的休眠毫秒數。非正數表示不執行空閒物件驅逐執行緒。
`tests-per-eviction-run`	`3`	在空閒物件驅逐執行緒的每次執行期間（如果有）檢查的物件數。
`min-evictable-time-millis`	`1000 * 60 * 30` (30 分鐘)	物件在池中空閒的最短時間，此後它有資格被空閒物件驅逐器（如果有）驅逐。
`soft-min-evictable-time-millis`	`-1`	物件在池中空閒的最短時間，此後它有資格被空閒物件驅逐器驅逐，並附加條件是池中每個鍵至少保留最小數量的物件例項。如果 `min-evictable-time-millis` 設定為正值，則此設定將被覆蓋。
`eviction-policy-class`	`org.apache.commons.pool2.impl.DefaultEvictionPolicy`	此池使用的驅逐策略實現。池嘗試使用執行緒上下文類載入器載入類。如果失敗，池嘗試使用載入此類的類載入器載入類。
`fairness`	`假`	池公平地服務等待借用連線的執行緒。`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`；預設搜尋控制設定如上所述。	驗證連線時要使用的 `SearchControls` 例項的 ID。僅當指定 `test-on-borrow`、`test-on-return` 或 `test-while-idle` 時使用。
`non-transient-exceptions`	`javax.naming.CommunicationException`	以逗號分隔的 `Exception` 類列表。所列異常被視為非瞬時異常，用於緊急失效。如果對池化 `DirContext` 例項的呼叫丟擲任何所列異常（或其子類），則該物件會自動失效，而無需執行任何額外的 testOnReturn 操作。

配置

配置連線池需要將 <ldap:pooling> 元素巢狀在 <ldap:context-source> 元素中，如下所示

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

在實際情況下，您可能會配置池選項並啟用連線驗證。前面的示例演示了一般思路。

驗證配置

以下示例在每個 DirContext 傳遞給客戶端應用程式之前對其進行測試，並測試在池中空閒的 DirContext 物件

<beans>
   ...
    <ldap:context-source
        username="cn=Manager" password="secret" url="ldap://: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 指定的使用者填充。