@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class SimplePagedResultsControl extends Control implements DecodeableControl
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:
ServerSideSortRequestControl to ensure
that the entries are sorted. This is not a requirement for the
simple paged results control.
// 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;
}
}
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
PAGED_RESULTS_OID
The OID (1.2.840.113556.1.4.319) for the paged results control.
|
| Constructor and Description |
|---|
SimplePagedResultsControl(int pageSize)
Creates a new paged results control with the specified page size.
|
SimplePagedResultsControl(int pageSize,
ASN1OctetString cookie)
Creates a new paged results control with the specified page size and the
provided cookie.
|
SimplePagedResultsControl(int pageSize,
ASN1OctetString cookie,
boolean isCritical)
Creates a new paged results control with the specified page size and the
provided cookie.
|
SimplePagedResultsControl(int pageSize,
boolean isCritical)
Creates a new paged results control with the specified page size.
|
SimplePagedResultsControl(java.lang.String oid,
boolean isCritical,
ASN1OctetString value)
Creates a new paged results control from the control with the provided set
of information.
|
| Modifier and Type | Method and Description |
|---|---|
SimplePagedResultsControl |
decodeControl(java.lang.String oid,
boolean isCritical,
ASN1OctetString value)
Creates a new instance of this decodeable control from the provided
information.
|
static SimplePagedResultsControl |
decodeJSONControl(JSONObject controlObject,
boolean strict)
Attempts to decode the provided object as a JSON representation of a
simple paged results control.
|
static SimplePagedResultsControl |
get(SearchResult result)
Extracts a simple paged results response control from the provided result.
|
java.lang.String |
getControlName()
Retrieves the user-friendly name for this control, if available.
|
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.
|
int |
getSize()
Retrieves the size for this paged results control.
|
boolean |
moreResultsToReturn()
Indicates whether there are more results to return as part of this search.
|
JSONObject |
toJSONControl()
Retrieves a representation of this simple paged results control as a JSON
object.
|
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided
buffer.
|
decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo@NotNull public static final java.lang.String PAGED_RESULTS_OID
public SimplePagedResultsControl(int pageSize)
pageSize - The maximum number of entries that the server should
return in the first page.public SimplePagedResultsControl(int pageSize, boolean isCritical)
pageSize - The maximum number of entries that the server should
return in the first page.isCritical - Indicates whether this control should be marked
critical.public SimplePagedResultsControl(int pageSize, @Nullable ASN1OctetString cookie)
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.public SimplePagedResultsControl(int pageSize, @Nullable ASN1OctetString cookie, boolean isCritical)
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.public SimplePagedResultsControl(@NotNull java.lang.String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
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.LDAPException - If the provided control cannot be decoded as a
simple paged results control.@NotNull public SimplePagedResultsControl decodeControl(@NotNull java.lang.String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
decodeControl in interface DecodeableControloid - 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.LDAPException - If the provided information cannot be decoded as a
valid instance of this decodeable control.@Nullable public static SimplePagedResultsControl get(@NotNull SearchResult result) throws LDAPException
result - The result from which to retrieve the simple paged results
response control.null if the result did not contain a
simple paged results response control.LDAPException - If a problem is encountered while attempting to
decode the simple paged results response control
contained in the provided result.public int getSize()
@NotNull public ASN1OctetString getCookie()
public boolean moreResultsToReturn()
true if there are more results to return, or
false if not.@NotNull public java.lang.String getControlName()
getControlName in class Control@NotNull public JSONObject toJSONControl()
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.
toJSONControl in class Control@NotNull public static SimplePagedResultsControl decodeJSONControl(@NotNull JSONObject controlObject, boolean strict) throws LDAPException
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.LDAPException - If the provided JSON object cannot be parsed as a
valid simple paged results control.