Advanced LDAP Queries

本部分介绍如何使用 Spring LDAP 与 LDAP 查询。

This section covers various how to use LDAP queries with Spring LDAP.

LDAP Query Builder Parameters

LdapQueryBuilder 及其关联类旨在支持可以提供给 LDAP 搜索的所有参数。支持以下参数：

The LdapQueryBuilder and its associated classes are intended to support all of the parameters that can be supplied to an LDAP search. The following parameters are supported:

base: 指定应该从哪个 LDAP 树的根 DN 开始进行搜索。
base: Specifies the root DN in the LDAP tree where the search should start.
searchScope: 指定搜索应该遍历 LDAP 树的深度。
searchScope: Specifies how deep into the LDAP tree the search should traverse.
attributes: 指定从搜索中返回的属性。默认设置为全部。
attributes: Specifies the attributes to return from the search. The default is all.
countLimit: 指定从搜索中返回的最大条目数量。
countLimit: Specifies the maximum number of entries to return from the search.
timeLimit: 指定搜索可能花费的最大时间。
timeLimit: Specifies the maximum time that the search may take.
搜索过滤器：我们要查找的条目必须满足的条件。
Search filter: The conditions that the entries we are looking for must meet.

使用 LdapQueryBuilder 的 query 方法调用创建一个 LdapQueryBuilder。它被视为一种流畅的构建器 API，其中首先定义基本参数，随后是过滤器规范调用。一旦使用 LdapQueryBuilder 的 where 方法开始定义过滤器条件，则稍后尝试调用（例如）base 将被拒绝。基本搜索参数是可选的，但至少需要一个过滤器规范调用。以下查询搜索具有 Person 对象类的所有条目：

An LdapQueryBuilder is created with a call to the query method of LdapQueryBuilder. It is intended as a fluent builder API, where the base parameters are defined first, followed by the filter specification calls. Once filter conditions have been started to be defined with a call to the where method of LdapQueryBuilder, later attempts to call (for example) base are rejected. The base search parameters are optional, but at least one filter specification call is required. The following query searches for all entries with an object class of Person:

Example 1. Search for all entries with object class Person

import static org.springframework.ldap.query.LdapQueryBuilder.query;
...

List<Person> persons = ldapClient.search()
      .query(query().where("objectclass").is("person"))
      .toList(new PersonAttributesMapper());

以下查询搜索具有 person 对象类并且 cn（通用名称）为 John Doe 的所有条目：

The following query searches for all entries with an object class of person and a cn (common name) of John Doe:

Example 2. Search for all entries with object class person and cn=John Doe

import static org.springframework.ldap.query.LdapQueryBuilder.query;
...

List<Person> persons = ldapClient.search()
      .query(query().where("objectclass").is("person").and("cn").is("John Doe"))
      .toList(new PersonAttributesMapper());

以下查询搜索具有 person 对象类并且起始于 dc（域组件）为 dc=261consulting,dc=com 的所有条目：

The following query searches for all entries with an object class of person and starting at a dc (domain component) of dc=261consulting,dc=com:

Example 3. Search for all entries with object class person starting at dc=261consulting,dc=com

import static org.springframework.ldap.query.LdapQueryBuilder.query;
...

List<Person> persons = ldapClient.search()
      .query(query().base("dc=261consulting,dc=com").where("objectclass").is("person"))
      .toList(new PersonAttributesMapper());

以下查询返回具有 person 对象类并且起始于 dc（域组件）为 dc=261consulting,dc=com 的所有条目的 cn（通用名称）属性：

The following query returns the cn (common name) attribute for all entries with an object class of person and starting at a dc (domain component) of dc=261consulting,dc=com:

Example 4. Search for all entries with class Person starting at dc=261consulting,dc=com, returning only the cn attribute

import static org.springframework.ldap.query.LdapQueryBuilder.query;
...

Stream<Person> persons = ldapClient.search()
      .query(query().base("dc=261consulting,dc=com")
             .attributes("cn")
             .where("objectclass").is("person")),
      .toStream(new PersonAttributesMapper());

以下查询使用 or 来搜索通用名称 (cn) 的多种拼写：

The following query uses or to search for multiple spellings of a common name (cn):

Example 5. Search with or criteria

import static org.springframework.ldap.query.LdapQueryBuilder.query;
...
Stream<Person> persons = ldapClient.search()
      .query(query().where("objectclass").is("person"),
             .and(query().where("cn").is("Doe").or("cn").is("Doo"))
      .toStream(new PersonAttributesMapper());

Filter Criteria

早期的例子演示了 LDAP 过滤器中的简单等式条件。LDAP 查询生成器支持以下条件类型：

The earlier examples demonstrate simple equals conditions in LDAP filters. The LDAP query builder has support for the following criteria types:

is: 指定等于 (=) 条件。
is: Specifies an equals (=) condition.
gte: 指定大于或等于 (>=) 条件。
gte: Specifies a greater-than-or-equals (>=) condition.
lte: 指定小于或等于 (⇐) 条件。
lte: Specifies a less-than-or-equals (⇐) condition.
like: 指定一个 "`like`"条件，其中通配符可以包含在查询中——例如，where("cn").like("J*hn Doe")`将生成以下过滤器：(cn=J*hn Doe)`。
like: Specifies a “like” condition where wildcards can be included in the query — for example, where("cn").like("J*hn Doe") results in the following filter: (cn=J*hn Doe).
whitespaceWildcardsLike: 指定一个条件，其中所有空格都替换为通配符——例如，where("cn").whitespaceWildcardsLike("John Doe")`将生成以下过滤器：(cn=John*Doe)`。
whitespaceWildcardsLike: Specifies a condition where all whitespace is replaced with wildcards — for example, where("cn").whitespaceWildcardsLike("John Doe") results in the following filter: (cn=John*Doe).
isPresent: 指定检查属性存在的条件——例如，where("cn").isPresent()`将生成以下过滤器：(cn=*)`。
isPresent: Specifies a condition that checks for the presence of an attribute — for example, where("cn").isPresent() results in the following filter: (cn=*).
not: 指定应该否定当前条件——例如，where("sn").not().is("Doe)`将生成以下过滤器：(!(sn=Doe))`。
not: Specifies that the current condition should be negated — for example, where("sn").not().is("Doe) results in the following filter: (!(sn=Doe))

Hardcoded Filters

有时您可能希望指定硬编码过滤器作为 LdapQuery 的输入。LdapQueryBuilder 有两种方法可以实现此目的：

There may be occasions when you want to specify a hardcoded filter as input to an LdapQuery. LdapQueryBuilder has two methods for this purpose:

filter(String hardcodedFilter): 将指定字符串用作过滤器。请注意，不会以任何方式触及指定的输入字符串，这意味着如果您要从用户输入构建过滤器，则此方法并不是特别合适。
filter(String hardcodedFilter): Uses the specified string as a filter. Note that the specified input string is not touched in any way, meaning that this method is not particularly well suited if you are building filters from user input.
filter(String filterFormat, String… params): 将指定字符串用作 `MessageFormat`的输入，正确地对参数进行编码，并将其插入过滤器字符串中的指定位置。
filter(String filterFormat, String… params): Uses the specified string as input to MessageFormat, properly encoding the parameters and inserting them at the specified places in the filter string.
filter(Filter filter): 使用指定过滤器。
filter(Filter filter): Uses the specified filter.

您不能将硬编码过滤器方法与前面描述的 where 方法混合使用。只能选择其中一种。如果您使用 filter() 指定过滤器，那么尝试在之后调用 where 时您将收到一个异常。

You cannot mix the hardcoded filter methods with the where approach described earlier. It is either one or the other. If you specify a filter by using filter(), you get an exception if you try to call where afterwards.