| Author |
Topic: Virtual List View Control -- draft-ietf-ldapext-ldapv3-vlv-09.txt |
|
SteveHB
member
offline  |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
 |
|
|
| Virtual List View Control -- draft-ietf-ldapext-ldapv3-vlv-09.txt |
http://www.ietf.org/proceedings/02nov/I-D/draft-ietf-ldapext-ldapv3-vlv-09.txt
This document describes a Virtual List View extension for the Lightweight Directory Access Protocol (LDAP) Search operation. This extension is designed to allow the "virtual list box" feature, common in existing commercial e-mail address book applications, to be supported efficiently by LDAP servers. LDAP servers' inability to support this client feature is a significant impediment to LDAP replacing proprietary protocols in commercial e-mail systems.
The extension allows a client to specify that the server return, for a given LDAP search with associated sort keys, a contiguous subset of the search result set. This subset is specified in terms of offsets into the ordered list, or in terms of a greater than or equal comparison value.
|
|
|
|
|
|
|
SteveHB
member
offline  |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Client-Server Interaction |
The Virtual List View control extends a regular LDAP Search operation which MUST also include a Server-Side Sorting control [SSS]. Rather than returning the complete set of appropriate SearchResultEntry messages, the server is instructed to return a contiguous subset of those entries, taken from the ordered result set, centered around a particular target entry. Henceforth, in the interests of brevity, the ordered search result set will be referred to as "the list".
The sort control may contain any sort specification valid for the server. The attributeType field in the first SortKeyList sequence element has special significance for "typedown". The Virtual List View control acts upon a set of ordered entries and this order must be repeatable for all subsequent virtual list requests. The server-side sorting control is intended to aid in this ordering, but other mechanisms may need to be employed to produce a repeatable order -- especially for entries that don't have a value of the sort key.
The desired target entry and the number of entries to be returned, both before and after that target entry in the list, are determined by the client's VirtualListViewRequest control.
When the server returns the set of entries to the client, it attaches a VirtualListViewResponse control to the SearchResultDone message. The server returns in this control: its current estimate for the list content count, the location within the list corresponding to the target entry, any error codes, and optionally a context identifier.
The target entry is specified in the VirtualListViewRequest control by one of two methods. The first method is for the client to indicate the target entry's offset within the list. The second way is for the client to supply an attribute assertion value. The value is compared against the values of the attribute specified as the primary sort key in the sort control attached to the search operation. The first sort key in the SortKeyList is the primary sort key. The target entry is the first entry in the list with value greater than or equal to (in the primary sort order), the presented value. The order is determined by rules defined in [SSS]. Selection of the target entry by this means is designed to implement "typedown". Note that it is possible that no entry satisfies these conditions, in which case there is no target entry. This condition is indicated by the server returning the special value contentCount + 1 in the target position field.
Because the server may not have an accurate estimate of the number of entries in the list, and to take account of cases where the list size is changing during the time the user browses the list, and because the client needs a way to indicate specific list targets "beginning" and "end", offsets within the list are transmitted between client and server as ratios---offset to content count. The server sends its latest estimate as to the number of entries in the list (content count) to the client in every response control. The client sends its assumed value for the content count in every request control. The server examines the content count and offsets presented by the client and computes the corresponding offsets within the list, based on its own idea of the content count.
Si = Sc * (Ci / Cc)
Where:
Si is the actual list offset used by the server
Sc is the server's estimate for content count
Ci is the client's submitted offset
Cc is the client's submitted content count
The result is rounded to the nearest integer.
If the content count is stable, and the client returns to the server the content count most recently received, Cc = Sc and the offsets transmitted become the actual server list offsets. The following special cases exist when the client is specifying the offset and content count:
- an offset of one and a content count of non-one (Ci = 1, Cc != 1)
indicates that the target is the first entry in the list.
- equivalent values (Ci = Cc) indicate that the target is the last
entry in the list.
- a content count of zero (Cc = 0, Ci != 0) means the client has no
idea what the content count is, the server MUST use its own
content count estimate in place of the client's.
Because the server always returns contentCount and targetPosition, the client can always determine which of the returned entries is the target entry. Where the number of entries returned is the same as the number requested, the client is able to identify the target by simple arithmetic. Where the number of entries returned is not the same as the number requested (because the requested range crosses the beginning or end of the list, or both), the client MUST use the target position and content count values returned by the server to identify the target entry. For example, suppose that 10 entries before and 10 after the target were requested, but the server returns 13 entries, a content count of 100 and a target position of 3. The client can determine that the first entry must be entry number 1 in the list, therefore the 13 entries returned are the first 13 entries in the list, and the target is the third one.
A server-generated contextID MAY be returned to clients. A client receiving a contextID MUST return it unchanged or not return it at all, in a subsequent request which relates to the same list. The purpose of this interaction is to maintain state information between the client and server.
|
|
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Request Control |
This control is included in the SearchRequest message as part of the controls field of the LDAPMessage. The controlType is set to "2.16.840.1.113730.3.4.9". If this control is included in a SearchRequest message, a Server Side Sorting request control [SSS] MUST also be present in the message.
The controlValue, an OCTET STRING, is the BER-encoding of the following SEQUENCE:
VirtualListViewRequest ::= SEQUENCE {
beforeCount INTEGER (0..maxInt),
afterCount INTEGER (0..maxInt),
target CHOICE {
byOffset [0] SEQUENCE {
offset INTEGER (1 .. maxInt),
contentCount INTEGER (0 .. maxInt)
},
greaterThanOrEqual [1] AssertionValue
},
contextID OCTET STRING OPTIONAL }
beforeCount indicates how many entries before the target entry the client wants the server to send.
afterCount indicates the number of entries after the target entry the client wants the server to send.
offset and contentCount identify the target entry.
greaterThanOrEqual is a matching rule assertion value defined in [LDAPPROT]. The assertion value is encoded according to the ORDERING matching rule for the attributeDescription in the sort control [SSS]. If present, the value supplied in greaterThanOrEqual is used to determine the target entry by comparison with the values of the attribute specified as the primary sort key. The first list entry who's value is no less than (less than or equal to when the sort order is reversed) the supplied value is the target entry.
contextID contains the value of the most recently received contextID field from a VirtualListViewResponse control for the same list view. If the contextID is not known because no contextID has been sent by the server in a VirtualListViewResponse control, it SHALL be omitted. If the server receives a contextID that is invalid, it SHALL fail the search operation and indicate the failure with a protocolError (3) value in the virtualListViewResult field of the VirtualListViewResponse. The contextID provides state information between the client and server. This state information is used by the server to ensure continuity contiguous virtual list requests. When a server receives a VirtualListViewRequest control that includes a contextID, it SHALL determine whether the client has sent a contiguous virtual list request and SHALL provide contiguous entries if possible. If a valid contextID is sent, and the server is unable to determine whether contiguous data is requested, or is unable to provide requested contiguous data, it SHALL fail the search operation and indicate the failure with an unwillingToPerform (53) value in the virtualListViewResult field of the VirtualListViewResponse. contextID values have no validity outside the connection and query with which they were received. A client MUST NOT submit a contextID which it received from a different connection, a different query, or a different server.
|
|
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Response Control |
If the request control is serviced, this response control is included in the SearchResultDone message as part of the controls field of the LDAPMessage.
The controlType is set to "2.16.840.1.113730.3.4.10". The controlValue, an OCTET STRING, is the BER-encoding of the following SEQUENCE:
VirtualListViewResponse ::= SEQUENCE {
targetPosition INTEGER (0 .. maxInt),
contentCount INTEGER (0 .. maxInt),
virtualListViewResult ENUMERATED {
success (0),
operationsError (1),
protocolError (3),
unwillingToPerform (53),
insufficientAccessRights (50),
timeLimitExceeded (3),
adminLimitExceeded (11),
innapropriateMatching (18),
sortControlMissing (60),
offsetRangeError (61),
other(80),
... },
contextID OCTET STRING OPTIONAL }
targetPosition gives the list offset for the target entry.
contentCount gives the server's estimate of the current number of
entries in the list. Together these give sufficient information for
the client to update a list box slider position to match the newly
retrieved entries and identify the target entry. The contentCount
value returned SHOULD be used in a subsequent VirtualListViewRequest
control.
contextID is a server-defined octet string. If present, the contents
of the contextID field SHOULD be returned to the server by a client
in a subsequent virtual list request. The presence of a contextID
here indicates that the server is willing to return contiguous data
from a subsequent search request which uses the same search criteria,
accompanied by a VirtualListViewRequest which indicates that the
client wishes to receive an adjoining page of data.
The virtualListViewResult codes which are common to the LDAP
searchResultDone (adminLimitExceeded, timeLimitExceeded,
operationsError, unwillingToPerform, insufficientAccessRights,
success, other) have the same meanings as defined in [LDAPPROT], but
they pertain specifically to the VLV operation. For example, the
server could exceed a VLV-specific administrative limit while
processing a SearchRequest with a VirtualListViewRequest control.
Obviously, the same administrative limit would not be exceeded should
the same SearchRequest be submitted by the client without the
VirtualListViewRequest control. In this case, the client can
determine that the administrative limit has been exceeded in
servicing the VLV request, and can if it chooses resubmit the
SearchRequest without the VirtualListViewRequest control, or with
different parameters.
insufficientAccessRights means that the server denied the client
permission to perform the VLV operation.
If the server determines that the results of the search presented
exceed the range specified in INTEGER values, or if the client
specifies an invalid offset or contentCount, the server MUST set the
virtualListViewResult value to offsetRangeError.
|
|
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Client-Server Interaction |
Server Side: 78564 entries
Client Side: a view screen of 20 entries
[Action #1: client wants to show the beginning of the list
Client: Server:
_offset: 1
_contentCount: 0 -->
_beforeCount: 0
_afterCount: 19
<== _contentCount: 78564
_targetPosition: 1
(with 20 entries returned)
Action #2: client drags the scroll bar down to the bottom of the list
Client: Server:
_offset: 78564
_contentCount: 78564 -->
_beforeCount: 19
_afterCount: 0
<== _contentCount: 78564
_targetPosition: 78564
(with 20 entries returned)
Action #3: client presses a page up key
Client: Server:
_offset: 78564-19-20
_contentCount: 78564 -->
_beforeCount: 0
_afterCount: 19
<== _contentCount: 78564
_targetPosition: 78525
(with 20 entries returned)
[Action #4: client drags the scroll bar slider 68% of list
Client: Server:
_offset: 53424
_contentCount: 78564 -->
_beforeCount: 9
_afterCount: 10
<== _contentCount: 78564
_targetPosition: 53424
(with 20 entries returned)
Action #5: client types XYZ to browse the list starting from XYZ
Client: Server:
greaterThanOrEqual: XYZ
_beforeCount: 0 -->
_afterCount: 19
<== _contentCount: 78564
_targetPosition: 77777
(with 20 entries returned)
|
|
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Who Supports VLV Control? |
SunOne Directory Server & Fedora Directory Server support Virtual List View (VLV) Control, in replacement of Paged Results Control.
Active Directory Server supports VLV Control since AD2003, AD 2008
|
|
|
|
|
|
|
SteveHB
member
offline |
| |
| posts: |
113 |
| joined: |
05/31/2006 |
| from: |
Mountain View, CA |
|
|
|
|
|
| Why Virtual List View (VLV) Control Must Be Used In Conjunction With Sort Control? |
For browsing huge amount of search results, Paged Results Control can be used on it own where the results can be returned in any order; but the Virtual List View (VLV) Control is aimed to bring back results which are sorted. In that sense, it must be used with Server-Side Sort (SSS) Control.
On the other hand, only attribute value is specified as greaterThanOrEqual as the follows:
VirtualListViewRequest ::= SEQUENCE {
....
greaterThanOrEqual [1] AssertionValue
},
}
Which attribute type (sn, cn or any) is this value associated with? That attribute type is specified and passed in another control -- Server-Side Sort Control. For this reason, VLV Control needs Sort Control.
|
|
|
|
|
|
|
|
Email To Friend | 
Set Alert To This Topic
New Topic | 
Post Reply 
posted on: 03/04/2009 07:39:22 PM
Edit
Quote
Report
Profile
Reply