Download the JDK
Search the Tutorials
Hide the TOC
Trail: Java Naming and Directory Interface(TM).
Lesson: New features in JDK 5.0 and JDK 6
New features in JDK 5.0 and JDK 6
Retrieving Distinguished Name
Standard LDAP Controls
Paged Results Control
Sort Control
Manage Referral Control
Manipulating LdapName (Distinguished Name)
Manipulating Relative Distringuished Name (RDN)
Setting Timeout for Ldap Operations
Home Page > Java Naming and Directory Interface(TM). > New features in JDK 5.0 and JDK 6
Paged Results Control

> #### BasicControl

> The `javax.naming.ldap.BasicControl` which implements the `javax.naming.ldap.Control` serves as a base implementation for extending other controls.

> #### Paged Results Control

> The paged results control is useful for LDAP clients which want to receive search results in a controlled manner limited by the page size. The page size can be configured by the client as per the availability of its resources, like bandwidth and the processing capability.

> The server uses a cookie (similar to the HTTP session cookie mechanism) to maintain the state of the search requests in order to track the results being sent to the client. The paged results control is specified in RFC 2696. The classes below provide the functionality required to support paged results control.

> - `javax.naming.ldap.PagedResultsControl`
> - `javax.naming.ldap.PagedResultsResponseControl`

> ##### How to use Paged Results Control?

> The example below illustrates the client-server interaction between a client doing a search requesting a page size limit of 5. The entire result set returned by the server contains 21 entries.
> 1. Client sends a search request asking for paged results with a page size of 5.

>           <blackquote>
>            // Activate paged results
>             int pageSize = 5; // 5 entries per page
>             byte[] cookie = null;
>             int total;
>             ctx.setRequestControls(new Control[]{
>                 new PagedResultsControl(pageSize, Control.CRITICAL) });
>             // Perform the search
>             NamingEnumeration results =
>                 ctx.search("", "(objectclass=*)", new SearchControls());
>            </blackquote>

> 2. The server responds with entries plus an indication of 21 total entries in the search result and an opaque cookie to be used by the client when retrieving subsequent pages.

>           <blackquote>
>           // Iterate over a batch of search results sent by the server
>                 while (results != null && results.hasMore()) {
>                     // Display an entry
>                     SearchResult entry = (SearchResult)results.next();
>                     System.out.println(entry.getName());

>                     // Handle the entry's response controls (if any)
>                     if (entry instanceof HasControls) {
>                         // ((HasControls)entry).getControls();
>                     }
>                 }
>           // Examine the paged results control response
>                 Control[] controls = ctx.getResponseControls();
>                 if (controls != null) {
>                     for (int i = 0; i < controls.length; i++) {
>                         if (controls[i] instanceof PagedResultsResponseControl) {
>                             PagedResultsResponseControl prrc =
>                                 (PagedResultsResponseControl)controls[i];
>                             total = prrc.getResultSize();
>                             cookie = prrc.getCookie();
>                         } else {
>                             // Handle other response controls (if any)
>                         }
>                     }
>                 }
>            </blackquote>

> 3. Client sends an identical search request, returning the opaque cookie, asking for the next page.

>           <blackquote>
>          // Re-activate paged results
>                 ctx.setRequestControls(new Control[]{
>                     new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });

>    </blackquote>
> 4. Server responds with five entries plus an indication that there are more entries The client repeats the search performed in step 4 until a null cookie is returned by the server, which indicates no more entries to be sent by the server.

> The complete JNDI example can be found here.

> Note: The Paged Search Control is supported by the Windows Active Directory Server. It's not supported by the Sun Java Directory Server version 5.2

Previous page: Standard LDAP Controls
Next page: Sort Control