LDAP Classes
Implements Java LDAP

LDAP Classes, Controls, Extensions, and ASN.1

The LDAP Classes for Java allow you to write applications to access, manage, update, and search for information stored in Novell eDirectory and other LDAP-aware directories.

See:
          Description

Packages
com.novell.ldap Provides classes for the Java LDAP methods defined in Internet drafts maintained by IETF.
com.novell.ldap.asn1 The classes provided in this package can be used to encode and decode Abstract Syntax Notation One (ASN.1) object types using BER (Basic Encding Rules).
com.novell.ldap.connectionpool Provides a utility class that manages connections to a single LDAP server.
com.novell.ldap.controls Provides classes for using LDAP controls.
com.novell.ldap.events Provides classes for LDAP Events notification when connected to a LDAP V3 Server.
com.novell.ldap.events.edir Provides classes for Edirectory Events notification when connected to a LDAP V3 Server.
com.novell.ldap.events.edir.eventdata  
com.novell.ldap.extensions Provides classes for using the Novell LDAP extensions that manage replicas, naming contexts, and the synchronization of replicas and the schema.
com.novell.ldap.util Provides utility classes for use by LDAP applications.
com.novell.security.sasl Provides customized Client classes for the Java SASL API as defined in JSR28 - Java SASL Specification.

 

The LDAP Classes for Java allow you to write applications to access, manage, update, and search for information stored in Novell eDirectory and other LDAP-aware directories.

Readme

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


License and Copyright

This product is distributed under terms of the OpenLDAP License version 2.0.1, and is subject to OpenLDAP and Novell Copyrights.


Sample code

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



Introduction

The LDAP classes are 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 classes.

Overview of the LDAP model

LDAP is the lightweight directory access protocol, described in RFC2251 and RFC2252. 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 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). The LDAP classes offer 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 API implementation follow the referrals automatically. 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 the LDAP classes

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.


    LDAP Classes
    Implements Java LDAP

    Copyright © 2002 Novell, Inc. All Rights Reserved.
    Novell, Inc.
    1800 South Novell Place
    Provo, Ut 84606
    Phone: (801) 861-5000