





INTERNET-DRAFT                                      Kurt D. Zeilenga
                                                 OpenLDAP Foundation
Expires in six months                                 1 October 2002



              LDAP (Alternative) Virtual List View Operation
                   <draft-zeilenga-ldapext-vlv-00.txt>



1.      Status of this Memo

  This document is an Internet-Draft and is in full conformance with all
  provisions of Section 10 of RFC2026.

  This document is offered to IETF LDAPEXT WG as an alternative to
  draft-ietf-ldapext-ldapv3-vlv-xx.txt.

  This document is intended to be, after appropriate review and
  revision, submitted to the RFC Editor as a Standard Track document.
  Distribution of this memo is unlimited.  Technical discussion of this
  document will take place on the IETF LDAPEXT Working Group mailing
  list <ldapext@ietf.org>.  Please send editorial comments directly to
  the author <Kurt@OpenLDAP.org>.

  Internet-Drafts are working documents of the Internet Engineering Task
  Force (IETF), its areas, and its working groups.  Note that other
  groups may also distribute working documents as Internet-Drafts.
  Internet-Drafts are draft documents valid for a maximum of six months
  and may be updated, replaced, or obsoleted by other documents at any
  time.  It is inappropriate to use Internet-Drafts as reference
  material or to cite them other than as ``work in progress.''

  The list of current Internet-Drafts can be accessed at
  <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
  Internet-Draft Shadow Directories can be accessed at
  <http://www.ietf.org/shadow.html>.

  Copyright 2002, The Internet Society.  All Rights Reserved.

  Please see the Copyright section near the end of this document for
  more information.








Zeilenga                 LDAP Virtual List View                 [Page 1]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


Abstract

  This document describes an LDAP (Lightweight Directory Access
  Protocol) Virtual List View (VLV) operation.  The operation allows the
  client to obtain portion (the view) of an ordered set (the list) of
  entries visible through a virtual window.  The client can reissue the
  operation with different criteria to obtain a different view of the
  list.  Clients may use this operation to page, scroll, or browse
  directory content.

  The VLV operation is defined as a set of LDAP controls which extend
  the Search operation.  The VLV controls may be used in conjunction
  with a number of other search controls, such as the Server Side
  Sorting of Search Results (RFC 2891) control.


1. Overview

  A "virtual list" is a graphical user interface (GUI) technique
  employed where a list containing a large number of entries need to be
  displayed.  A window containing a small number of list entries are
  visible.  This window can be relocated such that another set of list
  entries are visible.  The set of entries visible through the window is
  the view.

  The Lightweight Directory Access Protocol (LDAP) [RFC3377] Virtual
  List View (VLV) operation allows a client to obtain the set of entries
  of an ordered list visible through a window from a server.  The set of
  entries are selected based on search criteria.  In absence of a
  control specifying a particular order, the order is determined by the
  server.  The position and size of the window is determined by
  parameters of the VLV request control.

  The VLV operation is defined as an extended Search operation.  The VLV
  operation is state-less.

  Appendix A. discusses how a client can use VLV operations to provide a
  GUI to page, scroll, and browse directory content.


1.1. Relationship to other LDAP extensions

  The VLV operation may be used with

      - Duplicate Entry Control [DUPENT],
      - ManageDsaIT Control [RFC3296],
      - Matched Values Control [MATCHED],
      - Server-Side Sorting Control [RFC2891], and



Zeilenga                 LDAP Virtual List View                 [Page 2]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


      - Subentries Control [SUBENTRY].

  as described in Section 5.  The VLV operation may be used with other
  LDAP extensions as detailed in other documents.

  This document provides a standardized mechanism for scrolling, paging,
  and browsing DIT content.  It is intended to replace Scrolling View
  Browsing [SVB] and the the Simple Paged Results Manipulation [RFC2696]
  control extensions.


1.2. Comparison to Scrolling View Browsing

  This document was originally offered as an alternative to the
  Scrolling View Browsing (SVB) [SVB] approach.  While both SVB and VLV
  are upon a Virtual View List metaphor, they differ in many ways.  This
  section highlights a few of the differences.

  SVB was designed to work in static environments.  Small DIT changes
  between related SVB operations can yield astonishing results.  For
  example, an SVB operation intended to page the view down, may jump
  over entries or an SVB operation intended to scroll a view up can
  actually return entries which are below the current view.  This is
  because SVB relies on the ordinal position of entries in the list to
  be stable.

  VLV addresses this problem by selecting the target entry which the
  view is centered about by DN.  An VLV intended to page down the view,
  selects the next page based upon the position of a particular entry.
  Likewise for scrolling.  Even where the target entry is modified (and
  hence now appears next to other entries in the list), the client can,
  by requesting overlapping entries, determine whether the returned view
  is adjacent to the previous view or not.  Based upon intended result,
  the client can choose to display this view to the user or request
  another view centered about other entries in the previous view.

  SVB provides a mechanism allowing selection of the target entry by its
  offset from the head of the list, but not the tail of the list.  VLV
  provides selection by offsets from the head or the tail.

  SVB provides a "type down" selection mechanism limited to the list
  primary sort key.  VLV provides a "type down" selection mechanism
  which allows selection by all of the sort keys.

  SVB requires that entries be sorted using the Server-Side Sorting
  Control [RFC2891].  VLV only requires that the list be ordered by a
  deterministic algorithm.  VLV allows, but does not require, a
  particular ordering algorithm to be requested.



Zeilenga                 LDAP Virtual List View                 [Page 3]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


1.3. Terminology and Conventions

  The term "list" (of entries) refers to an ordered set of entries by a
  deterministic algorithm.  The list may contain both returnable and
  non-returnable entries.

  The term "returnable entry" refers to an entry which the server is
  willing and able to return.  A "non-returnable entry" refers to an
  entry which the server is unwilling or unable to return.

  The term "target" refers to the entry used to position the window.

  The term "view" refers to the portion of a list of entries visible
  through a window.

  The term "window" refers to the criteria for selecting the portion of
  the list to be viewed.

  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  document are to be interpreted as described in BCP 14 [RFC2119].


2. Protocol Elements

  Protocol elements are described using ASN.1 [X.680].  The term
  "BER-encoded" means the element is to be encoded using the Basic
  Encoding Rules [X.690] per Section 5.1 of [RFC2251].


2.1.  VLV Request Control

  The VLV Request Control is an LDAPControl [RFC2251] whose controlType
  is the "IANA-ASSIGNED-OID.1", criticality is True or False (the
  DEFAULT), and the controlValue, an OCTET STRING, contains a
  BER-encoded value of the vlvRequestValue data type:

      target ::= SEQUENCE {
           tSelect CHOICE {
                tName       [0] LDAPDN,
                tFraction [1] SEQUENCE {
                     tNumerator          INTEGER,
                          -- constrained to (0..tDenominator))
                     tDenominator   INTEGER (1..maxint)
                },
                tOffset   [2] INTEGER (0..maxint),
                tTypeDown [3] SEQUENCE OF AssertionValue
                     -- contains at least one AssertionValue



Zeilenga                 LDAP Virtual List View                 [Page 4]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


                ...
           },
           tReverse  BOOLEAN DEFAULT False
                -- for tTypeDown, tReverse is constrained to False
      }

      window ::= SEQUENCE {
           wOffset        INTEGER,
           wCount         INTEGER (0..maxInt)
           wReverse  BOOLEAN DEFAULT False
      }

      vlvRequestValue ::= SEQUENCE {
           COMPONENTS OF target
           COMPONENTS OF window
      }

  The VLV Request Control is applicable to the SearchRequest message.


2.2.  VLV Target Response Control

  The VLV Target Response Control is an LDAPControl [RFC2251] whose
  controlType is the "IANA-ASSIGNED-OID.2", criticality is False (the
  DEFAULT), and the controlValue is absent.

  The VLV Target Response Control is applicable to the SearchResultEntry
  message.


2.3.  VLV Done Response Control

  The VLV Done Response Control is an LDAPControl [RFC2251] whose
  controlType is the "IANA-ASSIGNED-OID.3", criticality is False (the
  DEFAULT), and the controlValue is absent.

  The VLV Done Response Control is applicable to the SearchResultDone
  message.


2.4.  VLV Result Codes

  Implementations of this specification SHALL recognize the following
  additional resultCode [RFC2251] values:

       vlvTargetInvalid    (IANA-ASSIGNED-1)
       vlvTargetNotFound   (IANA-ASSIGNED-2)
       vlvWindowInvalid    (IANA-ASSIGNED-3)



Zeilenga                 LDAP Virtual List View                 [Page 5]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


3. The VLV Operation

  The VLV operation is defined as an extension to the Search operation.
  The operation is initiated by the client sending a VLV request
  message, a SearchRequest which includes a VLV Request Control.  In
  response to this request, the server returns zero or more
  SearchResultEntry messages, one of which may include the VLV Target
  Control.  The operation is completed by the server returning a VLV
  done response message, a SearchResultDone message which includes VLV
  Response Done Control.

  No searchResultReference messages are returned in response to a VLV
  Request.  Continuation references are discussed further in Section
  4.1.

  In the VLV request message, fields of searchRequest structure specify
  the list of entries.  The searchRequest fields have the same semantics
  as defined in Section 4.5.1 of [RFC2251].  The fields of the VLV
  Request Control specify the desired target as well as the window.


3.1. Target Selection

  The target may be select from the list by multiple means.


3.1.1. Target Selection by DN

  The target tName choice allows selection of the target by
  distinguished name (DN).  If the provided LDAPDN is not a valid string
  representation [RFC2253] of a DN, vlvTargetInvalid is returned.  If
  the entry named cannot be found, is not in the list, or is not
  returnable, vlvTargetNotFound is returned.

  When the request is accompanied by a Duplicate Entry control [DUPENT],
  tReverse=False indicates that first duplicate of the entry in the list
  is the target and tReverse=True indicates that last duplicate of the
  entry in the list is the target.  If a Duplicate Entry control was not
  provided, tReverse is ignored.


3.1.2. Target Selection by Offset

  The target tOffset choice selects the target based on ordinal position
  in the list.  When tReverse is False (DEFAULT), a tOffset value of N
  selects the first returnable entry whose ordinal position is greater
  than N.  When tReverse is True, a tOffset value of N selects the last
  returnable entry in a list of size M whose ordinal position is less



Zeilenga                 LDAP Virtual List View                 [Page 6]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  than or equal to the value M-N.  For example, in a list of 100
  entries:

      <tOffset=0,tReverse=False> selects the first returnable entry;

      <tOffset=0,tReverse=True> selects the first returnable entry;

      <tOffset=10,tReverse=True> selects the first returnable entry
      whose ordinal position is greater than 10;

      <tOffset=5,tReverse=True> selects the last returnable entry whose
      ordinal position is less than or equal to 95 (100-5).

  If the value of tOffset is greater than or equal to the size of the
  list, vlvTargetInvalid is returned.  If no entry meets the criteria,
  vlvTargetNotFound is returned.


3.1.2. Target Selection by Fraction

  The target tFraction choice selects the target based on proportional
  position of entries on the list. The target is the first returnable
  entry whose ordinal position is closest to quantity 0.5 plus product
  of the size of the list, less one, and the quotient of the value
  tNumerator divided by the value of tDenominator.  That is, the target
  is the returnable entry of whose ordinal position in a list of N
  entries is closest to

       (0.5 + (N - 1) * (tNumerator / tDenominator))).

  Where the two closest returnable entries are equally close, the entry
  which appears later in the list is targeted.

  For a list of any size:

      <tNumerator=0,tDenominator=1> selects the first returnable entry;
      and
      <tNumerator=1,tDenominator=1> selects the last returnable entry;

  For a list of size 100:
      <tNumerator=1,tDenominator=2> selects the returnable entry closest
  to 51 (e.g., the returnable entry closest to the middle);
      <tNumerator=2,tDenominator=3> selects the returnable entry closest
  to 65.49.

  For a list of size 101:
      <tNumerator=1,tDenominator=2> selects the returnable entry closest
  to 50.5 (e.g., the returnable entry closest to the middle);



Zeilenga                 LDAP Virtual List View                 [Page 7]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


      <tNumerator=2,tDenominator=3> selects the returnable entry closest
  to 67.2.

  If the list is empty or contains no returnable entries,
  vlvTargetNotFound is returned.  If tReverse is True, protocolError is
  returned.


3.1.3. Target Selection by Type Down

  The target tTypeDown choice selects the target whose based upon "type
  down" criteria.

  The first tTypeDown AssertionValue is associated with the first sort
  key.  The second AssertionValue is associated with the second key.
  And so on.

  If there are more AssertionValues than keys, protocolError is
  returned.  If there are more keys than AssertionValues, only the keys
  which have associated AssertionValues are used.

  If tReverse is True, protocolError is returned.

  To select the target, the set of returnable entries whose least
  attribute value for the first key is equal to the first AssertionValue
  is determined.  If the set contains one entry, that entry is the
  target.  If this set is empty, the first returnable greater than the
  AssertionValue is the target.  If none, vlvTargetNotFound is returned.
  If the set contains multiple entries, additional key and
  AssertionValue pairs are used in turn as detailed in the next
  paragraph.  If there are no additional pairs, the target is the first
  entry in the set.

  Using the next key and AssertionValue, a subset of the set (from the
  preceding step) whose least attribute value for the key is equal to
  the AssertionValue is determined.  If the set contains one entry, that
  entry is the target.  If this subset is empty, first entry in the set
  greater than the AssertionValue is the target.  If none, the first
  returnable entry entry greater than the first AssertionValue is the
  target.  In none, vlvTargetNotFound is returned.  If the set contains
  multiple entries, then this step is repeated with the next key and
  AssertionValue pair.  If there are no additional pairs, the target is
  the first entry in the subset.

  For example, consider a list sorted by list sorted first by 'sn', then
  by 'givenName', and then by 'initials' and a target criteria of
  <tTypeDown={"James", "J"}>.   First, the set of returnable entries
  whose least value of 'sn' is "James" is determined.  Second, assuming



Zeilenga                 LDAP Virtual List View                 [Page 8]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  the set is non-empty, the subset of this set whose least value of
  'givenName' is "J" is determined.  If the subset is non-empty, the
  first entry of the subset is the target (as there are no further key /
  AssertionValue pairs).  If this subset is empty then, the target is
  the first entry in the set which has a 'givenName' greater than "J".
  If none, then the target is the first entry in the list which contains
  a 'sn' value greater than 'James'.


3.2. View Selection and Return

  If wCount is 0, the view is empty and no entries are returned.
  Otherwise, the window is positioned relative to the target entry to
  determine the view.

  The positioning index is the value of wOffset plus the ordinal
  position of the target entry.  If this index is less than 1, the first
  entry of the list is first entry of the view.  If the index is greater
  than the size of the list, the last entry in the list is the first
  entry in the view.  Otherwise, the entry whose ordinal position in the
  list is equal to this index is the first entry of the view.

  If the entry at the positioning index is returnable, it is returned
  first and wCount is reduced by one.

  If wReverse=False, the next wCount returnable entries from the
  position index towards the tail of the list are in the view and are
  returned in increase ordinal order.

  If wReverse=True, the next wCount returnable entries from the position
  index towards the head of the list are in the view and are returned in
  decreasing ordinal order.

  If the target entry is within view, it is returned with a Virtual
  Target Response control.


3.3. Done Response Message

  The VLV Done Response message is returned on completion of the VLV
  operation.


4. Other considerations

4.1. Continuation References

  As indicated above, no searchResultReference messages are returned in



Zeilenga                 LDAP Virtual List View                 [Page 9]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  response to a VLV Request.

  Where the content contains references to other servers, the server MAY
  obtain entries from these others in order to fulfill the VLV request.
  Otherwise, the server SHALL ignore these references.


4.2. Changes to content between VLV operations

  While individual entries tend to change infrequently, changes to a
  list of entries is likely change frequently.  For example, if the
  average entry changes once per (8 hour) work day, a list of 28,800
  entries will change approximately once per second during the work day.

  The client SHOULD NOT assume the directory content is static.


4.3. Changes to content during a VLV operation

  Server implementations which allows directory content to change (due
  to other operations) during processing of the VLV operation, need to
  take special care to ensure the operation behaves in a consistent
  manner.

  During the processing of the VLV operation, an entry is modified in a
  manner which changes in a manner which affects it position in the
  list.  If only the old position is in the view, the server MUST either
  return the old entry in the old position or not return the entry.  If
  only the new position is in the view, the server MUST either return
  new entry in the new position or not return the entry.  If both
  positions are in the view, the server MUST either return the old entry
  in the old position, the new entry in the new position, or not return
  the entry.

  If the target entry is modified, then the server MUST select all
  returned entries based upon the old position of the target entry or
  select all returned entries based upon the new entry.


5. Interaction with Other Controls

  The VLV operation may be used with

      - Duplicate Entry Control [DUPENT],
      - ManageDsaIT Control [RFC3296],
      - Matched Values Control [MATCHED],
      - Server-Side Sorting Control [RFC2891], and
      - Subentries Control [SUBENTRY].



Zeilenga                 LDAP Virtual List View                [Page 10]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  as described below.  The VLV operation may be used with other LDAP
  extensions as detailed in other documents.


5.1. Server-Side Sorting Control

  VLV operations provide a view into an ordered list.  When the Server-
  Side Sorting Control (SSS) [RFC2891] indicates the particular sorting
  algorithm to be used to determining the order of entries in the list.
  Where the sorting algorithm allows for two or more entries to be
  presented in any order, the server MUST choose the order which these
  entries appear in the list by a deterministic algorithm.

  That is, if the Sort Control indicates the list is to sorted by their
  CN values and two or more entries have the same CN value, the server
  is not free to return the entries in randomly selected order.


5.2. Duplicate Entry Control

  It is often desirable to include an entry which has multiple values
  for the sort key(s) in the list multiple times, once for each value of
  a sort key.  For example, when constructing a list of entries by
  ordered by common name (CN), it is often desirable for the entry to
  appear in the list under each CN value.  The Duplicate Entry Control
  provides a mechanism by which the "client requests that the server
  return separate entries for each value held in the specified
  attribute(s)" [DUPENT].

  When used with the VLV Operation, the Duplicate Entry Control
  logically applies to entries before list ordering.  That is, each
  duplicate entry is ordered independently in respect to other entries
  (duplicates or not) in the list.

  A particular ordering algorithm may be specified by use of a sorting
  control.


5.3. Matched Values Control

  The Matched Values control is "used to return a subset of attribute
  values from an entry, specifically, only those values that match a
  "values return" filter" [MATCHED].

  When used with the VLV Operation, the Matched Values control logically
  applies to entries before list ordering.  That is, entries are to
  ordered based only upon a subset of attribute values selected by the
  Matched Values control.  Other values are eliminated.



Zeilenga                 LDAP Virtual List View                [Page 11]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  Matched Values control SHOULD precede other controls are specified
  which affect the number and ordering entries in the list.


5.4. ManageDsaIT control

  As when used with other operations, the ManageDsaIT control [RFC3296]
  causes referral and other special objects to be treated as normal
  objects with respect to the VLV Operation and other controls.  That
  is, the referral and other special objects appear in the list if they
  were normal objects.


5.5. Subentries control

  The Subentries control is used with the search operation "to control
  the visibility of entries and subentries which are within scope"
  [SUBENTRY].  When used with the VLV Operation, the subentries control
  and other factors (search scope, filter, etc.) is used to determining
  whether an entry or subentry in the list is returnable or not.


6. Security Considerations

  Significant resources (CPU, memory, etc.) may be required at the
  server to process a VLV Operation, especially where the VLV Operation
  has been extended by Server-Side Sorting, Duplicate Entry, and other
  controls.  Servers SHOULD provide administrative controls to limit the
  rate and/or kinds of VLV operations which can be submitted by
  authorized users.

  A single VLV operation does not directly disclose the size of the
  list.  However, by issuing multiple VLV operations, an authorized
  client can determine the size of the list.


7. IANA Considerations

  Registration of the following values is requested [RFC3383].


7.1.  Object Identifiers

  It is requested that IANA register upon Standards Action an LDAP
  Object Identifier in identifying the protocol elements defined in this
  technical specification.  The following registration template is
  suggested:




Zeilenga                 LDAP Virtual List View                [Page 12]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


      Subject: Request for LDAP OID Registration
      Person & email address to contact for further information:
          Kurt Zeilenga <kurt@OpenLDAP.org>
      Specification: RFCXXXX
      Author/Change Controller: IESG
      Comments:
           Three delegations will be made under the assigned OID:

           IANA-ASSIGNED-OID.1 VLV Request Control
           IANA-ASSIGNED-OID.2 VLV Target Response Control
           IANA-ASSIGNED-OID.3 VLV Done Response Control


7.2.  LDAP Protocol Mechanism

  It is requested that IANA register upon Standards Action the LDAP
  protocol mechanism described in this document.  The following
  registration template is suggested:

      Subject: Request for LDAP Protocol Mechanism Registration
      Object Identifier: IANA-ASSIGNED-OID.1
      Description: VLV Request Control
      Person & email address to contact for further information:
          Kurt Zeilenga <kurt@openldap.org>
      Usage: Control
      Specification: RFCxxxx
      Author/Change Controller: IESG
      Comments: none
      in 2


7.3.  LDAP Result Codes

      It is requested that IANA register upon Standards Action the LDAP
      result codes:

           vlvTargetInvalid    (IANA-ASSIGNED-1)
           vlvTargetNotFound   (IANA-ASSIGNED-2)
           vlvWindowInvalid    (IANA-ASSIGNED-3)

      The following registration template is suggested:

      Subject: LDAP Result Code Registration
      Person & email address to contact for further information:
          Kurt Zeilenga <kurt@OpenLDAP.org>
      Result Code Name: vlvTargetInvalid
      Result Code Name: vlvTargetNotFound
      Result Code Name: vlvWindowInvalid



Zeilenga                 LDAP Virtual List View                [Page 13]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


      Specification: RFCXXXX
      Author/Change Controller: IESG
      Comments:  request consecutive result codes be assigned


8. Normative References

  [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
            Requirement Levels", BCP 14 (also RFC 2119), March 1997.

  [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
            Protocol (v3)", RFC 2251, December 1997.

  [RFC2253]  M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
            Protocol (v3): UTF-8 String Representation of Distinguished
            Names", RFC 2253, December 1997.

  [RFC2830] J. Hodges, R. Morgan, and M. Wahl, "Lightweight Directory
            Access Protocol (v3): Extension for Transport Layer
            Security", RFC 2830, May 2000.

  [RFC2891] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for
            Server Side Sorting of Search Results", RFC 2891, August
            2000

  [RFC3296] K. Zeilenga, "Named Subordinate References in Lightweight
            Directory Access Protocol (LDAP) Directories", RFC 3296,
            July 2002.

  [RFC3377] J. Hodges, R. Morgan, "Lightweight Directory Access Protocol
            (v3): Technical Specification", RFC 3377, September 2002.

  [DUPENT]  J. Sermersheim. "LDAP Control for a Duplicate Entry
            Representation of Search Results",
            draft-ietf-ldapext-ldapv3-dupent-xx.txt (a work in
            progress).

  [MATCHED] D. Chadwick, "Returning Matched Values with LDAPv3",
            draft-ietf-ldapext-matchedval-xx.txt (a work in progress).

  [X.680]   ITU-T, "Abstract Syntax Notation One (ASN.1) - Specification
            of Basic Notation", X.680, 1994.

  [X.690]   ITU-T, "Specification of ASN.1 encoding rules:  Basic,
            Canonical, and Distinguished Encoding Rules", X.690, 1994.


9. Informative References



Zeilenga                 LDAP Virtual List View                [Page 14]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 (also
            RFC 3383), September 2002.

  [SVB]     D. Bozeman, J. Sermersheim, A. Kashi, "LDAP Extensions for
            Scrolling View Browsing of Search Results", draft-ietf-
            ldapext-ldapv3-vlv-08.txt (a work in progress).


10. Acknowledgment

  This work benefited from prior work in this area, especially the
  paging and scrolling work done in IETF ASID and LDAPEXT working
  groups.

  This borrows significantly (both concepts and text) from the "LDAP
  Extensions for Scrolling View Browsing of Search Results" [SVB]
  Internet-Draft written by Dave Boreham, Jim Sermersheim, and Asaf
  Kashi.


11. Author's Address

  Kurt D. Zeilenga
  OpenLDAP Foundation
  <Kurt@OpenLDAP.org>

Appendix A.  Using the VLV Operation

  This informative appendix discusses how the VLV operation can be used
  to page, scroll, and browse directory content.

  For the purposes of this discussion, let's assume we want to implement
  an address book application which allows the user to page, scroll, and
  browse address information held in an LDAP-accessible directory system
  using inetOrgPerson [RFC2798] schema.

  Say this application has a widget which is capable of displaying 10
  rows of information.  In each row, we'll display the values of
  'displayName' and 'mail' attributes of an entry.

  Aside from the usual search parameters (baseObject, scope, filter), we
  likely also want to sort the entries.  So, initially, we'll provide a
  sort control which requests values be sorted by displayName.

A.1. Widget Initialization

  There are multiple VLV operations which might be used to initialize
  the widget.  To initialize the widget with the first 10 entries of the



Zeilenga                 LDAP Virtual List View                [Page 15]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  list, the VLV request <tOffset=0, tReverse=False, wOffset=0,
  wCount=10, wReverse=False> can be used.  To initialize the widget with
  the middle 10 entries, the VLV request <tNumerator=1, tDenominator=2,
  tReverse=False, wOffset=-5, wCount=10, wReverse=False> can be used.
  To initialize the widget to the last 10 entries, the VLV request
  <tNumerator=1, tDenominator=1, tReverse=False, wOffset=-9, wCount=10,
  wReverse=False> can be used.

  However, as the last 10 entries of in the list may not be returnable,
  it may be more appropriate to request <tNumerator=1, tDenominator=1,
  tReverse=False, wOffset=0, wCount=10, wReverse=True> instead.  Note
  that since wReverse is selected, the last entry is returned first.

  The widget can also be initialized to the entries surrounding a known
  DN by sending the request <tName="cn=kdz,dc=example,dc=com",
  tReverse=False, wOffset=-5, wCount=10, wReverse=False>.

  The widget can also be initialized based upon "typedown" criteria.
  Typedown is discussed in A.4.


A.2. Slider navigation

  Most list widgets allow based upon proportional positioning of a
  slider.  Our widget reports the slider's position as the percentage
  the area above the slider position to the total slider area.  When it
  is repositioned, the application can request <tNumerator=percent,
  tDenominator=100, tReverse=False, wOffset=-5, wCount=10,
  wReverse=False> when percent is less than or equal to 50 and
  <tNumerator=percent, tDenominator=100, tReverse=False, wOffset=5,
  wCount=10, wReverse=True> when percent is less than or equal to 50.
  Because the list may contain non-returnable entries, we reverse the
  window as we approach the tail of the list.  When wReverse is True,
  the last entry is returned first.


A.3. Page navigation

  Most list widgets provide page up/down controls.

  When page down is selected, the application can request <tName=last,
  tReverse=False, wOffset=0, wCount=10, wReverse=False> where last is
  the name of the entry presently at the bottom of the current widget
  view.  The server will then return a new view in forward order.  When
  inserted into the widget, the target will appear at the top of the
  current widget view.

  When page up is selected, the application can request <tName=first,



Zeilenga                 LDAP Virtual List View                [Page 16]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  tReverse=False, wOffset=0, wCount=10, wReverse=Reverse> where first is
  the name of the entry presently at the top of the current view.  The
  server will then return a new view in reverse order with the named
  entry returned first.  When inserted into the widget, the target will
  appear at the bottom the current widget view.

  If the page up/down VLV operation returns vlvTargetNotFound, the
  application can reissue the page up/down VLV operation with the name
  of the entry nearest the top/bottom of the present widget view.

  It is noted that when named entry is modified prior to issuing of the
  VLV operation in a manner which affects its position in the list, the
  view will follow the named entry.


A.4. Type down navigation

  Type down navigation can be used to navigate the list.

  The list is sorted by 'displayName'.  When the user types in a partial
  or complete value, the application can use this value to present the
  10 values at are below the value.

  So, for example, the user inputs "K", the application can request
  <tTypeDown="K", tReverse=False, wOffset=0, wCount=10, wReverse>.
  Desiring further typedown, the user inputs "Kurt" and the application
  requests <tTypeDown="Kurt", tReverse=False, wOffset=0, wCount=10,
  wReverse>.  Etc.


Copyright 2002, The Internet Society.  All Rights Reserved.

  This document and translations of it may be copied and furnished to
  others, and derivative works that comment on or otherwise explain it
  or assist in its implementation may be prepared, copied, published and
  distributed, in whole or in part, without restriction of any kind,
  provided that the above copyright notice and this paragraph are
  included on all such copies and derivative works.  However, this
  document itself may not be modified in any way, such as by removing
  the copyright notice or references to the Internet Society or other
  Internet organizations, except as needed for the  purpose of
  developing Internet standards in which case the procedures for
  copyrights defined in the Internet Standards process must be followed,
  or as required to translate it into languages other than English.

  The limited permissions granted above are perpetual and will not be
  revoked by the Internet Society or its successors or assigns.




Zeilenga                 LDAP Virtual List View                [Page 17]

INTERNET-DRAFT        draft-zeilenga-ldapext-vlv-00       1 October 2002


  This document and the information contained herein is provided on an
  "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
  ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
  INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
  INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
  WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.













































Zeilenga                 LDAP Virtual List View                [Page 18]

