此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring LDAP 3.2.8！spring-doc.cadn.net.cn

池化支持

池化 LDAP 连接有助于减少为每个 LDAP 交互创建新的 LDAP 连接的开销。虽然存在 Java LDAP 池支持，但它的配置选项和功能（如连接验证和池维护）受到限制。Spring LDAP 支持在每个ContextSource基础。spring-doc.cadn.net.cn

池化支持是通过提供<ldap:pooling />child 元素添加到<ldap:context-source />元素。只读和读写DirContext对象单独池化（如果anonymous-read-only）。Jakarta Commons-Pool 用于提供底层的矿池实现。spring-doc.cadn.net.cn

`DirContext`验证

验证池连接是使用自定义池库而不是 JDK 提供的 LDAP 池功能的主要动机。验证允许共用DirContext检查连接，以确保在将它们签出池、签入池或当它们在池中空闲时，它们仍然正确连接和配置。spring-doc.cadn.net.cn

如果配置了连接验证，则使用DefaultDirContextValidator.DefaultDirContextValidator执行DirContext.search(String, String, SearchControls)，如果名称为空，则过滤器"objectclass=*"和SearchControlsset 来限制单个结果，而只有objectclass属性和 500 毫秒的超时。如果返回的NamingEnumeration有结果，则DirContext通过验证。如果未返回任何结果或引发异常，则DirContext未通过验证。在大多数 LDAP 服务器上，默认设置应该无需更改配置即可使用，并提供最快的方法来验证DirContext. 如果需要自定义，可以使用池配置中描述的验证配置属性来实现自定义。spring-doc.cadn.net.cn

如果连接引发被视为非暂时性的异常，则连接将自动失效。例如，如果DirContext实例会抛出一个javax.naming.CommunicationException，它将被解释为非暂时性错误，并且实例会自动失效，而不会产生额外的testOnReturn操作。解释为非瞬态的异常是使用nonTransientExceptions属性的PoolingContextSource.

池配置

以下属性在<ldap:pooling />元素来配置 DirContext 池：spring-doc.cadn.net.cn

表 1.池化配置属性
属性	违约	描述
`max-active`spring-doc.cadn.net.cn	`8`spring-doc.cadn.net.cn	可以同时从此池分配的每种类型（只读或读写）的活动连接的最大数量。您可以无限制地使用非正数。spring-doc.cadn.net.cn
`max-total`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	可以同时从此池中分配的活动连接总数（适用于所有类型）。您可以无限制地使用非正数。spring-doc.cadn.net.cn
`max-idle`spring-doc.cadn.net.cn	`8`spring-doc.cadn.net.cn	每种类型（只读或读写）在池中保持空闲状态而不释放额外连接的最大活动连接数。您可以无限制地使用非正数。spring-doc.cadn.net.cn
`min-idle`spring-doc.cadn.net.cn	`0`spring-doc.cadn.net.cn	可以在池中保持空闲状态的每种类型（只读或读写）的活动连接的最小数量，而无需创建额外的连接。您可以使用 0（默认值）来不创建 none。spring-doc.cadn.net.cn
`max-wait`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	池在引发异常之前等待（没有可用连接时）返回连接的最大毫秒数。您可以使用非正数无限期等待。spring-doc.cadn.net.cn
`when-exhausted`spring-doc.cadn.net.cn	`BLOCK`spring-doc.cadn.net.cn	指定池耗尽时的行为。spring-doc.cadn.net.cn 这`FAIL`选项抛出`NoSuchElementException`当池耗尽时。spring-doc.cadn.net.cn 这`BLOCK`option 等待，直到有新对象可用。如果`max-wait`为正数，并且在`max-wait`时间到期，`NoSuchElementException`被抛出。spring-doc.cadn.net.cn 这`GROW`option 创建并返回一个新对象（本质上是使`max-active`毫无意义）。spring-doc.cadn.net.cn
`test-on-borrow`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	在从池中借用对象之前是否对其进行验证。如果对象验证失败，则会将其从池中删除，并尝试借用另一个对象。spring-doc.cadn.net.cn
`test-on-return`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	在将对象返回到池之前是否对其进行验证。spring-doc.cadn.net.cn
`test-while-idle`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	对象是否由空闲对象 evictor （（如果有））验证。如果对象验证失败，则会将其从池中删除。spring-doc.cadn.net.cn
`eviction-run-interval-millis`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	空闲对象 evictor 线程运行之间休眠的毫秒数。当为非正数时，不运行空闲对象 evictor 线程。spring-doc.cadn.net.cn
`tests-per-eviction-run`spring-doc.cadn.net.cn	`3`spring-doc.cadn.net.cn	在每次运行空闲对象 evictor 线程期间要检查的对象数（如果有）。spring-doc.cadn.net.cn
`min-evictable-time-millis`spring-doc.cadn.net.cn	`1000 * 60 * 30`（30 分钟）spring-doc.cadn.net.cn	对象在有资格被空闲对象 evictor （如果有）逐出之前，可以在池中处于空闲状态的最短时间。spring-doc.cadn.net.cn
`validation-query-base`spring-doc.cadn.net.cn	`LdapUtils.emptyName()`spring-doc.cadn.net.cn	验证连接时使用的搜索库。仅在以下情况下使用`test-on-borrow`,`test-on-return`或`test-while-idle`。spring-doc.cadn.net.cn
`validation-query-filter`spring-doc.cadn.net.cn	`objectclass=*`spring-doc.cadn.net.cn	验证连接时使用的搜索筛选条件。仅在以下情况下使用`test-on-borrow`,`test-on-return`或`test-while-idle`。spring-doc.cadn.net.cn
`validation-query-search-controls-ref`spring-doc.cadn.net.cn	`null`;默认搜索控制设置如上所述。spring-doc.cadn.net.cn	一个`SearchControls`实例。仅在`test-on-borrow`,`test-on-return`或`test-while-idle`。spring-doc.cadn.net.cn
`non-transient-exceptions`spring-doc.cadn.net.cn	`javax.naming.CommunicationException`spring-doc.cadn.net.cn	逗号分隔的`Exception`类。列出的异常被视为非暂时性 Age Invalidation 。如果对池`DirContext`实例，则该对象将自动失效，无需任何其他 testOnReturn作。spring-doc.cadn.net.cn

Pool2 配置

以下属性在<ldap:pooling2 />元素来配置DirContext池：spring-doc.cadn.net.cn

表 2.池化配置属性
属性	违约	描述
`max-total`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	可以同时从此池中分配的活动连接总数（适用于所有类型）。您可以无限制地使用非正数。spring-doc.cadn.net.cn
`max-total-per-key`spring-doc.cadn.net.cn	`8`spring-doc.cadn.net.cn	每个键的池分配的对象实例数（签出或空闲）的限制。达到限制时，子池将耗尽。负值表示没有限制。spring-doc.cadn.net.cn
`max-idle-per-key`spring-doc.cadn.net.cn	`8`spring-doc.cadn.net.cn	可以在池中保持空闲状态的每种类型（只读或读写）的最大活动连接数，而不会释放额外的连接。负值表示没有限制。spring-doc.cadn.net.cn
`min-idle-per-key`spring-doc.cadn.net.cn	`0`spring-doc.cadn.net.cn	可以在池中保持空闲状态的每种类型（只读或读写）的最小活动连接数，而无需创建额外的连接。您可以使用 0（默认值）来不创建 none。spring-doc.cadn.net.cn
`max-wait`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	池在引发异常之前等待（没有可用连接时）返回连接的最大毫秒数。您可以使用非正数无限期等待。spring-doc.cadn.net.cn
`block-when-exhausted`spring-doc.cadn.net.cn	`true`spring-doc.cadn.net.cn	是否等待新对象可用。如果 max-wait 为正数，则`NoSuchElementException`如果在`maxWait`时间到期。spring-doc.cadn.net.cn
`test-on-create`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	借用前是否验证对象。如果对象验证失败，则借用失败。spring-doc.cadn.net.cn
`test-on-borrow`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	指示对象在从池中借用之前是否经过验证的指示器。如果对象验证失败，则会将其从池中删除，并尝试借用另一个对象。spring-doc.cadn.net.cn
`test-on-return`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	指示对象在返回到池之前是否经过验证的指示器。spring-doc.cadn.net.cn
`test-while-idle`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	指示对象是否由空闲对象 evictor （（如果有））验证的指示器。如果对象验证失败，则会将其从池中删除。spring-doc.cadn.net.cn
`eviction-run-interval-millis`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	空闲对象 evictor 线程运行之间休眠的毫秒数。当为非正数时，不运行空闲对象 evictor 线程。spring-doc.cadn.net.cn
`tests-per-eviction-run`spring-doc.cadn.net.cn	`3`spring-doc.cadn.net.cn	在每次运行空闲对象 evictor 线程期间要检查的对象数（如果有）。spring-doc.cadn.net.cn
`min-evictable-time-millis`spring-doc.cadn.net.cn	`1000 * 60 * 30`（30 分钟）spring-doc.cadn.net.cn	对象在有资格被空闲对象 evictor （如果有）逐出之前，可以在池中处于空闲状态的最短时间。spring-doc.cadn.net.cn
`soft-min-evictable-time-millis`spring-doc.cadn.net.cn	`-1`spring-doc.cadn.net.cn	对象在有资格被空闲对象 evictor 驱逐之前可以在池中闲置的最短时间，额外的条件是每个键至少保留池中的最小对象实例数。此设置被`min-evictable-time-millis`如果它设置为正值。spring-doc.cadn.net.cn
`eviction-policy-class`spring-doc.cadn.net.cn	`org.apache.commons.pool2.impl.DefaultEvictionPolicy`spring-doc.cadn.net.cn	此池使用的逐出策略实现。池尝试使用线程上下文类加载器加载类。如果失败，则池将尝试使用加载此类的类加载器来加载该类。spring-doc.cadn.net.cn
`fairness`spring-doc.cadn.net.cn	`false`spring-doc.cadn.net.cn	该池为等待公平借用连接的线程提供服务。`true`表示等待线程就像在 FIFO 队列中等待一样提供。spring-doc.cadn.net.cn
`jmx-enable`spring-doc.cadn.net.cn	`true`spring-doc.cadn.net.cn	JMX 使用池的平台 MBean 服务器启用。spring-doc.cadn.net.cn
`jmx-name-base`spring-doc.cadn.net.cn	`null`spring-doc.cadn.net.cn	JMX 名称库，用作分配给启用 JMX 的池的名称的一部分。spring-doc.cadn.net.cn
`jmx-name-prefix`spring-doc.cadn.net.cn	`pool`spring-doc.cadn.net.cn	JMX 名称前缀，用作分配给已启用 JMX 的池的名称的一部分。spring-doc.cadn.net.cn
`lifo`spring-doc.cadn.net.cn	`true`spring-doc.cadn.net.cn	指示池是否具有相对于空闲对象或 FIFO（先进先出）队列的 LIFO （后进先出）行为的指示器。LIFO 始终返回池中最近使用的对象，而 FIFO 始终返回空闲对象池中最早的对象spring-doc.cadn.net.cn
`validation-query-base`spring-doc.cadn.net.cn	`LdapUtils.emptyPath()`spring-doc.cadn.net.cn	用于验证搜索的基本 DN。spring-doc.cadn.net.cn
`validation-query-filter`spring-doc.cadn.net.cn	`objectclass=*`spring-doc.cadn.net.cn	用于验证查询的筛选条件。spring-doc.cadn.net.cn
`validation-query-search-controls-ref`spring-doc.cadn.net.cn	`null`;默认搜索控制设置如上所述。spring-doc.cadn.net.cn	一个`SearchControls`实例。仅在以下情况下使用`test-on-borrow`,`test-on-return`或`test-while-idle`指定spring-doc.cadn.net.cn
`non-transient-exceptions`spring-doc.cadn.net.cn	`javax.naming.CommunicationException`spring-doc.cadn.net.cn	逗号分隔的`Exception`类。列出的异常被视为非暂时性 Age Invalidation 。如果对池`DirContext`实例，则该对象将自动失效，无需任何其他 testOnReturn作。spring-doc.cadn.net.cn

配置

配置池化需要添加<ldap:pooling>元素嵌套在<ldap:context-source>元素，如下所示：spring-doc.cadn.net.cn

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

在实际情况下，您可能会配置池选项并启用连接验证。前面的示例演示了一般思路。spring-doc.cadn.net.cn

验证配置

以下示例测试每个DirContext在传递给客户端应用程序并测试DirContext池中一直处于空闲状态的对象：spring-doc.cadn.net.cn

<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 时有时会出现的问题。目前，它涵盖了以下问题：spring-doc.cadn.net.cn

自定义身份验证 spring-doc.cadn.net.cn

自定义身份验证

这PoolingContextSource假设所有DirContext检索对象ContextSource.getReadOnlyContext()具有相同的环境，同样，所有DirContext检索对象ContextSource.getReadWriteContext()具有相同的环境。这意味着，将LdapContextSource配置了AuthenticationSource在PoolingContextSource未按预期运行。池将使用第一个用户的凭证填充，并且，除非需要新连接，否则不会为AuthenticationSource对于请求线程。spring-doc.cadn.net.cn