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: Specifies the root DN in the LDAP tree where the search should start.
searchScope: Specifies how deep into the LDAP tree the search should traverse.
attributes: Specifies the attributes to return from the search. The default is all.
countLimit: Specifies the maximum number of entries to return from the search.
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: Specifies an equals (=) condition.
gte: Specifies a greater-than-or-equals (>=) condition.
lte: Specifies a less-than-or-equals (⇐) condition.
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: 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: Specifies a condition that checks for the presence of an attribute — for example, where("cn").isPresent() results in the following filter: (cn=*).
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): 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): 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): 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.