The LDAP protocol provides synchronous as well as asynchronous directory access methods.
Synchronous methods do not return until the operation has completed. To facilitate user feedback during synchronous searches, intermediate search results can be obtained before the entire search operation is completed by specifying the number of entries to return at a time.
Asynchronous methods take a MessageQueue parameter (either LdapResponseQueue or LDAPSearchQueue) and return a MessageQueue object which is used to enumerate the responses from the server. MessageQueue is associated with the request, and it is the responsibility of the client to read the messages from the queue and process them. A loop is typically used to read from the MessageQueue object, which blocks until there is a response available, until the operation has completed.
|
Messages Retrieved From |
Result Objects Derived From |
|---|---|
|
LdapResponseQueue |
LdapResponse |
|
LdapSearchQueue |
LdapResponse, search results, or search result references. |
An LdapResponseQueue can be shared between operations, for multiplexing the results. In this case, the object returned on one operation is passed in to one or more other operations, rather than passing in null.
For the asynchronous methods, exceptions are raised only for connection errors. LDAP result messages are converted into LdapResponse objects, which are to be checked by the client for errors and referrals, whereas, the synchronous methods throw an LdapException on result codes other than 0.
An asynchronous search conducted by an LdapConnection object returns results through the getResponse method of the LdapSearchQueue returned by the search operation. The getResponse method typically returns an LdapSearchResult object which has an Entry Property that returns the LdapEntry that represents the search entry.
None of the ancillary asynchronous classes are intended to be instantiated by a client, so they lack public constructors.
Errors result in the throwing of an LdapException, with a specific error code and context-specific textual information available.
If null is passed as the value of an LdapConstraints or LdapSearchConstraints parameter to an operation, the default constraints are used for that operation.
If null is passed as the value of a DN to an operation it is treated as if it was the empty string.
The API doesn’t distinguish between LDAP search continuation references and LDAP referrals, presenting a unified interface to the client for handling the two.
Implementations of the API must ensure that the LdapConnection class is thread-safe. Other classes and methods can be thread-safe and the implementor must indicate which classes and methods are thread-safe.