@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class VirtualListViewRequestControl extends Control
SimplePagedResultsControl, with
the exception that the simple paged results control requires scrolling
through the results in sequential order, while the VLV control allows
starting and resuming at any arbitrary point in the result set. The starting
point may be specified using either a positional offset, or based on the
first entry with a value that is greater than or equal to a specified value.
targetOffset -- The position in the result set of the entry to
target for the next page of results to return. Note that the offset is
one-based (so the first entry has offset 1, the second entry has offset
2, etc.).beforeCount -- The number of entries before the entry specified
as the target offset that should be retrieved.afterCount -- The number of entries after the entry specified
as the target offset that should be retrieved.contentCount -- The estimated total number of entries that
are in the total result set. This should be zero for the first request
in a VLV search sequence, but should be the value returned by the
server in the corresponding response control for subsequent searches as
part of the VLV sequence.contextID -- This is an optional cookie that may be used to
help the server resume processing on a VLV search. It should be absent
from the initial request, but for subsequent requests should be the
value returned in the previous VLV response control.assertionValue -- The value that specifies the start of the
page of results to retrieve. The target entry will be the first entry
in which the value for the primary sort attribute is greater than or
equal to this assertion value.beforeCount -- The number of entries before the entry specified
by the assertion value that should be retrieved.afterCount -- The number of entries after the entry specified
by the assertion value that should be retrieved.contextID -- This is an optional cookie that may be used to
help the server resume processing on a VLV search. It should be absent
from the initial request, but for subsequent requests should be the
value returned in the previous VLV response control.ServerSideSortRequestControl. This is necessary to ensure that a
consistent order is used for the resulting entries.
VirtualListViewResponseControl to provide information about the
state of the virtual list view processing.
// Perform a search to retrieve all users in the server, but only retrieving
// ten at a time. Ensure that the users are sorted in ascending order by
// last name, then first name.
int numSearches = 0;
int totalEntriesReturned = 0;
SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
SearchScope.SUB, Filter.createEqualityFilter("objectClass", "person"));
int vlvOffset = 1;
int vlvContentCount = 0;
ASN1OctetString vlvContextID = null;
while (true)
{
// Note that the VLV control always requires the server-side sort
// control.
searchRequest.setControls(
new ServerSideSortRequestControl(new SortKey("sn"),
new SortKey("givenName")),
new VirtualListViewRequestControl(vlvOffset, 0, 9, vlvContentCount,
vlvContextID));
SearchResult searchResult = connection.search(searchRequest);
numSearches++;
totalEntriesReturned += searchResult.getEntryCount();
for (SearchResultEntry e : searchResult.getSearchEntries())
{
// Do something with each entry...
}
LDAPTestUtils.assertHasControl(searchResult,
VirtualListViewResponseControl.VIRTUAL_LIST_VIEW_RESPONSE_OID);
VirtualListViewResponseControl vlvResponseControl =
VirtualListViewResponseControl.get(searchResult);
vlvContentCount = vlvResponseControl.getContentCount();
vlvOffset += 10;
vlvContextID = vlvResponseControl.getContextID();
if (vlvOffset > vlvContentCount)
{
break;
}
}
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
VIRTUAL_LIST_VIEW_REQUEST_OID
The OID (2.16.840.1.113730.3.4.9) for the virtual list view request
control.
|
| Constructor and Description |
|---|
VirtualListViewRequestControl(ASN1OctetString assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
VirtualListViewRequestControl(ASN1OctetString assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID,
boolean isCritical)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
VirtualListViewRequestControl(byte[] assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
VirtualListViewRequestControl(byte[] assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID,
boolean isCritical)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
VirtualListViewRequestControl(Control control)
Creates a new virtual list view request control which is decoded from the
provided generic control.
|
VirtualListViewRequestControl(int targetOffset,
int beforeCount,
int afterCount,
int contentCount,
ASN1OctetString contextID)
Creates a new virtual list view request control that will identify the
beginning of the result set by a target offset.
|
VirtualListViewRequestControl(int targetOffset,
int beforeCount,
int afterCount,
int contentCount,
ASN1OctetString contextID,
boolean isCritical)
Creates a new virtual list view request control that will identify the
beginning of the result set by a target offset.
|
VirtualListViewRequestControl(java.lang.String assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
VirtualListViewRequestControl(java.lang.String assertionValue,
int beforeCount,
int afterCount,
ASN1OctetString contextID,
boolean isCritical)
Creates a new virtual list view request control that will identify the
beginning of the result set by an assertion value.
|
| Modifier and Type | Method and Description |
|---|---|
static VirtualListViewRequestControl |
decodeJSONControl(JSONObject controlObject,
boolean strict)
Attempts to decode the provided object as a JSON representation of a
virtual list view request control.
|
int |
getAfterCount()
Retrieves the number of entries that should be retrieved after the target
entry.
|
ASN1OctetString |
getAssertionValue()
Retrieves the assertion value for this virtual list view request control,
if applicable.
|
byte[] |
getAssertionValueBytes()
Retrieves the byte array representation of the assertion value for this
virtual list view request control, if applicable.
|
java.lang.String |
getAssertionValueString()
Retrieves the string representation of the assertion value for this virtual
list view request control, if applicable.
|
int |
getBeforeCount()
Retrieves the number of entries that should be retrieved before the target
entry.
|
int |
getContentCount()
Retrieves the estimated number of entries in the result set, if applicable.
|
ASN1OctetString |
getContextID()
Retrieves the context ID for this virtual list view request control, if
available.
|
java.lang.String |
getControlName()
Retrieves the user-friendly name for this control, if available.
|
int |
getTargetOffset()
Retrieves the target offset position for this virtual list view request
control, if applicable.
|
JSONObject |
toJSONControl()
Retrieves a representation of this virtual list view request 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 VIRTUAL_LIST_VIEW_REQUEST_OID
public VirtualListViewRequestControl(int targetOffset, int beforeCount, int afterCount, int contentCount, @Nullable ASN1OctetString contextID)
targetOffset - The position of the entry that should be used as the
start of the result set.beforeCount - The maximum number of entries that should be returned
before the entry with the specified target offset.afterCount - The maximum number of entries that should be returned
after the entry with the specified target offset.contentCount - The estimated number of entries in the result set.
For the first request in a series of searches with
the VLV control, it should be zero. For subsequent
searches in the VLV sequence, it should be the
content count included in the response control from
the previous search.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from the
previous search.public VirtualListViewRequestControl(@NotNull java.lang.String assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.public VirtualListViewRequestControl(@NotNull byte[] assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.public VirtualListViewRequestControl(@NotNull ASN1OctetString assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.public VirtualListViewRequestControl(int targetOffset, int beforeCount, int afterCount, int contentCount, @Nullable ASN1OctetString contextID, boolean isCritical)
targetOffset - The position of the entry that should be used as the
start of the result set.beforeCount - The maximum number of entries that should be returned
before the entry with the specified target offset.afterCount - The maximum number of entries that should be returned
after the entry with the specified target offset.contentCount - The estimated number of entries in the result set.
For the first request in a series of searches with
the VLV control, it should be zero. For subsequent
searches in the VLV sequence, it should be the
content count included in the response control from
the previous search.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from the
previous search.isCritical - Indicates whether this control should be marked
critical.public VirtualListViewRequestControl(@NotNull java.lang.String assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID, boolean isCritical)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.isCritical - Indicates whether this control should be marked
critical.public VirtualListViewRequestControl(@NotNull byte[] assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID, boolean isCritical)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.isCritical - Indicates whether this control should be marked
critical.public VirtualListViewRequestControl(@NotNull ASN1OctetString assertionValue, int beforeCount, int afterCount, @Nullable ASN1OctetString contextID, boolean isCritical)
assertionValue - The assertion value that will be used to identify
the start of the result set. The target entry will
be the first entry with a value for the primary
sort attribute that is greater than or equal to
this assertion value. It must not be null.beforeCount - The maximum number of entries that should be
returned before the first entry with a value
greater than or equal to the provided assertion
value.afterCount - The maximum number of entries that should be
returned after the first entry with a value
greater than or equal to the provided assertion
value.contextID - The context ID that may be used to help the server
continue in the same result set for subsequent
searches. For the first request in a series of
searches with the VLV control, it should be
null. For subsequent searches in the VLV
sequence, it should be the (possibly null)
context ID included in the response control from
the previous search.isCritical - Indicates whether this control should be marked
critical.public VirtualListViewRequestControl(@NotNull Control control) throws LDAPException
control - The generic control to be decoded as a virtual list view
request control.LDAPException - If the provided control cannot be decoded as a
virtual list view request control.public int getTargetOffset()
@Nullable public java.lang.String getAssertionValueString()
null if the target is
specified by offset.@Nullable public byte[] getAssertionValueBytes()
null if the target
is specified by offset.@Nullable public ASN1OctetString getAssertionValue()
null if the target is specified by offset.public int getBeforeCount()
public int getAfterCount()
public int getContentCount()
@Nullable public ASN1OctetString getContextID()
null if there is none.@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 virtual list view request
control, the OID is "2.16.840.1.113730.3.4.9".
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 virtual list
view request 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 virtual list view
request 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:
target-offset -- An optional integer field whose value is
the offset of the target entry within the result set, with the
first entry in the result set having an offset value of one.
Exactly one of the target-offset and
assertion-value fields must be provided.
assertion-value -- An optional string field that indicates
that the target entry should be the first one in the result set in
which the value of the primary sort attribute is greater than or
equal to the provided assertion value. Exactly one of the
target-offset and assertion-value fields must be
provided.
before-count -- A mandatory integer field whose value is
the maximum number of entries before the target entry that should
be included in the page of results to return.
after-count -- A mandatory integer field whose value is
the maximum number of entries after the target entry that should
be included in the page of results to return.
content-count -- An optional integer field that represents
the estimated number of entries in the entire result set. This
field may only be present when the target-offset field is
also provided, and its value may be absent or zero when retrieving
the first page of results, and it should be the
content-count value returned in the previous virtual list
view response control for all subsequent pages.
context-id -- An optional string field that represents an
opaque cookie that may be used to help the server continue a series
of searches using the virtual list view request control. For the
first search in a series, this should be absent. For all
subsequent requests in the series, it should be the
context-id value (if any) included in the response control
from the previous page of the series. The context ID 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 VirtualListViewRequestControl 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 virtual list view request control.