This section contains general information that is helpful to understand before you begin developing with the LDAP Classes for Java. This section contains information on LDAP connections, asynchronous and synchronous methods, constraints, LDAP messages, and LDAP URLs.
The central LDAP class is an LDAPConnection. This class provides methods to establish an authenticated or anonymous connection to an LDAP server, as well as methods to search for, modify, compare, and delete entries in the directory.
The following code demonstrates the use of an LDAPConnection object to connect to an LDAP server:
String MY_HOST = "localhost"; int MY_PORT = 389; LDAPConnection ld = new LDAPConnection(); ld.connect(MY_HOST, MY_PORT);
These four lines use the LDAPConnection object to create an anonymous connection to the LDAP server specified by MY_HOST, and the port specified by MY_PORT. At this point, you may authenticate to the server using the bind method, or perform another operation.
The LDAP connection can also be created when the socket connect timeout value is passed as a parameter to the LDAPConnection constructor. And this parameter value has to be specified in MILLISECONDS.This sets the underlying socket connect timeout value to the passed in parameter. The constructor takes the value as an integer and an exception is thrown if the connection is not alive for the specified time (in milliseconds).
The following code demonstrates the use of an LDAPConnection object to connect to an LDAP server using the LDAPConnection constructor, which sets the socket connect timeout to 20 seconds (20000 milliseconds) and connect to MY_HOST. The exception will be thrown if the connection to MY_HOST is not alive for 20 seconds.
int MY_SOCKET_TIMEOUT = 20000; LDAPConnection ld = new LDAPConnection(MY_SOCKET_TIMEOUT); ld.connect(MY_HOST, MY_PORT);
The LDAPConnection class also provides methods for managing settings that are specific to the LDAP session (such as limits on the number of results returned or time-out limits). An LDAPConnection object can be cloned, allowing objects to share a single network connection in a thread-safe manner. For a complete list of the methods and values available from LDAPConnection, see the JavaDoc API Reference.
Blocking versus Non-Blocking: The LDAP protocol provides both synchronous and asynchronous functions. For the synchronous search methods you can set the batch size parameter for functionality similar to the asynchronous search methods.
Asynchronous functions do not block, they return immediately after initiating the operation. One of the Listener class functions is used to retrieve the results.
Asynchronous functions return either an LDAPResponseListener or an LDAPSearchListener object and optionally may take a listener object as input. Several asynchronous operations may be tied to the same listener object.
Synchronous functions with batch size of zero block until all the results have been received from the server. Synchronous search functions with batch size = n: (non-zero) Block until “n” messages have been received from the server, then let enumeration proceed while queueing additional messages.
The default value of the batch size parameter is 1. Thus by default, an enumeration of search results from a synchronous search operation will return messages as they are received from the server. The enumeration will block if no messages are waiting.
Other differences between asynchronous and synchronous operations are detailed in the operation-specific sections, such as exception handling and referral handling.
The Sample Code contains both asynchronous and synchronous programs.
Usually when you are just getting started, your application does not require a secure connection. By default, an anonymous connection is made when you connect to the LDAP server.
If you wish to authenticate to perform an operation that requires more than anonymous access, use the LDAPConnection.bind method.
ld.bind(loginDN, loginPW);
Passing NULL or “” for the loginDN will authenticate anonymously.
The LDAP Classes for Java support SASL mechanisms for authentication. The SASL mechanisms supported are simple, Digest-MD5, NMAS_LOGIN and EXTERNAL.
Before you can make a non-encrypted connection, the LDAP server must be configured to allow clear-text passwords. For information on setting this option see documentation for the LDAP Group Object.
LDAP constraints are used to control LDAP operations, allowing you to control the way in which operations are performed. Using constraints you can, for example, enable referral handling, set referral hop limits, and set controls to be sent to the server. For a complete listing of available constraints, see the LDAPConstraints object in the JavaDoc API Reference.
Constraints can be set in one of two ways, depending on the desired behavior:
Connection-based: Constraints set on a connection apply to all operations performed on that connection.
Operation-based: Constraints set on an operation apply only for that operation.
Connection-based constraints are set by creating a constraints object and setting properties for this object using LDAPConstraints methods (for a list see the JavaDoc API Reference). Once these properties are set, the constraints are set for a connection using the LDAPConnection.setConstraints method.
The following is an example using the LDAPConstraints object to set the maximum time a client will wait for an operation to complete. This setting applies for all operations performed on this connection.
LDAPConnection lc = new LDAPConnection();
LDAPConstraints cons = lc.getConstraints();
cons.setTimeLimit(5000);
lc.setConstraints(cons);
Note that we used the LDAPConnection.getConstraints method to initialize the LDAPConstraints object. This retrieves all constraints previously set for this connection, allowing us to add our new constraint without changing the existing constraints.
Operation-based constraints are set by creating a constraints object and setting properties, the same way it is done when setting connection-based constraints. However, instead of setting these constraints on the connection, this constraints object is passed to the method called to perform the operation.
The following is an example using the LDAPConstraints object to set the maximum time a client will wait for a single operation to complete.
LDAPConnection lc = new LDAPConnection();
LDAPConstraints cons = lc.getConstraints();
cons.setTimeLimit(5000);
lc.add(entry, cons);
LDAP URLs provide a uniform method to access information on an LDAP server. Defined in RFC 2255, LDAP URLs begin with the prefix LDAP:// or LDAPS://. The following provides the syntax and descriptions of an LDAP URL.
ldap[s]://<hostname>:<port>/<base_dn>?<attributes>?<scope>?<filter>?<extension>
Note that ldaps is a common enhancement used to denote SSL, and is not defined in an RFC.
Table 1-3 Field descriptions for an LDAP URL
NOTE:An attribute list is required if you want to provide a scope (even if the attribute list is blank). To return all attributes within a specific scope you must include <base_dn>??<scope>.
The SDK provides an LDAPUrl class to handle LDAP URLs. This class has methods to store, parse, and manage LDAP URLs. For more information see the JavaDoc API Reference.
If you receive an LDAPReferralExeption, you can retrieve a list of referral URLs using the LDAPReferralException.getReferrals method. This method returns an array of LDAP URL Strings, which can be converted to LDAPUrls and passed directly to LDAP searches, or can be examined to determine whether or not you wish to follow the referrals. For more information see Referral Exceptions.
The LDAPMessage class represents the base class for LDAP response messages for asynchronous commands.
For all asynchronous operations you are returned a listener object. Methods of this listener object return an LDAPResponse (a subclass of LDAPMessage), which contains the result of the operation (for example, LDAPException.SUCCESS, or LDAPException.INSUFFICIENT_ACCESS_RIGHTS).
When performing an asynchronous search, a number of LDAPMessage objects are returned. These messages can be one of three sub-types:
LDAPSearchResult represents an entry returned from your search.
LDAPSearchResultReference contains a search result reference (referral information) to continue your search.
an LDAPResponse, signals the end of the results.
In your code, you need to determine the message type and handle it appropriately.
For example, you could perform an asynchronous search and receive nine LDAP messages. Seven of these could be LDAPSearchResults, one could be an LDAPSearchResultReference, and the last one is an LDAPResponse. In your code, you set up conditional statements to determine the message type and handle it appropriately. See Asynchronous Methods for more information.