Package org.forgerock.opendj.ldap.controls

Class VirtualListViewRequestControl

java.lang.Object
org.forgerock.opendj.ldap.controls.VirtualListViewRequestControl
All Implemented Interfaces:
Control
public final class VirtualListViewRequestControl extends Object implements Control
The virtual list view request control as defined in draft-ietf-ldapext-ldapv3-vlv. This control allows a client to specify that the server return, for a given search request with associated sort keys, a contiguous subset of the search result set. This subset is specified in terms of offsets into the ordered list, or in terms of a greater than or equal assertion value.

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;
     }
 }
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final List<String>
    ALIASES
    The user-friendly aliases for the virtual list view request control.
    static final ControlDecoder<VirtualListViewRequestControl>
    DECODER
    A decoder which can be used for decoding the VirtualListViewRequestControl.
    static final String
    OID
    The OID for the virtual list view request control.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getAfterCount()
    Returns the number of entries after the target entry to be included in the search results.
    String
    getAlias()
    Returns the control "friendly name" alias for the control.
    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()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

  • Method Details

    • newAssertionControl

      public 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. The assertion value is encoded according to the ORDERING matching rule for the attribute description in the sort control. The assertion value is used to determine the target entry by comparison with the values of the attribute specified as the primary sort key. The first list entry whose value is no less than (less than or equal to when the sort order is reversed) the supplied value is the target entry.
      Parameters:
      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.
      Returns:
      The new control.
      Throws:
      IllegalArgumentException - If beforeCount or afterCount were less than 0.
      NullPointerException - If assertionValue was null.

    • newOffsetControl

      public 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.
      Parameters:
      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.
      Returns:
      The new control.
      Throws:
      IllegalArgumentException - If beforeCount, afterCount, or contentCount were less than 0, or if offset was less than 1.

    • getAfterCount

      public int getAfterCount()
      Returns the number of entries after the target entry to be included in the search results.
      Returns:
      The number of entries after the target entry to be included in the search results.

    • getAssertionValue

      public ByteString getAssertionValue()
      Returns the assertion value that will be used to locate the target entry, if applicable.
      Returns:
      The assertion value that will be used to locate the target entry, or null if this control is using a target offset.

    • getAssertionValueAsString

      public String getAssertionValueAsString()
      Returns the assertion value that will be used to locate the target entry, if applicable, decoded as a UTF-8 string.
      Returns:
      The assertion value that will be used to locate the target entry decoded as a UTF-8 string, or null if this control is using a target offset.

    • getBeforeCount

      public int getBeforeCount()
      Returns the number of entries before the target entry to be included in the search results.
      Returns:
      The number of entries before the target entry to be included in the search results.

    • getContentCount

      public int getContentCount()
      Returns the content count returned by the server in the last virtual list view response, if applicable.
      Returns:
      The content count returned by the server in the last virtual list view response, which may be 0 if this is the first virtual list view request, or -1 if this control is using a target assertion.

    • getContextId

      public 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.
      Returns:
      The context ID provided by the server in the last virtual list view response, or null if unavailable.

    • getOffset

      public int getOffset()
      Returns the positional offset of the target entry in the result set, if applicable, where 1 is the first entry.
      Returns:
      The positional offset of the target entry in the result set, or -1 if this control is using a target assertion.

    • getOid

      public String getOid()
      Description copied from interface: Control
      Returns the numeric OID associated with this control.
      Specified by:
      getOid in interface Control
      Returns:
      The numeric OID associated with this control.

    • getValue

      public ByteString getValue()
      Description copied from interface: Control
      Returns the value, if any, associated with this control. Its format is defined by the specification of this control.
      Specified by:
      getValue in interface Control
      Returns:
      The value associated with this control, or null if there is no value.

    • hasTargetOffset

      public boolean hasTargetOffset()
      Returns true if this control is using a target offset, or false if this control is using a target assertion.
      Returns:
      true if this control is using a target offset, or false if this control is using a target assertion.

    • hasValue

      public boolean hasValue()
      Description copied from interface: Control
      Returns 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.
      Specified by:
      hasValue in interface Control
      Returns:
      true if this control has a value, or false if there is no value.

    • isCritical

      public boolean isCritical()
      Description copied from interface: Control
      Returns 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.

      Specified by:
      isCritical in interface Control
      Returns:
      true if this control must be processed by the Directory Server, or false if it can be ignored.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getAlias

      public String getAlias()
      Description copied from interface: Control
      Returns the control "friendly name" alias for the control.
      Specified by:
      getAlias in interface Control
      Returns:
      "Friendly name" alias for the control.