Subject: Client-Server Interaction
Author: SteveHB
In response to: Virtual List View Control -- draft-ietf-ldapext-ldapv3-vlv-09.txt
Posted on: 03/04/2009 07:49:09 PM
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.
>
> On 03/04/2009 07:39:22 PM
SteveHB wrote:
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.
References:
