LDAP SDK for Java

Performing LDAP Operations

LDAPConnection objects provide a number of methods for processing operations against an LDAP directory server. This document provides basic information about processing such operations.

Operation Requests

The LDAPConnection object provides a number of convenience methods for processing different types of operations, but for each operation there is also a method that takes an LDAPRequest subclass (e.g., AddRequest for add operations, BindRequest for bind operations, etc.). In most cases, these request objects are mutable and can be altered and re-used across multiple requests. This makes it possible, for example, to construct a search request for a common type of request that the application needs to make, and simply alter the filter and re-send the updated request without the need to create a completely new request object.

Using request objects also provides a greater set of options than the most commonly-used options provided through the methods in the LDAPConnection class. In particular, it is possible to include controls in these requests, which is not available with the other methods used to request operations in the LDAPConnection class, and you can also use it to specify a timeout for the operation that differs from the default timeout specified in the associated connection options. Further, it is necessary to use these request objects if you wish to process asynchronous operations. Note, however, that request objects themselves are not threadsafe and therefore a single request object should not be used to process multiple concurrent operations.

Operation Results

All operations listed below other than those in the "Other Convenience Methods" section return an LDAPResult object (or one of its subclasses), which includes the following information:

• The LDAP result code for the operation.
• The matched DN string (if one was provided)
• A diagnostic message providing additional information about the result (if one was provided)
• The referral URLs (if any were provided)
• The response controls for the operation (if any were provided)

When processing synchronous operations (which is the case for all operations described on this page), the LDAP SDK will only return an LDAPResult object when the operation completes successfully. For operations that do not complete successfully, it will instead throw an LDAPException. LDAPException objects include all of the same elements as an LDAPResult object, so all of the above information will still be available. The added benefit of throwing an exception in this case, however, is that it eliminates the need for the caller to have to explicitly check the result code of the operation to determine if it was successful.

The types of result that may be returned include:

• Add, delete, modify, and modify DN operations return simple LDAPResult objects.
• Bind operations return BindResult objects, which may include an optional server SASL credentials element.
• Compare operations return CompareResult objects, which provide a convenience method for indicating whether the compare assertion matched the target entry.
• Extended operations return ExtendedResult objects, which may include a response OID and/or value. Subclasses for specific types of extended operations may provide other methods for accessing the content of the response.
• Search operations return SearchResult objects, which include the number of entries and referrals returned, and may also hold the returned entries and/or references.

Processing Search Operations

Search operations differ from other types of LDAP operations in that there may be multiple responses to a single request. In addition to the search result done message, each entry and reference is returned in a separate message. As a result, processing such operations in the LDAP SDK is somewhat different than for other operations.

There are two basic ways to perform search operations in the UnboundID LDAP SDK for Java. One approach, which works for all types of searches, is to use the SearchResultListener interface. If a search request includes a reference to a SearchResultListener, then its searchEntryReturned method will be called for each entry returned from the server. Further, if the server returns referrals as part of the search operation and the connection is not configured to automatically follow referrals, then the listener's searchReferenceReturned method will be called so that the referral can be handled.

If no SearchResultListener is provided as part of the search request, then the SDK will collect all search result entries and references and include them in the SearchResult object that is returned from the search. This is significantly more convenient, but does introduce a risk of running out of available memory on the client if a search matches a very large number of entries. If a search request may cause the server to return a large number of entries, then it should use a SearchResultListener to process the entries as they are returned rather than attempting to collect them all in memory until the search is complete.

Other Convenience Methods

In addition to methods that may be used for performing standard LDAP operations, the LDAPConnection class provides methods that may be useful when interacting with the server.

If you wish to retrieve a single entry from the server and you know the DN of that entry, then you could use a search operation to retrieve that entry, but you may also use one of the getEntry methods. These methods allow you to specify just the DN of the entry (and optionally a set of attributes to include in the entry) and will return the requested entry if it exists.

The directory server's root DSE is a special entry with a zero-length DN that provides information about the capabilities of the server. This may include information like the base DNs for data in the directory, supported controls and extended operations, and product version information. The LDAPConnection class provides a getRootDSE method that may be used to retrieve and parse the server root DSE.

The directory server also publishes schema information about the attribute types, object classes, syntaxes, and other schema elements that it supports. The getSchema method may be used to retrieve a Schema object that includes parsed versions of the server schema elements so that the client can determine the types of information that may be stored in the directory.