public final class VirtualListViewRequestControl extends Object implements Control
This control must be used in conjunction with the server-side sort request control in order to ensure that results are returned in a consistent order.
This control is similar to the simple paged results request control, except that it allows the client to move backwards and forwards in the result set.
The following example demonstrates use of the virtual list view controls.
ByteString contextID = ByteString.empty(); // Add a window of 2 entries on either side of the first sn=Jensen entry. SearchRequest request = Requests.newSearchRequest("ou=People,dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=*)", "sn", "givenName") .addControl(ServerSideSortRequestControl.newControl(true, new SortKey("sn"))) .addControl(VirtualListViewRequestControl.newAssertionControl( true, ByteString.valueOf("Jensen"), 2, 2, contextID)); SearchResultHandler resultHandler = new MySearchResultHandler(); Result result = connection.search(request, resultHandler); ServerSideSortResponseControl sssControl = result.getControl(ServerSideSortResponseControl.DECODER, new DecodeOptions()); if (sssControl != null && sssControl.getResult() == ResultCode.SUCCESS) { // Entries are sorted. } else { // Entries not necessarily sorted } VirtualListViewResponseControl vlvControl = result.getControl(VirtualListViewResponseControl.DECODER, new DecodeOptions()); // Position in list: vlvControl.getTargetPosition()/vlvControl.getContentCount()The search result handler in this case displays pages of results as LDIF on standard out.
private static class MySearchResultHandler implements SearchResultHandler { @Override public void handleExceptionResult(LdapException error) { // Ignore. } @Override public void handleResult(Result result) { // Ignore. } @Override public boolean handleEntry(SearchResultEntry entry) { final LDIFEntryWriter writer = new LDIFEntryWriter(System.out); try { writer.writeEntry(entry); writer.flush(); } catch (final IOException e) { // The writer could not write to System.out. } return true; } @Override public boolean handleReference(SearchResultReference reference) { System.out.println("Got a reference: " + reference.toString()); return false; } }
Modifier and Type | Field and Description |
---|---|
static ControlDecoder<VirtualListViewRequestControl> |
DECODER
A decoder which can be used for decoding the virtual list view request control.
|
static String |
OID
The OID for the virtual list view request control.
|
Modifier and Type | Method and Description |
---|---|
int |
getAfterCount()
Returns the number of entries after the target entry to be included in
the search results.
|
ByteString |
getAssertionValue()
Returns the assertion value that will be used to locate the target entry,
if applicable.
|
String |
getAssertionValueAsString()
Returns the assertion value that will be used to locate the target entry,
if applicable, decoded as a UTF-8 string.
|
int |
getBeforeCount()
Returns the number of entries before the target entry to be included in
the search results.
|
int |
getContentCount()
Returns the content count returned by the server in the last virtual list
view response, if applicable.
|
ByteString |
getContextId()
Returns the context ID provided by the server in the last virtual list
view response for the same set of criteria, or
null if there was
no previous virtual list view response or the server did not include a
context ID in the last response. |
int |
getOffset()
Returns the positional offset of the target entry in the result set, if
applicable, where
1 is the first entry. |
String |
getOid()
Returns the numeric OID associated with this control.
|
ByteString |
getValue()
Returns the value, if any, associated with this control.
|
boolean |
hasTargetOffset()
Returns
true if this control is using a target offset, or
false if this control is using a target assertion. |
boolean |
hasValue()
Returns
true if this control has a value. |
boolean |
isCritical()
Returns
true if it is unacceptable to perform the operation
without applying the semantics of this control. |
static VirtualListViewRequestControl |
newAssertionControl(boolean isCritical,
ByteString assertionValue,
int beforeCount,
int afterCount,
ByteString contextId)
Creates a new virtual list view request control that will identify the
target entry by an assertion value.
|
static VirtualListViewRequestControl |
newOffsetControl(boolean isCritical,
int offset,
int contentCount,
int beforeCount,
int afterCount,
ByteString contextId)
Creates a new virtual list view request control that will identify the
target entry by a positional offset within the complete result set.
|
String |
toString() |
public static final String OID
public static final ControlDecoder<VirtualListViewRequestControl> DECODER
public static VirtualListViewRequestControl newAssertionControl(boolean isCritical, ByteString assertionValue, int beforeCount, int afterCount, ByteString contextId)
isCritical
- true
if it is unacceptable to perform the operation
without applying the semantics of this control, or
false
if it can be ignored.assertionValue
- The assertion value that will be used to locate the target
entry.beforeCount
- The number of entries before the target entry to be included
in the search results.afterCount
- The number of entries after the target entry to be included in
the search results.contextId
- The context ID provided by the server in the last virtual list
view response for the same set of criteria, or null
if
there was no previous virtual list view response or the server
did not include a context ID in the last response.IllegalArgumentException
- If beforeCount
or afterCount
were less than
0
.NullPointerException
- If assertionValue
was null
.public static VirtualListViewRequestControl newOffsetControl(boolean isCritical, int offset, int contentCount, int beforeCount, int afterCount, ByteString contextId)
isCritical
- true
if it is unacceptable to perform the operation
without applying the semantics of this control, or
false
if it can be ignored.offset
- The positional offset of the target entry in the result set,
where 1
is the first entry.contentCount
- The content count returned by the server in the last virtual
list view response, or 0
if this is the first virtual
list view request.beforeCount
- The number of entries before the target entry to be included
in the search results.afterCount
- The number of entries after the target entry to be included in
the search results.contextId
- The context ID provided by the server in the last virtual list
view response for the same set of criteria, or null
if
there was no previous virtual list view response or the server
did not include a context ID in the last response.IllegalArgumentException
- If beforeCount
, afterCount
, or
contentCount
were less than 0
, or if
offset
was less than 1
.public int getAfterCount()
public ByteString getAssertionValue()
null
if this control is using a target offset.public String getAssertionValueAsString()
null
if this control is
using a target offset.public int getBeforeCount()
public int getContentCount()
0
if this is the first
virtual list view request, or -1
if this control is using
a target assertion.public ByteString getContextId()
null
if there was
no previous virtual list view response or the server did not include a
context ID in the last response.null
if unavailable.public int getOffset()
1
is the first entry.-1
if this control is using a target assertion.public String getOid()
Control
public ByteString getValue()
Control
public boolean hasTargetOffset()
true
if this control is using a target offset, or
false
if this control is using a target assertion.true
if this control is using a target offset, or
false
if this control is using a target assertion.public boolean hasValue()
Control
true
if this control has a value. In some circumstances
it may be useful to determine if a control has a value, without actually
calculating the value and incurring any performance costs.public boolean isCritical()
Control
true
if it is unacceptable to perform the operation
without applying the semantics of this control.
The criticality field only has meaning in controls attached to request
messages (except UnbindRequest). For controls attached to response
messages and the UnbindRequest, the criticality field SHOULD be
false
, and MUST be ignored by the receiving protocol peer. A
value of true
indicates that it is unacceptable to perform the
operation without applying the semantics of the control.
isCritical
in interface Control
true
if this control must be processed by the Directory
Server, or false
if it can be ignored.Copyright 2010-2022 ForgeRock AS.