基本用法

使用 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 中插入数据称为绑定（binding）。这有点令人困惑，因为在 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 中删除数据称为解绑定（unbinding）。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 提供了更多帮助来简化这些操作。