此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring LDAP 3.3.3！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=*"和SearchControls设置为仅使用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	每种类型（只读或读写）的活动连接的最小数量，这些连接可以在池中保持空闲状态，而无需创建额外的连接。您可以使用零（默认值）来创建 non。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`选项，等待新对象可用。如果`max-wait`为正数，并且之后没有可用的新对象`max-wait`时间到期，`NoSuchElementException`被抛出。spring-doc.cadn.net.cn 这`GROW`选项创建并返回一个新对象（本质上是使`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	的 ID`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`类。列出的例外在预急失效方面被视为非暂时性。如果调用池的`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	每种类型（只读或读写）的活动连接的最小数量，可以在池中保持空闲状态，而无需创建额外的连接。您可以使用零（默认值）来创建 non。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	指示池是否具有空闲对象的 LIFO（后进先出）行为或作为 FIFO（先进先出）队列。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	的 ID`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`类。列出的例外在预急失效方面被视为非暂时性。如果调用池的`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