Some important LDAP result codes that could result from issuing a search to the directory server. The non-zero result codes except for 10 refer to either an error, or some limit being exceeded. The result codes that are not errors are prophylactic in nature: they prevent LDAP clients from monopolizing Directory Server resources. Administrators must never allow clients to request large numbers of entries or use unlimited amounts of server time processing a request without the client have mad special arrangements. Modern professional-quality directory servers like the UnboundID Directory Server support assigning connection and request resource limits on a per-client and per distinguished name basis.
In order to complete requests more quickly, the directory server can maintain indexes for values of attributes. The value of the attribute is used as the key, and a list of entry IDs are the data. The entry IDs can be considered pointers to the entries that have that value for the attribute in question.
Unindexed searches cannot always be avoided or eradicated, but important searches by applications should be indexed wherever it is feasible to do so. Unindexed searches can take a long time, and can adversely impact other LDP clients connected to the server. Note that a search starting high up in the directory information tree with subtree scope and filter “(objectClass=*)” or “(objectClass=top)” will almost always be unindexed, depending on where the base object is located in the tree, since every entry has an objectClass, and every entry has the objectClass “top”.
See the full article at LDAP: An index with a LIMIT-EXCEEDED condition causing an unindexed search” for a demonstration of an index that has exceeded a limit and caused a search to be unindexed, and most importantly, what to do about it.
The matched values request control described in RFC 3876 provides LDAP clients with a way to filter values that would be returned in a search request. This capability is very useful when the LDAP client must process entries with large numbers of values for a multi-valued attribute. The LDAP client specifies the usual search request parameters:
- baseObject
- scope
- filter
- requested attributes
and in addition may specify other search parameters such as size limit, time limit, and so on.
LDAP clients should always check the root DSE to determine whether a request control is supported before transmitting it to a server For a full description of the search request see:
- LDAP: ldapsearch
- LDAP: Mastering Search Filters
- LDAP: Programming Practices
- LDAP: Search Best Practices
To use the matched values request control, the LDAP client creates the request control using a matched values filter, attaches the request control to the search request, and transmits the search request to the directory server, then processes the response. The server will only return values of attributes matching the matched values filter; attributes need not retrieve all values of a multi-valued attribute and iterate over them. The demonstration of how to use the matched values request control is called MatchedValuesRequestControlExample.java – click on the filename to download.
Test Entry
The test was executed using the following entry. Note the multiple values of the description attribute. The intent of the test is to retrieve the description attribute whose value is "description type 4". Without the matched values request control, the LDAP client would be forced to retrieve all values of the description attribute and iterate over all of the values until a value of "description type 4" was found – not very scalable at all. With the matched values request control, the matched values filter is specified as "(description:caseExactMatch:=description type 4)" and the server responds with a search result entry with a description attribute with only that value, if that value exists.
dn: uid=user.0,ou=People,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson postalAddress: Aaren Atp$01251 Chestnut Street$Panama City, DE 50369 postalCode: 50369 description: This is the description for Aaren Atp. description: description type 1 description: description type 2 description: description type 3 description: description type 4 description: description type 5 description: description type 6 description: description type 7 description: description type 8 description: description type 9 description: description type 10 uid: user.0 employeeNumber: 998 initials: ASA givenName: Aaren pager: +1 779 041 6341 mobile: +1 010 154 3228 cn: Aaren Atp sn: Atp telephoneNumber: +1 685 622 6202 street: 01251 Chestnut Street homePhone: +1 225 216 5900 l: Panama City mail: user.0@maildomain.net mail: This is the new attribute value. st: DE
Execute the example
java -cp YOUR_CLASSPATH \ samplecode.MatchedValuesRequestControlExample \ --attribute description \ --baseObject uid=user.0,ou=people,dc=example,dc=com \ --bindDn uid=user.0,ou=people,dc=example,dc=com \ --bindPasswordFile /Users/terrygardner/.pwdFile \ --hostname ldap.example.com \ --matchedValuesFilter "(description:caseExactMatch:=description type 4)" \ --port 1389 \ --scope base
The use of the extensible match filter is not strictly necessary, "(description=description type 4)" would have worked also, since the case matches. The matched values filter supports extensible match filters, but cannot contain a DN argument component.
On my system, this outputs:
[07/Dec/2011:13:29:56 -0500] Connected to LDAP server.
[07/Dec/2011:13:29:56 -0500] MatchedValuesRequestControl is supported.
[07/Dec/2011:13:29:56 -0500] SearchResultEntry(dn='uid=user.0,ou=People,dc=example,dc=com',
messageID=3, attributes={Attribute(name=description,
values={'description type 4'})}, controls={})
[07/Dec/2011:13:29:56 -0500] MatchedValuesRequestControlExample
has completed processing. The result code was: 0 (success)
From the command line with the ldapsearch tool
ldapsearch -D 'uid=user.0,ou=people,dc=example,dc=com' \ -j ~/.pwdFile -p 1389 -b dc=example,dc=com \ --matchedValuesFilter 'description=description type 4' \ '(uid=user.0)' dn: uid=user.0,ou=People,dc=example,dc=com description: description type 4
If you are still using the old OpenLDAP ldapsearch tool, it also support the matched values request control with a slightly different syntax:
/usr/bin/ldapsearch -LLLx -D 'uid=user.0,ou=people,dc=example,dc=com' \ -W -H ldap://ldap.example.com:1389 \ -b dc=example,dc=com \ -E mv='(description:caseExactMatch:=description type 4)' \ '(uid=user.0)' Enter LDAP Password: dn: uid=user.0,ou=People,dc=example,dc=com description: description type 4
The Simple Paged Results Request Control provides LDAP clients with a means to view sequential data at a rate controlled by the client, but it’s limited by the fact that clients can only scroll through pages in order. The Virtual List View Request Control, currently in draft form at the IETF, provides a way for LDAP clients to scroll through results from an arbitrary point in in the result set. Use of the Virtual List View Request Control requires the Server Side Sort Request Control with at least one sort key. The UnboundID Directory Server supports the virtual list view request control.
As always when working with request controls, features, and extensions, programmers must check that the object identifier is listed in the root DSE, and server administrators must allow the controls to be used by the authorization id.
Object identifiers:
- Simple Paged Results Request Control:
1.2.840.113556.1.4.319 - Virtual List View Request Control:
2.16.840.1.113730.3.4.9 - Server Side Sort Request Control:
1.2.840.113556.1.4.473
Check the root DSE using the command line tool:
/usr/bin/ldapsearch -xLLLH ldap://localhost:1389 \ -b '' -s base '(&)' supportedControl | \ perl -lane 'print if /1.2.840.113556.1.4.319/ or /2.16.840.1.113730.3.4.9/ or /1.2.840.113556.1.4.473/' supportedControl: 1.2.840.113556.1.4.319 supportedControl: 1.2.840.113556.1.4.473 supportedControl: 2.16.840.1.113730.3.4.9
VirtualListViewDemo.java is a demonstration of the use of the Virtual List View Request Control and Response Control in Java using the UnboundID LDAP SDK.
There are two channels in which UnboundID products are discussed on IRC at irc.freenode.net: #UnboundID and #UnboundID-LDAP-SDK.
