mirror of
https://git.openldap.org/openldap/openldap.git
synced 2025-01-06 10:46:21 +08:00
1012 lines
36 KiB
Plaintext
1012 lines
36 KiB
Plaintext
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
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]
|
|||
|
|