Package com.unboundid.ldap.sdk.controls

Class SimplePagedResultsControl

java.lang.Object
com.unboundid.ldap.sdk.Control
com.unboundid.ldap.sdk.controls.SimplePagedResultsControl
All Implemented Interfaces:
DecodeableControl, Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class SimplePagedResultsControl extends Control implements DecodeableControl
This class provides an implementation of the simple paged results control as defined in RFC 2696. It allows the client to iterate through a potentially large set of search results in subsets of a specified number of entries (i.e., "pages").

The same control encoding is used for both the request control sent by clients and the response control returned by the server. It may contain two elements:
  • Size -- In a request control, this provides the requested page size, which is the maximum number of entries that the server should return in the next iteration of the search. In a response control, it is an estimate of the total number of entries that match the search criteria.
  • Cookie -- A token which is used by the server to keep track of its position in the set of search results. The first request sent by the client should not include a cookie, and the last response sent by the server should not include a cookie. For all other intermediate search requests and responses, the server will include a cookie value in its response that the client should include in its next request.
When the client wishes to use the paged results control, the first search request should include a version of the paged results request control that was created with a requested page size but no cookie. The corresponding response from the server will include a version of the paged results control that may include an estimate of the total number of matching entries, and may also include a cookie. The client should include this cookie in the next request (with the same set of search criteria) to retrieve the next page of results. This process should continue until the response control returned by the server does not include a cookie, which indicates that the end of the result set has been reached.

Note that the simple paged results control is similar to the VirtualListViewRequestControl in that both allow the client to request that only a portion of the result set be returned at any one time. However, there are significant differences between them, including:
  • In order to use the virtual list view request control, it is also necessary to use the ServerSideSortRequestControl to ensure that the entries are sorted. This is not a requirement for the simple paged results control.
  • The simple paged results control may only be used to iterate sequentially through the set of search results. The virtual list view control can retrieve pages out of order, can retrieve overlapping pages, and can re-request pages that it had already retrieved.

Example

The following example demonstrates the use of the simple paged results control. It will iterate through all users, retrieving up to 10 entries at a time: 
 // Perform a search to retrieve all users in the server, but only retrieving
 // ten at a time.
 int numSearches = 0;
 int totalEntriesReturned = 0;
 SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
      SearchScope.SUB, Filter.createEqualityFilter("objectClass", "person"));
 ASN1OctetString resumeCookie = null;
 while (true)
 {
   searchRequest.setControls(
        new SimplePagedResultsControl(10, resumeCookie));
   SearchResult searchResult = connection.search(searchRequest);
   numSearches++;
   totalEntriesReturned += searchResult.getEntryCount();
   for (SearchResultEntry e : searchResult.getSearchEntries())
   {
     // Do something with each entry...
   }

   LDAPTestUtils.assertHasControl(searchResult,
        SimplePagedResultsControl.PAGED_RESULTS_OID);
   SimplePagedResultsControl responseControl =
        SimplePagedResultsControl.get(searchResult);
   if (responseControl.moreResultsToReturn())
   {
     // The resume cookie can be included in the simple paged results
     // control included in the next search to get the next page of results.
     resumeCookie = responseControl.getCookie();
   }
   else
   {
     break;
   }
 }
See Also:

  • Field Details

  • Constructor Details

    • SimplePagedResultsControl

      public SimplePagedResultsControl(int pageSize)
      Creates a new paged results control with the specified page size. This version of the constructor should only be used when creating the first search as part of the set of paged results. Subsequent searches to retrieve additional pages should use the response control returned by the server in their next request, until the response control returned by the server does not include a cookie.
      Parameters:
      pageSize - The maximum number of entries that the server should return in the first page.

    • SimplePagedResultsControl

      public SimplePagedResultsControl(int pageSize, boolean isCritical)
      Creates a new paged results control with the specified page size. This version of the constructor should only be used when creating the first search as part of the set of paged results. Subsequent searches to retrieve additional pages should use the response control returned by the server in their next request, until the response control returned by the server does not include a cookie.
      Parameters:
      pageSize - The maximum number of entries that the server should return in the first page.
      isCritical - Indicates whether this control should be marked critical.

    • SimplePagedResultsControl

      public SimplePagedResultsControl(int pageSize, @Nullable ASN1OctetString cookie)
      Creates a new paged results control with the specified page size and the provided cookie. This version of the constructor should be used to continue iterating through an existing set of results, but potentially using a different page size.
      Parameters:
      pageSize - The maximum number of entries that the server should return in the next page of the results.
      cookie - The cookie provided by the server after returning the previous page of results, or null if this request will retrieve the first page of results.

    • SimplePagedResultsControl

      public SimplePagedResultsControl(int pageSize, @Nullable ASN1OctetString cookie, boolean isCritical)
      Creates a new paged results control with the specified page size and the provided cookie. This version of the constructor should be used to continue iterating through an existing set of results, but potentially using a different page size.
      Parameters:
      pageSize - The maximum number of entries that the server should return in the first page.
      cookie - The cookie provided by the server after returning the previous page of results, or null if this request will retrieve the first page of results.
      isCritical - Indicates whether this control should be marked critical.

    • SimplePagedResultsControl

      public SimplePagedResultsControl(@NotNull String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
      Creates a new paged results control from the control with the provided set of information. This should be used to decode the paged results response control returned by the server with a page of results.
      Parameters:
      oid - The OID for the control.
      isCritical - Indicates whether the control should be marked critical.
      value - The encoded value for the control. This may be null if no value was provided.
      Throws:
      LDAPException - If the provided control cannot be decoded as a simple paged results control.

  • Method Details

    • decodeControl

      @NotNull public SimplePagedResultsControl decodeControl(@NotNull String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
      Creates a new instance of this decodeable control from the provided information.
      Specified by:
      decodeControl in interface DecodeableControl
      Parameters:
      oid - The OID for the control.
      isCritical - Indicates whether the control should be marked critical.
      value - The encoded value for the control. This may be null if no value was provided.
      Returns:
      The decoded representation of this control.
      Throws:
      LDAPException - If the provided information cannot be decoded as a valid instance of this decodeable control.

    • get

      @Nullable public static SimplePagedResultsControl get(@NotNull SearchResult result) throws LDAPException
      Extracts a simple paged results response control from the provided result.
      Parameters:
      result - The result from which to retrieve the simple paged results response control.
      Returns:
      The simple paged results response control contained in the provided result, or null if the result did not contain a simple paged results response control.
      Throws:
      LDAPException - If a problem is encountered while attempting to decode the simple paged results response control contained in the provided result.

    • getSize

      public int getSize()
      Retrieves the size for this paged results control. For a request control, it may be used to specify the number of entries that should be included in the next page of results. For a response control, it may be used to specify the estimated number of entries in the complete result set.
      Returns:
      The size for this paged results control.

    • getCookie

      @NotNull public ASN1OctetString getCookie()
      Retrieves the cookie for this control, which may be used in a subsequent request to resume reading entries from the next page of results. The value should have a length of zero when used to retrieve the first page of results for a given search, and also in the response from the server when there are no more entries to send. It should be non-empty for all other conditions.
      Returns:
      The cookie for this control, or an empty cookie (with a value length of zero) if there is none.

    • moreResultsToReturn

      public boolean moreResultsToReturn()
      Indicates whether there are more results to return as part of this search.
      Returns:
      true if there are more results to return, or false if not.

    • getControlName

      @NotNull public String getControlName()
      Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.
      Overrides:
      getControlName in class Control
      Returns:
      The user-friendly name for this control, or the OID if no user-friendly name is available.

    • toJSONControl

      @NotNull public JSONObject toJSONControl()
      Retrieves a representation of this simple paged results control as a JSON object. The JSON object uses the following fields:
      • oid -- A mandatory string field whose value is the object identifier for this control. For the simple paged results control, the OID is "1.2.840.113556.1.4.319".
      • control-name -- An optional string field whose value is a human-readable name for this control. This field is only intended for descriptive purposes, and when decoding a control, the oid field should be used to identify the type of control.
      • criticality -- A mandatory Boolean field used to indicate whether this control is considered critical.
      • value-base64 -- An optional string field whose value is a base64-encoded representation of the raw value for this simple paged results control. Exactly one of the value-base64 and value-json fields must be present.
      • value-json -- An optional JSON object field whose value is a user-friendly representation of the value for this simple paged results control. Exactly one of the value-base64 and value-json fields must be present, and if the value-json field is used, then it will use the following fields:
        • size -- A mandatory integer field. When used in a request control, this represents the maximum number of entries that should be returned in the next page of results. When used in a response control, it provides an estimate of the total number of entries across all pages of the result set.
        • cookie -- An optional string field. When used in a request control, this should be empty when requesting the first page of results, and the value of the cookie field returned in the response control from the previous page of results. For a response control, this will be non-empty for all pages except the last page of results. The cookie value used in the JSON representation of the control will be a base64-encoded representation of the raw cookie value that would be used in the LDAP representation of the control, and it must be treated as an opaque blob by the client.
      Overrides:
      toJSONControl in class Control
      Returns:
      A JSON object that contains a representation of this control.

    • decodeJSONControl

      @NotNull public static SimplePagedResultsControl decodeJSONControl(@NotNull JSONObject controlObject, boolean strict) throws LDAPException
      Attempts to decode the provided object as a JSON representation of a simple paged results control.
      Parameters:
      controlObject - The JSON object to be decoded. It must not be null.
      strict - Indicates whether to use strict mode when decoding the provided JSON object. If this is true, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this is false, then unrecognized fields will be ignored.
      Returns:
      The simple paged results control that was decoded from the provided JSON object.
      Throws:
      LDAPException - If the provided JSON object cannot be parsed as a valid simple paged results control.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this LDAP control to the provided buffer.
      Overrides:
      toString in class Control
      Parameters:
      buffer - The buffer to which to append the string representation of this buffer.