mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-12-21 03:10:25 +08:00
Code Issues Packages Projects Releases Wiki Activity
f6db6d336f
openldap/doc/drafts/draft-zeilenga-ldapext-vlv-xx.txt
Kurt Zeilenga 304410c7a0 Update drafts
2003-05-31 22:47:07 +00:00

1012 lines
36 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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]
Reference in New Issue View Git Blame Copy Permalink