Java LDAP Overview

The LDAP Class Libraries for Java (JLDAP) allow you to write applications to access, manage, update, and search for information stored in directories accessible using LDAPv3.

README

See the README for information about dependencies, installation notes, and SSL integration.

README

Sample code

The LDAP Class Libraries for Java contain a number of samples demonstrating common operations. These samples are available on the Novell Developer Kit.

Java LDAP Sample Code

Introduction

JLDAP is designed to provide powerful, yet simple, access to LDAP directory services. This API defines both asynchronous and synchronous interfaces to LDAP to suit a wide variety of applications. This document gives a brief overview of the LDAP model, then an overview of the constituents of the class library.

Overview of the LDAP model

LDAP is the lightweight directory access protocol, described in RFC 2251-2256,2829-2830. It defines a lightweight access mechanism in which clients send requests to and receive responses from LDAP servers.

The LDAP information model comes from X.500 and is based on the entry, which contains information about some object (e.g., a person). Entries are composed of attributes, which have a type and one or more values. Each attribute has a syntax that determines what kinds of values are allowed in the attribute (e.g., ASCII characters, a jpeg photograph, etc.) and how those values behave during directory operations (e.g., is case significant during comparisons).

Entries may be organized in a tree structure, usually based on political, geographical, and organizational boundaries. Other structures are possible, including a flat namespace. Each entry is uniquely named relative to its sibling entries by its relative distinguished name (RDN) consisting of one or more distinguished attribute values from the entry. At most one value from each attribute may be used in the RDN. For example, the entry for the person Babs Jensen might be named with the "Barbara Jensen" value from the CN (commonName) attribute.

A globally unique name for an entry, called a distinguished name or DN, is constructed by concatenating the sequence of RDNs from the entry up to the root of the tree. For example, if Babs worked for the University of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,o=University of Michigan,c=US". The DN format used by LDAP is defined in RFC2253.

Operations are provided to authenticate, search for and retrieve information, modify information, and add and delete entries from the tree.

An LDAP server may return referrals if it cannot completely service a request (for example if the request specifies a directory base outside of the tree managed by the server). JLDAP offers the programmer three options: the programmer can catch these referrals as exceptions and explicitly issue new requests to the referred-to servers, the programmer can provide an object to establish a new connection to a referred-to server, or the programmer can let the library automatically follow the referrals. In the latter case, the programmer may also provide a reauthentication object, allowing automatic referrals to proceed with appropriate credentials. If no such object is provided, referrals are followed with anonymous credentials, and the protocol level of the original connection is used. If the original connection used a socket factory or TLS, the referral connection will use the same.

Before the client encodes and sends a string value to a server, the string values are converted from the Java 16-bit Unicode format to UTF-8 format, which is the standard string encoding for LDAPv3 servers. The integrity of double-byte and other non-ASCII character sets is fully preserved.

Overview of JLDAP

The central LDAP class is LDAPConnection. It 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 LDAPConnection class also provides fields for storing settings that are specific to the LDAP session (such as limits on the number of results returned or timeout limits). An LDAPConnection object can be cloned, allowing objects to share a single network connection but use different settings (using LDAPConstraints or LDAPSearchConstraints).

A synchronous search conducted by an LDAPConnection object returns results in an LDAPSearchResults object, which can be enumerated to access the entries found. Each entry (represented by an LDAPEntry object) provides access to the attributes (represented by LDAPAttribute objects) returned for that entry. Each attribute can produce the values found as byte arrays or as Strings.

The LDAP asynchronous methods

The LDAP protocol provides synchronous as well as asynchronous directory access methods. All asynchronous methods return listener objects (either LDAPResponseListener or LDAPSearchListener) and also take a listener object as input. The listener is a message queue associated with the request, and it is the responsibility of the client to read messages out of the queue and process them.

Messages retrieved from an LDAPResponseListener are result objects derived from LDAPResponse. Messages retrieved from an LDAPSearchListener are either result objects derived from LDAPResponse, search results, or search result references.

An asynchronous search conducted by an LDAPConnection object returns results via the getResponse method of the LDAPSearchListener returned by the search operation. The getResponse method typically returns an LDAPSearchResult object which has a getEntry method 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.

Overview of LDAP API Use

An application generally uses the LDAP API in four steps.

Construct an LDAPConnection. Initialize an LDAP session with a directory server. The LDAPConnection.connect() call establishes a handle to the session, allowing multiple sessions to be open at once, on different instances of LDAPConnection.
Authenticate to the LDAP server with LDAPConnection.bind().
Perform some LDAP operations and obtain some results. The synchronous version of LDAPConnection.search() returns an LDAPSearchResults which can be enumerated to access all entries found. The asynchronous version of LDAPConnection.search() returns an LDAPSearchListener, which is used to read the results of the search. LDAPConnection.read() returns a single entry.
Close the connection. The LDAPConnection.disconnect() call closes the connection.

There are both synchronous and asynchronous versions of the LDAP protocol operations in this API. Synchronous methods do not return until the operation has completed.

Asynchronous methods take a listener parameter (either LDAPResponseListener or LDAPSearchListener) and return a listener object which is used to enumerate the responses from the server. A loop is typically used to read from the listener object, which blocks until there is a response available, until the operation has completed.

An LDAPResponseListener may 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.

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. Standard Java Enumerations are used to parse synchronous search results.

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 MAY be thread-safe and the implementor MUST indicate which classes and methods are thread-safe.