Processing the DirContext

本部分介绍如何处理 DirContext，包括预处理和后处理。

This section covers how to process the DirContext, including pre- and post-processing.

Custom DirContext Pre- and Post-processing

在某些情况下，您可能希望在搜索操作之前和之后对 DirContext 执行操作。用于此操作的接口称为 DirContextProcessor。以下列表显示了 DirContextProcessor 接口：

In some situations, you might like to perform operations on the DirContext before and after the search operation. The interface that is used for this is called DirContextProcessor. The following listing shows the DirContextProcessor interface:

public interface DirContextProcessor {
   public void preProcess(DirContext ctx) throws NamingException;
   public void postProcess(DirContext ctx) throws NamingException;
}

LdapTemplate 类具有一个搜索方法，该方法采用 DirContextProcessor，如下所示：

The LdapTemplate class has a search method that takes a DirContextProcessor, as follows:

public void search(SearchExecutor se, NameClassPairCallbackHandler handler,
   DirContextProcessor processor) throws DataAccessException;

在搜索操作之前，将对给定的 DirContextProcessor 实例调用 preProcess 方法。在搜索运行且生成的结果 NamingEnumeration 被处理后，将调用 postProcess 方法。这允许您对将用于搜索的 DirContext 执行操作，并在搜索执行后检查 DirContext。这可能非常有用（例如，在处理请求和响应控件时）。

Before the search operation, the preProcess method is called on the given DirContextProcessor instance. After the search has run and the resulting NamingEnumeration has been processed, the postProcess method is called. This lets you perform operations on the DirContext to be used in the search and to check the DirContext when the search has been performed. This can be very useful (for example, when handling request and response controls).

当您不需要自定义 SearchExecutor 时，还可以使用以下便捷方法：

You can also use the following convenience methods when you do not need a custom SearchExecutor:

public void search(Name base, String filter,
   SearchControls controls, NameClassPairCallbackHandler handler, DirContextProcessor processor)

public void search(String base, String filter,
   SearchControls controls, NameClassPairCallbackHandler handler, DirContextProcessor processor)

public void search(Name base, String filter,
   SearchControls controls, AttributesMapper mapper, DirContextProcessor processor)

public void search(String base, String filter,
   SearchControls controls, AttributesMapper mapper, DirContextProcessor processor)

public void search(Name base, String filter,
   SearchControls controls, ContextMapper mapper, DirContextProcessor processor)

public void search(String base, String filter,
   SearchControls controls, ContextMapper mapper, DirContextProcessor processor)

Implementing a Request Control DirContextProcessor

LDAPv3 协议使用“Controls`" 发送和接收额外的用于影响预定义操作的行为的数据。为了简化请求控制 `DirContextProcessor 的实现，Spring LDAP 提供了 AbstractRequestControlDirContextProcessor 基本类。此类处理从 LdapContext 检索当前的请求控制，调用模板方法创建请求控制并将其添加到 LdapContext。您需要在子类中做的是实现用于执行搜索后所需操作的模板方法 createRequestControl 和 postProcess 方法。以下列表显示了相关签名：

The LDAPv3 protocol uses “Controls” to send and receive additional data to affect the behavior of predefined operations. To simplify the implementation of a request control DirContextProcessor, Spring LDAP provides the AbstractRequestControlDirContextProcessor base class. This class handles the retrieval of the current request controls from the LdapContext, calls a template method for creating a request control, and adds it to the LdapContext. All you have to do in the subclass is to implement the template method called createRequestControl and the postProcess method for performing whatever you need to do after the search. The following listing shows the relevant signatures:

public abstract class AbstractRequestControlDirContextProcessor implements
      DirContextProcessor {

   public void preProcess(DirContext ctx) throws NamingException {
      ...
   }

   public abstract Control createRequestControl();
}

典型的 DirContextProcessor 类似于以下示例：

A typical DirContextProcessor is similar to the following example:

Example 1. A request control DirContextProcessor implementation
public class MyCoolRequestControl extends AbstractRequestControlDirContextProcessor {
   private static final boolean CRITICAL_CONTROL = true;
   private MyCoolCookie cookie;
   ...
   public MyCoolCookie getCookie() {
      return cookie;
   }

   public Control createRequestControl() {
      return new SomeCoolControl(cookie.getCookie(), CRITICAL_CONTROL);
   }

   public void postProcess(DirContext ctx) throws NamingException {
      LdapContext ldapContext = (LdapContext) ctx;
      Control[] responseControls = ldapContext.getResponseControls();

      for (int i = 0; i < responseControls.length; i++) {
         if (responseControls[i] instanceof SomeCoolResponseControl) {
            SomeCoolResponseControl control = (SomeCoolResponseControl) responseControls[i];
            this.cookie = new MyCoolCookie(control.getCookie());
         }
      }
   }
}

使用控件时确保使用 LdapContextSource。 Control 接口适用于 LDAPv3，并且要求使用 LdapContext 而不是 DirContext。如果用非 LdapContext 的参数调用 AbstractRequestControlDirContextProcessor 子类，它会抛出一个 IllegalArgumentException。

Make sure you use LdapContextSource when you use controls. The Control interface is specific for LDAPv3 and requires that LdapContext is used instead of DirContext. If an AbstractRequestControlDirContextProcessor subclass is called with an argument that is not an LdapContext, it throws an IllegalArgumentException.

Paged Search Results

某些搜索可能返回大量的结果。如果没有简单的方法过滤出少量结果，则服务器每次调用只返回一定数量的结果将非常方便。这被称为“分步搜索结果”。然后可以显示结果的每个“页面”，并链接到下一页和上一页。如果没有此功能，客户端必须手动将搜索结果限制为页面或检索整个结果，然后将其分解为合适大小的页面。前者相当复杂，而后者将消耗不必要的内存量。

Some searches may return large numbers of results. When there is no easy way to filter out a smaller amount, it is convenient to have the server return only a certain number of results each time it is called. This is known as “paged search results”. Each “page” of the result could then be displayed, with links to the next and previous page. Without this functionality, the client must either manually limit the search result into pages or retrieve the whole result and then chop it into pages of suitable size. The former would be rather complicated, and the latter would consume unnecessary amounts of memory.

某些 LDAP 服务器支持 PagedResultsControl，它请求 LDAP 服务器返回指定大小的页面中的搜索操作结果。用户通过控制调用的频率来控制返回页面的速率。但是，您必须跟踪调用之间的 cookie。服务器使用此 cookie 跟踪上一次使用分步结果请求调用时停止的位置。

Some LDAP servers support PagedResultsControl, which requests that the results of a search operation are returned by the LDAP server in pages of a specified size. The user controls the rate at which the pages are returned, by controlling the rate at which the searches are called. However, you must keep track of a cookie between the calls. The server uses this cookie to keep track of where it left off the previous time it was called with a paged results request.

Spring LDAP 使用前面部分讨论的概念对分步上下文进行预处理和后处理，从而提供对分步结果的支持。它通过使用 PagedResultsDirContextProcessor 类来实现。PagedResultsDirContextProcessor 类使用所请求的页面大小创建一个 PagedResultsControl 并将其添加到 LdapContext。在搜索之后，它获取 PagedResultsResponseControl 并检索分步结果 cookie，这对于在连续的分步结果请求之间保持上下文是必需的。

Spring LDAP provides support for paged results by using the concept for pre- and post-processing of an LdapContext, as discussed in the previous sections. It does so by using the PagedResultsDirContextProcessor class. The PagedResultsDirContextProcessor class creates a PagedResultsControl with the requested page size and adds it to the LdapContext. After the search, it gets the PagedResultsResponseControl and retrieves the paged results cookie, which is needed to keep the context between consecutive paged results requests.

以下示例显示如何使用分步搜索结果功能：

The following example shows how the to use the paged search results functionality:

Example 2. Paged results using PagedResultsDirContextProcessor
public List<String> getAllPersonNames() {
  final SearchControls searchControls = new SearchControls();
  searchControls.setSearchScope(SearchControls.SUBTREE_SCOPE);

  final PagedResultsDirContextProcessor processor =
        new PagedResultsDirContextProcessor(PAGE_SIZE);

  return SingleContextSource.doWithSingleContext(
        contextSource, new LdapOperationsCallback<List<String>>() {

      @Override
      public List<String> doWithLdapOperations(LdapOperations operations) {
        List<String> result = new LinkedList<String>();

        do {
          List<String> oneResult = operations.search(
            "ou=People",
            "(&(objectclass=person))",
            searchControls,
            CN_ATTRIBUTES_MAPPER,
            processor);
          result.addAll(oneResult);
        } while(processor.hasMore());

        return result;
      }
  });
}

为了让分页结果 cookie 继续有效，您必须为每次分页结果调用使用相同的底层连接。您可以通过使用 SingleContextSource 来做到这一点，如前面的示例中所示。

For a paged results cookie to continue being valid, you must use the same underlying connection for each paged results call. You can do so by using the SingleContextSource, as demonstrated in the preceding example.