基本用法

使用 AttributesMapper 进行搜索和查找

以下示例使用 AttributesMapper 构建所有人员对象的所有通用名称的列表。

示例 1. 返回单个属性的 AttributesMapper
import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;

   public void setLdapClient(LdapClient ldapClient) {
      this.ldapClient = ldapClient;
   }

   public List<String> getAllPersonNames() {
      return ldapClient.search()
                .query(query().where("objectclass").is("person"))
                .toList((Attributes attrs) -> (String) attrs.get("cn").get());
   }
}

AttributesMapper 的内联实现从 Attributes 对象中获取所需的属性值并返回该值。在内部，LdapClient 遍历找到的所有条目，为每个条目调用给定的 AttributesMapper，并将结果收集到列表中。然后由 search 方法返回该列表。

请注意，AttributesMapper 实现可以轻松修改为返回一个完整的 Person 对象，如下所示

示例 2. 返回 Person 对象的 AttributesMapper
import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   private class PersonAttributesMapper implements AttributesMapper<Person> {
      public Person mapFromAttributes(Attributes attrs) throws NamingException {
         Person person = new Person();
         person.setFullName((String)attrs.get("cn").get());
         person.setLastName((String)attrs.get("sn").get());
         person.setDescription((String)attrs.get("description").get());
         return person;
      }
   }

   public List<Person> getAllPersons() {
      return ldapClient.search()
            .query(query().where("objectclass").is("person"))
            .toList(new PersonAttributesMapper());
   }
}

LDAP 中的条目由其专有名称 (DN) 唯一标识。如果您有条目的 DN，则可以直接检索该条目，而无需对其进行查询。在 Java LDAP 中，这称为“查找”。以下示例显示了对 Person 对象的查找

示例 3. 查找导致 Person 对象的结果
public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public Person findPerson(String dn) {
      return ldapClient.search().name(dn).toObject(new PersonAttributesMapper());
   }
}

前面的示例查找指定的 DN，并将找到的属性传递给提供的 AttributesMapper — 在这种情况下，导致 Person 对象。

构建 LDAP 查询

LDAP 搜索涉及许多参数，包括以下内容

  • 基本 LDAP 路径：LDAP 树中搜索应从何处开始。

  • 搜索范围：LDAP 树中搜索应深入到什么程度。

  • 要返回的属性。

  • 搜索过滤器：在范围内选择元素时要使用的条件。

Spring LDAP 提供了一个 LdapQueryBuilder，它具有用于构建 LDAP 查询的流畅 API。

假设您希望从基本 DN dc=261consulting,dc=com 开始执行搜索，将返回的属性限制为 cn 和 sn，并使用过滤器 (&(objectclass=person)(sn=?))，其中我们希望 ? 被 lastName 参数的值替换。以下示例展示了如何使用 LdapQueryBuilder 执行此操作

示例 4. 动态构建搜索过滤器
import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public List<String> getPersonNamesByLastName(String lastName) {

      LdapQuery query = query()
         .base("dc=261consulting,dc=com")
         .attributes("cn", "sn")
         .where("objectclass").is("person")
         .and("sn").is(lastName);

      return ldapClient.search().query(query)
            .toObject((Attributes attrs) -> (String) attrs.get("cn").get());
   }
}
除了简化复杂搜索参数的构建之外，LdapQueryBuilder 及其关联类还提供了对搜索过滤器中任何不安全字符的正确转义。这可以防止“LDAP 注入”，其中用户可能会使用此类字符将不需要的操作注入到您的 LDAP 操作中。
LdapClient 包含许多用于执行 LDAP 搜索的重载方法。这是为了适应尽可能多的不同用例和编程风格偏好。对于绝大多数用例，建议使用将 LdapQuery 作为输入的方法。
AttributesMapper 只是在处理搜索和查找数据时可用的回调接口之一。有关替代方案，请参阅 使用 DirContextAdapter 简化属性访问和操作。

有关 LdapQueryBuilder 的更多信息，请参阅 高级 LDAP 查询。

动态构建可分辨名称

可分辨名称 (LdapName) 的标准 Java 实现，在解析可分辨名称时表现良好。然而，在实际使用中，此实现存在许多缺点

  • LdapName 实现是可变的，这对于表示标识的对象来说非常不合适。

  • 尽管其可变特性，但使用 LdapName 动态构建或修改可分辨名称的 API 却很繁琐。提取索引或（尤其是）命名组件的值也有些尴尬。

  • LdapName 上的许多操作都会抛出已检查异常，需要在错误通常是致命的并且无法以有意义的方式修复的情况下使用 try-catch 语句。

为了简化对可分辨名称的操作，Spring LDAP 提供了一个 LdapNameBuilder，以及 LdapUtils 中的许多实用方法，这些方法在使用 LdapName 时很有帮助。

示例

本节介绍前几节中涵盖的主题的几个示例。第一个示例使用 LdapNameBuilder 动态构建 LdapName

示例 5. 使用 LdapNameBuilder 动态构建 LdapName
import org.springframework.ldap.support.LdapNameBuilder;
import javax.naming.Name;

public class PersonRepoImpl implements PersonRepo {
  public static final String BASE_DN = "dc=example,dc=com";

  protected Name buildDn(Person p) {
    return LdapNameBuilder.newInstance(BASE_DN)
      .add("c", p.getCountry())
      .add("ou", p.getCompany())
      .add("cn", p.getFullname())
      .build();
  }
  ...
}

假设 Person 具有以下属性

属性名称 属性值

country

Sweden

company

Some Company

fullname

Some Person

然后，前述代码将生成以下专有名称

cn=Some Person, ou=Some Company, c=Sweden, dc=example, dc=com

以下示例使用 LdapUtils 从专有名称中提取值

示例 6. 使用 LdapUtils 从专有名称中提取值
import org.springframework.ldap.support.LdapNameBuilder;
import javax.naming.Name;
public class PersonRepoImpl implements PersonRepo {
...
  protected Person buildPerson(Name dn, Attributes attrs) {
    Person person = new Person();
    person.setCountry(LdapUtils.getStringValue(dn, "c"));
    person.setCompany(LdapUtils.getStringValue(dn, "ou"));
    person.setFullname(LdapUtils.getStringValue(dn, "cn"));
    // Populate rest of person object using attributes.

    return person;
  }
}

由于 1.4 及更早版本的 Java 版本根本不提供任何公共专有名称实现，因此 Spring LDAP 1.x 提供了自己的实现 DistinguishedName。此实现有几个自身的缺点，并且在版本 2.0 中已弃用。你现在应使用 LdapName 以及前面描述的实用程序。

绑定和解绑

本节介绍如何添加和删除数据。更新在 下一节 中介绍。

添加数据

在 Java LDAP 中插入数据称为绑定。这有点令人困惑，因为在 LDAP 术语中，“绑定”表示完全不同的含义。JNDI 绑定执行 LDAP 添加操作，将具有指定专有名称的新条目与一组属性关联起来。以下示例使用 LdapClient 添加数据

示例 7. 使用属性添加数据
public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public void create(Person p) {
      Name dn = buildDn(p);
      ldapClient.bind(dn).attributes(buildAttributes(p)).execute();
   }

   private Attributes buildAttributes(Person p) {
      Attributes attrs = new BasicAttributes();
      BasicAttribute ocattr = new BasicAttribute("objectclass");
      ocattr.add("top");
      ocattr.add("person");
      attrs.put(ocattr);
      attrs.put("cn", "Some Person");
      attrs.put("sn", "Person");
      return attrs;
   }
}

手动属性构建虽然枯燥且冗长，但足以满足许多目的。但是，你可以进一步简化绑定操作，如 使用 DirContextAdapter 简化属性访问和操作 中所述。

删除数据

在 Java LDAP 中删除数据称为解绑。JNDI 解绑执行 LDAP 删除操作，从 LDAP 树中删除与指定专有名称关联的条目。以下示例使用 LdapClient 删除数据

示例 8. 删除数据
public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public void delete(Person p) {
      Name dn = buildDn(p);
      ldapClient.unbind(dn).execute();
   }
}

更新

在 Java LDAP 中，可以通过两种方式修改数据：使用 rebind 或使用 modifyAttributes。

使用 Rebind 更新

rebind 是修改数据的粗略方法。它基本上是 unbind 后跟 bind。以下示例调用 LDAP 的 rebind

示例 9. 使用 rebind 修改
public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public void update(Person p) {
      Name dn = buildDn(p);
      ldapTemplate.bind(dn).attributes(buildAttributes(p)).replaceExisting(true).execute();
   }
}

使用 modifyAttributes 更新

修改数据的更复杂的方式是使用 modifyAttributes。此操作采用一个明确的属性修改数组，并对特定条目执行这些修改，如下所示

示例 10. 使用 modifyAttributes 进行修改
public class PersonRepoImpl implements PersonRepo {
   private LdapClient ldapClient;
   ...
   public void updateDescription(Person p) {
      Name dn = buildDn(p);
      Attribute attr = new BasicAttribute("description", p.getDescription())
      ModificationItem item = new ModificationItem(DirContext.REPLACE_ATTRIBUTE, attr);
      ldapTemplate.modify().name(dn).attributes(item).execute();
   }
}

构建 Attributes 和 ModificationItem 数组是一项繁重的工作。但是，正如我们在 使用 DirContextAdapter 简化属性访问和操作 中所述，Spring LDAP 提供了更多帮助来简化这些操作。