Network Working Group                                        Rob Weltman
INTERNET-DRAFT                                             Coscend Corp.
Intended Category: Standards Track                   Christine Tomlinson
                                                  Sun Microsystems, Inc.
                                                           Miodrag Kekic
                                           Netscape Communications Corp.
                                                          Steven Sonntag
                                                            Novell, Inc.
                                                         Jim Sermersheim
                                                            Novell, Inc.
                                                              Mark Smith
                                           Netscape Communications Corp.
                                                               Tim Howes
                                                         Loudcloud, Inc.
                                                               June 2001


               The Java LDAP Application Program Interface
                  draft-ietf-ldapext-ldap-java-api-15.txt


Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Task Force
   (IETF), its areas, and its working groups.  Note that other groups
   may also distribute working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.



Abstract

   This document defines a Java [JAVA] language application program
   interface to the Lightweight Directory Access Protocol (LDAP)
   [LDAPv3], in the form of a class library.


Conventions Used in this Document

   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"

Expires December, 2001                                        [Page 1]


JAVA LDAP API                                                June 2001


   in this document are to be interpreted as defined in "Key words for
   use in RFCs to Indicate Requirement Levels" [KEYWORDS].



















































Expires December, 2001                                        [Page 2]


JAVA LDAP API                                                June 2001


1. Overview...........................................................10
1.1 The LDAP model....................................................10
1.2 The LDAP classes..................................................11
1.3 The LDAP asynchronous methods.....................................12
1.4 Interfaces........................................................12
1.5 Classes...........................................................13
1.6 Exceptions........................................................16
1.7 LDAP API use......................................................16
2. The Java LDAP classes..............................................18
2.1 public class LDAPAttribute........................................18
2.1.1 Constructors....................................................18
2.1.2 addValue........................................................19
2.1.3 getBaseName.....................................................19
2.1.4 getByteValues...................................................19
2.1.5 getByteValueArray...............................................20
2.1.6 getLangSubtype..................................................20
2.1.7 getName.........................................................20
2.1.8 getStringValueArray.............................................20
2.1.9 getStringValues.................................................20
2.1.10 getSubtypes....................................................20
2.1.11 hasSubtype.....................................................21
2.1.12 hasSubtypes....................................................21
2.1.13 removeValue....................................................21
2.1.14 size...........................................................22
2.2 public class LDAPAttributeSchema..................................22
2.2.1 Constructors....................................................22
2.2.2 getEqualityMatchingRule.........................................23
2.2.3 getOrderingMatchingRule.........................................24
2.2.4 getSuperior.....................................................24
2.2.5 getSubstringMatchingRule........................................24
2.2.6 getSyntaxString.................................................24
2.2.7 getUsage........................................................24
2.2.8 isCollective....................................................24
2.2.9 isUserModifiable................................................25
2.2.10 isSingleValued.................................................25
2.2.11 Constants of LDAPAttributeSchema...............................25
2.3 public class LDAPAttributeSet.....................................25
2.3.1 Constructors....................................................25
2.3.2 add.............................................................26
2.3.3 clone...........................................................26
2.3.4 elementAt.......................................................26
2.3.5 getAttribute....................................................26
2.3.6 getAttributes...................................................27
2.3.7 getSubset.......................................................28
2.3.8 remove..........................................................28
2.3.9 removeElementAt.................................................29
2.3.10 size...........................................................29
2.4 public interface LDAPBind.........................................29
2.4.1 bind............................................................29
2.5 public class LDAPCompareAttrNames.................................30
2.5.1 Constructors....................................................30
2.5.2 getLocale.......................................................31

Expires December, 2001                                        [Page 3]


JAVA LDAP API                                                June 2001


2.5.3 isGreater.......................................................31
2.5.4 setLocale.......................................................31
2.6 public class LDAPConnection.......................................31
2.6.1 Constructors....................................................32
2.6.2 abandon.........................................................32
2.6.3 add.............................................................33
2.6.4 addUnsolicitedNotificationListener..............................34
2.6.5 bind............................................................34
2.6.6 clone...........................................................37
2.6.7 compare.........................................................38
2.6.8 connect.........................................................39
2.6.9 delete..........................................................40
2.6.10 disconnect.....................................................40
2.6.11 extendedOperation..............................................41
2.6.12 finalize.......................................................41
2.6.13 getAuthenticationDN............................................41
2.6.14 getAuthenticationMethod........................................42
2.6.15 getConstraints.................................................42
2.6.16 getHost........................................................42
2.6.17 getInputStream.................................................42
2.6.18 getOutputStream................................................42
2.6.19 getPort........................................................43
2.6.20 getProperty....................................................43
2.6.21 getProtocolVersion.............................................44
2.6.22 getResponseControls............................................44
2.6.23 getSaslBindCallbackHandler.....................................44
2.6.24 getSaslBindProperties..........................................44
2.6.25 getSearchConstraints...........................................44
2.6.26 getSocketFactory...............................................45
2.6.27 isBound........................................................45
2.6.28 isConnected....................................................45
2.6.29 isTLS..........................................................45
2.6.30 modify.........................................................45
2.6.31 read...........................................................47
2.6.32 removeUnsolicitedNotificationListener..........................48
2.6.33 rename.........................................................48
2.6.34 search.........................................................50
2.6.35 setConstraints.................................................52
2.6.36 setInputStream.................................................52
2.6.37 setOutputStream................................................52
2.6.38 setProperty....................................................53
2.6.39 setSocketFactory...............................................53
2.6.40 startTLS.......................................................53
2.6.41 Constants of LDAPConnection....................................54
2.7 public class public class LDAPConstraints.........................54
2.7.1 Constructors....................................................54
2.7.2 getClientControls...............................................55
2.7.3 getHopLimit.....................................................55
2.7.4 getReferralFollowing............................................55
2.7.5 getServerControls...............................................56
2.7.6 getTimeLimit....................................................56
2.7.7 setClientControls...............................................56

Expires December, 2001                                        [Page 4]


JAVA LDAP API                                                June 2001


2.7.8 setHopLimit.....................................................56
2.7.9 setReferralFollowing............................................56
2.7.10 setReferralHandler.............................................57
2.7.11 setServerControls..............................................57
2.7.12 setTimeLimit...................................................57
2.8 public class LDAPControl..........................................58
2.8.1 Constructors....................................................58
2.8.2 clone...........................................................58
2.8.3 getID...........................................................58
2.8.4 getValue........................................................58
2.8.5 isCritical......................................................58
2.8.6 register........................................................59
2.8.7 setValue........................................................59
2.9 public class LDAPDITContentRuleSchema.............................59
2.9.1 Constructors....................................................59
2.9.2 getAuxiliaryClasses.............................................61
2.9.3 getOptionalAttributes...........................................61
2.9.4 getPrecludedAttributes..........................................61
2.9.5 getRequiredAttributes...........................................61
2.10 public class LDAPDITStructureRuleSchema..........................61
2.10.1 Constructors...................................................61
2.10.2 getNameForm....................................................62
2.10.3 getRuleID......................................................62
2.10.4 getSuperiors...................................................63
2.11 public class LDAPDN..............................................63
2.11.1 equals.........................................................63
2.11.2 escapeRDN......................................................63
2.11.3 explodeDN......................................................64
2.11.4 explodeRDN.....................................................64
2.11.5 isValid........................................................64
2.11.6 normalize......................................................64
2.11.7 unescapeRDN....................................................65
2.12 public class LDAPEntry...........................................65
2.12.1 Constructors...................................................65
2.12.2 getAttribute...................................................66
2.12.3 getAttributeSet................................................66
2.12.4 getDN..........................................................66
2.13 public interface LDAPEntryComparator.............................67
2.13.1 isGreater......................................................67
2.14 public class LDAPException.......................................67
2.14.1 Constructors...................................................67
2.14.2 errorCodeToString..............................................68
2.14.3 getCause.......................................................69
2.14.4 getLDAPErrorMessage............................................69
2.14.5 getLDAPResultCode..............................................69
2.14.6 getMatchedDN...................................................69
2.14.7 toString.......................................................69
2.14.8 Result codes...................................................70
2.15 public class LDAPExtendedOperation...............................71
2.15.1 Constructors...................................................71
2.15.2 getID..........................................................71
2.15.3 getValue.......................................................72

Expires December, 2001                                        [Page 5]


JAVA LDAP API                                                June 2001


2.15.4 setValue.......................................................72
2.16 public class LDAPExtendedResponse................................72
2.16.1 getID..........................................................72
2.16.2 getValue.......................................................72
2.17 public interface LDAPListener....................................72
2.17.1 getMessageIDs..................................................72
2.17.2 getResponse....................................................73
2.17.3 isResponseReceived.............................................73
2.17.4 merge..........................................................74
2.18 public class LDAPMatchingRuleSchema..............................74
2.18.1 Constructors...................................................74
2.18.2 getAttributes..................................................75
2.18.3 getSyntaxString................................................75
2.19 public class LDAPMatchingRuleUseSchema...........................75
2.19.1 Constructors...................................................75
2.19.2 getAttributes..................................................76
2.20 public class LDAPMessage.........................................76
2.20.1 getControls....................................................76
2.20.2 getMessageID...................................................77
2.20.3 getType........................................................77
2.21 public class LDAPModification....................................77
2.21.1 Constructors...................................................77
2.21.2 getAttribute...................................................78
2.21.3 getOp..........................................................78
2.21.4 Constants of LDAPModification..................................78
2.22 public class LDAPModificationSet.................................78
2.22.1 Constructors...................................................78
2.22.2 add............................................................79
2.22.3 elementAt......................................................79
2.22.4 remove.........................................................79
2.22.5 removeElementAt................................................79
2.22.6 size...........................................................80
2.23 public class LDAPNameFormSchema..................................80
2.23.1 Constructors...................................................80
2.23.2 getObjectClass.................................................81
2.23.3 getOptionalNamingAttributes....................................81
2.23.4 getRequiredNamingAttributes....................................81
2.24 public class LDAPObjectClassSchema...............................81
2.24.1 Constructors...................................................82
2.24.2 getOptionalAttributes..........................................83
2.24.3 getRequiredAttributes..........................................83
2.24.4 getSuperiors...................................................83
2.24.5 getType........................................................83
2.25 public interface LDAPRebind......................................83
2.25.1 getRebindAuthentication........................................83
2.26 public class LDAPRebindAuth......................................84
2.26.1 Constructors...................................................84
2.26.2 getDN..........................................................84
2.26.3 getPassword....................................................84
2.27 public class LDAPReferralException...............................85
2.27.1 Constructors...................................................85
2.27.2 getFailedReferral..............................................86

Expires December, 2001                                        [Page 6]


JAVA LDAP API                                                June 2001


2.27.3 getReferrals...................................................86
2.27.4 setFailedReferral..............................................86
2.28 public interface LDAPReferralHandler.............................86
2.29 public class LDAPResponse........................................86
2.29.1 getErrorMessage................................................86
2.29.2 getMatchedDN...................................................87
2.29.3 getReferrals...................................................87
2.29.4 getResultCode..................................................87
2.30 public class LDAPResponseListener................................87
2.30.1 getMessageIDs..................................................87
2.30.2 getResponse....................................................87
2.30.3 isResponseReceived.............................................88
2.30.4 merge..........................................................88
2.31 public class LDAPSchema..........................................88
2.31.1 Constructors...................................................88
2.31.2 fetchSchema....................................................89
2.31.3 getAttribute...................................................89
2.31.4 getAttributeNames..............................................89
2.31.5 getAttributes..................................................89
2.31.6 getDITContentRule..............................................90
2.31.7 getDITContentRuleNames.........................................90
2.31.8 getDITContentRules.............................................90
2.31.9 getDITStructureRule............................................90
2.31.10 getDITStructureRuleNames......................................90
2.31.11 getDITStructureRules..........................................91
2.31.12 getMatchingRule...............................................91
2.31.13 getMatchingRuleNames..........................................91
2.31.14 getMatchingRules..............................................91
2.31.15 getMatchingRuleUse............................................91
2.31.16 getMatchingRuleUseNames.......................................91
2.31.17 getMatchingRuleUses...........................................92
2.31.18 getNameForm...................................................92
2.31.19 getNameFormNames..............................................92
2.31.20 getNameForms..................................................92
2.31.21 getObjectClass................................................92
2.31.22 getObjectClasses..............................................92
2.31.23 getObjectClassNames...........................................93
2.31.24 getSyntax.....................................................93
2.31.25 getSyntaxes...................................................93
2.32 public abstract class LDAPSchemaElement..........................93
2.32.1 add............................................................93
2.32.2 getAliases.....................................................94
2.32.3 getDescription.................................................94
2.32.4 getName........................................................94
2.32.5 getID..........................................................94
2.32.6 getQualifier...................................................94
2.32.7 getQualifierNames..............................................95
2.32.8 getValue.......................................................95
2.32.9 isObsolete.....................................................95
2.32.10 modify........................................................95
2.32.11 remove........................................................96
2.32.12 setQualifier..................................................96

Expires December, 2001                                        [Page 7]


JAVA LDAP API                                                June 2001


2.33 public class LDAPSearchConstraints...............................96
2.33.1 Constructors...................................................96
2.33.2 getBatchSize...................................................98
2.33.3 getDereference.................................................98
2.33.4 getMaxResults..................................................98
2.33.5 getServerTimeLimit.............................................98
2.33.6 setBatchSize...................................................98
2.33.7 setDereference.................................................99
2.33.8 setMaxResults..................................................99
2.33.9 setServerTimeLimit.............................................99
2.33.10 Constants of LDAPSearchConstraints............................99
2.34 public class LDAPSearchListener.................................100
2.34.1 getMessageIDs.................................................100
2.34.2 getResponse...................................................100
2.34.3 isComplete....................................................100
2.34.4 isResponseReceived............................................101
2.34.5 merge.........................................................101
2.35 public class LDAPSearchResult...................................101
2.35.1 getEntry......................................................101
2.36 public class LDAPSearchResultReference..........................101
2.36.1 getReferrals..................................................102
2.37 public class LDAPSearchResults..................................102
2.37.1 getCount......................................................102
2.37.2 getResponseControls...........................................102
2.37.3 hasMoreElements...............................................102
2.37.4 next..........................................................102
2.37.5 nextElement...................................................103
2.37.6 sort..........................................................103
2.38 public interface LDAPSocketFactory..............................103
2.38.1 makeSocket....................................................103
2.39 public class LDAPSyntaxSchema...................................104
2.39.1 Constructors..................................................104
2.40 public interface LDAPUnsolicitedNotificationListener............105
2.40.1 messageReceived...............................................105
2.41 public class LDAPUrl............................................105
2.41.1 Constructors..................................................105
2.41.2 decode........................................................106
2.41.3 encode........................................................106
2.41.4 getAttributeArray.............................................107
2.41.5 getAttributes.................................................107
2.41.6 getDN.........................................................107
2.41.7 getExtensions.................................................107
2.41.8 getFilter.....................................................107
2.41.9 getHost.......................................................107
2.41.10 getPort......................................................108
2.41.11 getScope.....................................................108
2.41.12 getUrl.......................................................108
3. Implementation Considerations.....................................108
3.1 Client and Server Controls.......................................108
3.2 Referral handling and exceptions.................................109
3.3 Notice of disconnection..........................................111
3.4 Level of compatibility...........................................111

Expires December, 2001                                        [Page 8]


JAVA LDAP API                                                June 2001


3.5 Invalid responses................................................111
3.6 Array Return Values..............................................111
4. Security Considerations...........................................111
5. Acknowledgements..................................................112
6. Bibliography......................................................112
7. Authors' Addresses................................................113
8. Appendix A - Sample java LDAP programs............................115
8.1 Java LDAP programs using synchronous methods.....................115
8.2 Java LDAP programs using asynchronous methods....................121
9. Appendix B - Revision history.....................................126
9.1 Changes from ldap-java-api-14.txt................................126
9.2 Changes from ldap-java-api-13.txt................................127
9.3 Changes from ldap-java-api-12.txt................................128
9.4 Changes from ldap-java-api-11.txt................................129
9.5 Changes from ldap-java-api-10.txt................................132
9.6 Changes from ldap-java-api-09.txt................................133
9.7 Changes from ldap-java-api-08.txt................................134
9.8 Changes from ldap-java-api-07.txt................................134
9.9 Changes from ldap-java-api-06.txt................................134
9.10 Changes from ldap-java-api-05.txt...............................135
9.11 Changes from ldap-java-api-04.txt...............................136
9.12 Changes from ldap-java-api-03.txt...............................136
9.13 Changes from ldap-java-api-02.txt...............................137
9.14 Changes from ldap-java-api-01.txt...............................138





























Expires December, 2001                                        [Page 9]


JAVA LDAP API                                                June 2001


1. Overview

   The LDAP [LDAPv3] class library is designed to provide powerful, yet
   simple, access to LDAP directory services. It 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. The public class
   methods are described in detail, followed by an appendix that
   provides some example code demonstrating the use of the
   classes, and an appendix listing changes from earlier drafts.


1.1 The LDAP model

   LDAP is the Lightweight Directory Access Protocol, described in
   [LDAPv3]. 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 [X500] 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 directory operations act upon these
   values.

   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 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
   Example company, the DN of her entry might be "cn=Barbara
   Jensen,dc=example,dc=com". The DN format used by LDAP is defined in
   [DN].

   Operations are provided to authenticate, search for and retrieve
   information, modify information, and add and delete entries from the
   tree. The protocol is also extensible, allowing operations to be
   extended by "controls" and new "extended" operations to be defined.

   An LDAP server may return referrals or search references if it cannot
   completely service a request (for example if the request specifies a

Expires December, 2001                                       [Page 10]


JAVA LDAP API                                                June 2001


   directory base outside of the tree managed by the server, the server
   may return a referral. If a search request spans multiple servers, it
   may return one or more search references). The LDAP class library
   presents a unified interface for the application to process search
   references and referrals, and generically refers to either in the
   remainder of this document as simply referrals or referral following.
   The API gives the programmer two options to handle referrals: the
   application can receive the referrals and explicitly issue new
   requests to the referred-to servers, or the application can let the
   library automatically follow the referrals. In the latter case
   referrals are followed by default with anonymous credentials using
   the protocol version and socket factory or TLS [TLS][LDAPTLS] of the
   original connection.  If default behavior is not desired, the
   application can instruct the library to follow referrals with an
   authenticated connection by providing a reauthentication object to
   provide credentials for a simple bind. For greater flexibility, the
   application can provide an object that creates and manages the new
   authenticated connection for the API to use when following the
   referral.

   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 many LDAPv3 protocol elements and value
   encodings use. The integrity of double-byte and other non-ASCII
   character sets is fully preserved. If in the future there are
   characters added to Unicode which cannot be represented with Java 16-
   bit Unicode strings, implementations of the Java LDAP API SHOULD
   adopt whatever conventions are introduced into the Java language to
   accommodate the characters.

   The next sections give an overview of how the class library is used
   and detailed descriptions of the LDAP class methods that implement
   all of these functions.


1.2  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, and establish integrity and confidentiality
   protective services.

   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

Expires December, 2001                                       [Page 11]


JAVA LDAP API                                                June 2001


   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.


1.3 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.


1.4 Interfaces


   LDAPEntryComparator        An interface to support arbitrary sorting
                              algorithms for entries returned by a
                              search operation. The basic Java LDAP
                              classes include one implementation:
                              LDAPCompareAttrNames, to sort in
                              ascending order based on one or more
                              attribute names.


   LDAPListener               Common interface for LDAPResponseListener
                              and LDAPSearchListener. Represents a
                              queue of incoming asynchronous messages
                              from the server.


   LDAPRebind                 A programmer desiring to supply
                              credentials to the default
                              reauthentication behavior when
                              automatically following referrals MUST

Expires December, 2001                                       [Page 12]


JAVA LDAP API                                                June 2001


                              implement this interface. If LDAPRebind
                              or LDAPBind are not used, automatically
                              followed referrals and search references
                              will use anonymous authentication.
                              Referrals of any type other than LDAP
                              URLs [LDAPURL] MAY be chased on automatic
                              referral following.


   LDAPBind                   This interface allows a programmer to
                              override the default authentication and
                              reauthentication behavior when
                              automatically following referrals and
                              search references. It is used to specify
                              the authentication mechanism used on
                              automatic referral following.


   LDAPReferralHandler        Interface that is a shared ancestor to
                              LDAPBind and LDAPRebind.


   LDAPSocketFactory          Programmers needing to provide or use
                              specialized socket connections, including
                              Transport Layer Security (TLS) based
                              ones, can provide an object constructor
                              to implement them using this interface.


   LDAPUnsolicitedNotificationListener  Allows a client to be notified
                              when unsolicited messages arrive from a
                              server. Unsolicited messages have a
                              message ID of 0. An implementation of the
                              Java LDAP API SHOULD NOT generate
                              messages with an ID of 0.


1.5 Classes


   LDAPAttribute              Represents the name and values of one
                              attribute of a directory entry.


   LDAPAttributeSchema        Represents a schematic definition of a
                              particular attribute in a particular
                              Directory Server.


   LDAPAttributeSet           A collection of LDAPAttributes.



Expires December, 2001                                       [Page 13]


JAVA LDAP API                                                June 2001


   LDAPCompareAttrNames       An implementation of LDAPEntryComparator,
                              to support sorting of search results by
                              one or more attributes.


   LDAPConnection             The central point for interactions with
                              an LDAP directory.


   LDAPConstraints            Defines options controlling all
                              operations.


   LDAPControl                Sets additional parameters for an LDAP
                              operation, either on the server or on the
                              client.


   LDAPDITContentRuleSchema   Represents a specific DIT content rule in
                              the directory schema.


   LDAPDITStructureRuleSchema Represents a specific DIT structure rule
                              in the directory schema.


   LDAPDN                     A utility class to facilitate composition
                              and decomposition of distinguished names
                              (DNs).


   LDAPEntry                  Represents a single entry in a directory.


   LDAPExtendedOperation      Encapsulates the OID and data associated
                              with the sending or receiving of an
                              extended operation.


   LDAPExtendedResponse       The response returned by an LDAP server
                              on an asynchronous extended operation
                              request. It extends LDAPResponse.

   LDAPMatchingRuleSchema     Represents the schematic definition of a
                              particular matching rule in a particular
                              Directory Server.


   LDAPMatchingRuleUseSchema  Represents a specific matching rule use
                              in the directory schema.



Expires December, 2001                                       [Page 14]


JAVA LDAP API                                                June 2001


   LDAPMessage                Base class for LDAP request and response
                              messages. Subclassed by response messages
                              used in asynchronous operations.

   LDAPModification           A single add/delete/replace operation to
                              an LDAPAttribute.


   LDAPModificationSet        A collection of LDAPModifications.


   LDAPNameFormSchema         Represents a specific name form in the
                              directory schema.


   LDAPObjectClassSchema      Represents the schematic definition of a
                              particular object class in a particular
                              Directory Server.


   LDAPRebindAuth             An implementation of LDAPRebind MUST be
                              able to provide an LDAPRebindAuth at the
                              time of a referral. The class
                              encapsulates reauthentication
                              credentials.


   LDAPResponse               Represents a message received from an
                              LDAP server in response to an
                              asynchronous request. It extends
                              LDAPMessage.


   LDAPResponseListener       Low-level mechanism for processing
                              asynchronous messages received from a
                              server.


   LDAPSchema                 Represents the schema controlling one or
                              more entries held by a particular
                              Directory Server.


   LDAPSchemaElement          Base class for representing LDAP schema
                              elements.


   LDAPSyntaxSchema           Represents a specific syntax definition
                              in the directory schema.




Expires December, 2001                                       [Page 15]


JAVA LDAP API                                                June 2001


   LDAPSearchConstraints      Defines the options controlling search
                              operations.


   LDAPSearchListener         Low-level mechanism for queuing
                              asynchronous search results received from
                              a server.


   LDAPSearchResult           A single search result that is in
                              response to an asynchronous search
                              operation. It extends LDAPMessage.


   LDAPSearchResultReference  A continuation reference from an
                              asynchronous search operation. It extends
                              LDAPMessage.


   LDAPSearchResults          The enumerable results of a search
                              operation.


   LDAPUrl                    Encapsulates parameters of an LDAP Url
                              query, as defined in [LDAPURL].


1.6 Exceptions


   LDAPException         General exception, which includes an error
                         message and an LDAP API local error code or
                         server result code.


   LDAPReferralException Derived from LDAPException and contains a list
                         of URLs corresponding to a single referral or
                         search continuation response received on an
                         LDAP operation.


1.7 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().


Expires December, 2001                                       [Page 16]


JAVA LDAP API                                                June 2001


   -    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 described in this draft. 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, 5, and 6.

   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
   result code and context-specific textual information, if 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.

Expires December, 2001                                       [Page 17]


JAVA LDAP API                                                June 2001



   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.

   The following sections describe the LDAP classes in more detail.


2. The Java LDAP classes


2.1 public class LDAPAttribute

   The LDAPAttribute class represents the name and values of an
   attribute. It is used to specify an attribute to be added to, deleted
   from, or modified in a Directory entry. It is also returned on a
   search of a Directory.


2.1.1 Constructors

   public LDAPAttribute(LDAPAttribute attr)


   Constructs an attribute with copies of all values of the input
   attribute.


   public LDAPAttribute(String attrName)


   Constructs an attribute with no values.


   public LDAPAttribute(String attrName,
                           byte[] attrBytes)

   Constructs an attribute with a byte-formatted value.


   public LDAPAttribute(String attrName,
                           String attrString)

   Constructs an attribute that has a single string value.


   public LDAPAttribute(String attrName,
                        String[] attrStrings)

   Constructs an attribute that has an array of string values.

   Parameters are:

Expires December, 2001                                       [Page 18]


JAVA LDAP API                                                June 2001



      attr           An attribute to use as template.

      attrName       Name of the attribute.

      attrBytes      Value of the attribute as raw bytes.

      attrString     Value of the attribute as a String.

      attrStrings    Array of values as Strings.


2.1.2 addValue

   public void addValue(String attrString)

   Adds a string value to the attribute.


   public void addValue(byte[] attrBytes)

   Adds a byte[]-formatted value to the attribute.

   Parameters are:

      attrString     Value of the attribute as a String.

      attrBytes      Value of the attribute as raw bytes.


2.1.3 getBaseName

   public String getBaseName()

   public static String getBaseName(String attrName)

   Returns the base name. For example, if the attribute name is cn;lang-
   ja;phonetic, this method returns cn.

      attrName       Name of the attribute to extract the base name
                      from.


2.1.4 getByteValues

   public Enumeration getByteValues()

   Returns an enumerator for the values of the attribute in byte[]
   format.




Expires December, 2001                                       [Page 19]


JAVA LDAP API                                                June 2001


2.1.5 getByteValueArray

   public byte[][] getByteValueArray()

   Returns the values of the attribute as an array of byte[].


2.1.6 getLangSubtype

   public String getLangSubtype()

   Returns the language subtype, if any. For example, if the attribute
   name is cn;lang-ja;phonetic, this method returns the String lang-ja.


2.1.7 getName

   public String getName()

   Returns the name of the attribute.


2.1.8 getStringValueArray

   public String[] getStringValueArray()

   Returns the values of the attribute as an array of Strings. This
   method should only be called if the attribute values are known to be
   strings with values restricted to UTF-8. The returned Strings have
   undefined values if the attribute contains values not restricted to
   UTF-8.


2.1.9 getStringValues

   public Enumeration getStringValues()

   Returns an enumerator for the string values of an attribute. This
   method should only be called if the attribute values are known to be
   strings with values restricted to UTF-8. The returned Strings have
   undefined values if the attribute contains values not restricted to
   UTF-8.


2.1.10 getSubtypes

   public String[] getSubtypes()

   public static String[] getSubtypes(String attrName)




Expires December, 2001                                       [Page 20]


JAVA LDAP API                                                June 2001


   Extracts the subtypes from the specified attribute name. For example,
   if the attribute name is cn;lang-ja;phonetic, this method returns an
   array containing lang-ja and phonetic.

   Parameters are:

      attrName       Name of the attribute to extract the subtypes
                      from.


2.1.11 hasSubtype

   public boolean hasSubtype(String subtype)

   Reports if the attribute name contains the specified subtype. For
   example, if you check for the subtype lang-en and the attribute name
   is cn;lang-en, this method returns true.

   Parameters are:

      subtype        The single subtype to check for.


2.1.12 hasSubtypes

   public boolean hasSubtypes(String[] subtypes)

   Reports if the attribute name contains all specified subtypes. For
   example, if you check for the subtypes lang-en and phonetic and if
   the attribute name is cn;lang-en;phonetic, this method returns true.
   If the attribute name is cn;phonetic or cn;lang-en, this method
   returns false.

   Parameters are:

      subtypes       An array of subtypes to check for.


2.1.13 removeValue

   public void removeValue(String attrString)

   Removes a string value from the attribute.


   public void removeValue(byte[] attrBytes)

   Removes a byte[]-formatted value from the attribute.

   Parameters are:

      attrString     Value of the attribute as a String.

Expires December, 2001                                       [Page 21]


JAVA LDAP API                                                June 2001



      attrBytes      Value of the attribute as raw bytes.


2.1.14 size

   public int size()

   Returns the number of values of the attribute.


2.2 public class LDAPAttributeSchema
                 extends LDAPSchemaElement

   The LDAPAttributeSchema class represents the definition of an
   attribute. It is used to query attribute syntax, and to add or delete
   an attribute definition in a Directory. See [ATTR] for a description
   of attribute representation in LDAP.


2.2.1 Constructors

   public LDAPAttributeSchema(String name,
                              String oid,
                              String description,
                              String syntaxString,
                              boolean single
                              String superior,
                              String[] aliases,
                              boolean obsolete,
                              String equality,
                              String ordering,
                              String substring,
                              boolean collective,
                              boolean userMod,
                              int usage)

   Constructs an attribute definition for adding to or deleting from a
   Directory.


   public LDAPAttributeSchema(String raw)

   Constructs an attribute definition from the raw String value returned
   on a Directory query for "attributetypes".


   Parameters are:

      name           Name of the attribute.



Expires December, 2001                                       [Page 22]


JAVA LDAP API                                                June 2001


      oid            Object Identifier of the attribute - in dotted-
                      decimal format.

      description    Optional description of the attribute.

      syntaxString   Object Identifier of the syntax of the attribute
                      - in dotted-decimal format.

      single         true if the attribute is to be single-valued.

      superior       Optional name of the attribute type which this
                      attribute type derives from; null if there is no
                      superior attribute type.

      aliases        Optional list of additional names by which the
                      attribute may be known; null if there are no
                      aliases.

      obsolete       true if this attribute is obsolete.

      equality       Object Identifier of the equality matching rule
                      for the attribute - in dotted-decimal format; MAY
                      be null.

      ordering       Object Identifier of the ordering matching rule
                      for the attribute - in dotted-decimal format; MAY
                      be null.

      substring      Object Identifier of the substring matching rule
                      for the attribute - in dotted-decimal format; MAY
                      be null.

      collective     true if this is a collective attribute.

      userMod        true if the attribute is modifiable by users.

      usage          One of the following:

                     USER_APPLICATIONS
                     DIRECTORY_OPERATION
                     DISTRIBUTED_OPERATION
                     DSA_OPERATION

      raw            The raw String value returned on a Directory
                      query for "attributetypes".



2.2.2 getEqualityMatchingRule

   public String getEqualityMatchingRule ()


Expires December, 2001                                       [Page 23]


JAVA LDAP API                                                June 2001


   Returns the Object Identifier of the equality matching rule in effect
   for this attribute, or null if there is none.


2.2.3 getOrderingMatchingRule

   public String getOrderingMatchingRule ()

   Returns the Object Identifier of the ordering matching rule in effect
   for this attribute, or null if there is none.


2.2.4 getSuperior

   public String getSuperior()

   Returns the name of the attribute type which this attribute derives
   from, or null if there is no superior attribute.

2.2.5 getSubstringMatchingRule

   public String getSubstringMatchingRule ()

   Returns the Object Identifier of the substring matching rule in
   effect for this attribute, or null if there is none.


2.2.6 getSyntaxString

   public String getSyntaxString()

   Returns the Object Identifier of the syntax of the attribute in
   dotted-decimal format.


2.2.7 getUsage

   public int getUsage ()

   Returns one of the following:

        USER_APPLICATIONS
        DIRECTORY_OPERATION
        DISTRIBUTED_OPERATION
        DSA_OPERATION


2.2.8 isCollective

   public boolean isCollective ()

   Returns true if the attribute is collective.

Expires December, 2001                                       [Page 24]


JAVA LDAP API                                                June 2001



2.2.9 isUserModifiable

   public boolean isUserModifiable ()

   Returns true if the attribute is modifiable by users.


2.2.10 isSingleValued

   public boolean isSingleValued()

   Returns true if the attribute is single-valued.


2.2.11 Constants of LDAPAttributeSchema

   The constants correspond to those defined in RFC 2252 [ATTR]:
   userApplications, directoryOperation, distributedOperation, and
   dSAOperation.

     USER_APPLICATIONS (0)     An ordinary user attribute

     DIRECTORY_OPERATION (1)   An operational attribute used for a
                               directory operation or which holds a
                               directory specific value

     DISTRIBUTED_OPERATION (2) An operational attribute used to hold
                               server (DSA) information that is shared
                               among servers holding replicas of the
                               entry

     DSA_OPERATION (3)         An operational attribute used to hold
                               server (DSA) information that is local
                               to a server


2.3 public class LDAPAttributeSet
                 implements Cloneable

   An LDAPAttributeSet is a collection of LDAPAttributes, as returned in
   an entry on a search or read operation, or used to construct an entry
   to be added to a directory.


2.3.1 Constructors

   public LDAPAttributeSet()

   Constructs a new set of attributes. This set is initially empty.



Expires December, 2001                                       [Page 25]


JAVA LDAP API                                                June 2001


2.3.2 add

   public void add(LDAPAttribute attr)

   Adds the specified attribute to this attribute set.

   Parameters are:

      attr           Attribute to add to this set.


2.3.3 clone

   public Object clone()

   Returns a deep copy of this attribute set.


2.3.4 elementAt

   public LDAPAttribute elementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Returns the attribute at the position specified by the index. The
   index is 0-based.

   Parameters are:

      index           Index of the attribute to get.


2.3.5 getAttribute


   public LDAPAttribute getAttribute(String attrName)

   Returns the attribute matching the specified attrName. For example,

        getAttribute("cn")          returns only the "cn" attribute
        getAttribute("cn;lang-en")  returns only the "cn;lang-en"
                                    attribute.

   In both cases, null is returned if there is no exact match to the
   specified attrName.


   public LDAPAttribute getAttribute(String attrName, String lang)

   Returns a single best-match attribute, or none if no match is
   available in the entry.



Expires December, 2001                                       [Page 26]


JAVA LDAP API                                                June 2001


   LDAP version 3 allows adding a subtype specification to an attribute
   name. "cn;lang-ja", for example, indicates a Japanese language
   subtype of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype
   of "cn;lang-ja". This feature MAY be used to provide multiple
   localizations in the same Directory. For attributes which do not vary
   among localizations, only the base attribute may be stored, whereas
   for others there may be varying degrees of specialization.

   getAttribute(attrName, lang) returns the subtype that matches
   attrName and that best matches lang. If there are subtypes other than
   "lang" subtypes included in attrName, e.g. "cn;binary", only
   attributes with all of those subtypes are returned. If lang is null
   or empty, the method behaves as getAttribute(attrName). If there are
   no matching attributes, null is returned. If the results are
   ambiguous, the exception UnsupportedOperationException is thrown.

   Example:

      Assume the entry contains only the following attributes:

         cn;lang-en
         cn;lang-ja-JP-kanji
         sn

         getAttribute( "cn" )               returns null.
         getAttribute( "sn" )               returns the "sn" attribute.
         getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en"
                                            attribute.
         getAttribute( "cn", "lang-en" )    returns the "cn;lang-en"
                                            attribute.
         getAttribute( "cn", "lang-ja" )    returns null.
         getAttribute( "sn", "lang-en" )    returns the "sn" attribute.

   Parameters are:

      attrName       The name of an attribute to retrieve, with or
                      without subtype specification(s). "cn",
                      "cn;phonetic", and cn;binary" are valid attribute
                      names.

      lang           A language specification as in [LANG], with
                      optional subtypes appended using "-" as
                      separator. "lang-en", "lang-en-us", "lang-ja",
                      and "lang-ja-JP-kanji" are valid language
                      specification.


2.3.6 getAttributes

   public Enumeration getAttributes()

   Returns an enumeration of the attributes in this attribute set.

Expires December, 2001                                       [Page 27]


JAVA LDAP API                                                June 2001




2.3.7 getSubset

   public LDAPAttributeSet getSubset(String subtype)

   Creates a new attribute set containing only the attributes that have
   the specified subtypes.

   For example, suppose an attribute set contains the following
   attributes:

         cn
         cn;lang-ja
         sn;lang-ja;phonetic
         sn;lang-us


   Calling the getSubset method and passing lang-ja as the argument, the
   method returns an attribute set containing the following attributes:

         cn;lang-ja
         sn;lang-ja;phonetic


   Parameters are:

      subtype - Semi-colon delimited list of subtypes to include. For
                      example:
                     "lang-ja"        // Only Japanese language
                                      // subtypes
                     "binary"         // Only binary subtypes
                     "binary;lang-ja" // Only Japanese language
                                      // subtypes which also are binary


2.3.8 remove

   public void remove(String name)

   Removes the specified attribute from the set. Subtypes of the
   specified attribute are not removed. If the attribute is not a member
   of the set, nothing happens.

   Parameters are:

      name           Name of the attribute to remove from this set. To
                      remove an LDAPAttribute by object, the
                      LDAPAttribute.getName method can be used:
                      LDAPAttributeSet.remove( attr.getName() );



Expires December, 2001                                       [Page 28]


JAVA LDAP API                                                June 2001


2.3.9 removeElementAt

   public void removeElementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Removes the attribute at the position specified by the index.  The
   index is 0-based.

   Parameters are:

      index          Index of the attribute to remove.


2.3.10 size

   public int size()

   Returns the number of attributes in this set.


2.4 public interface LDAPBind
                     extends LDAPReferralHandler

   Used to do explicit bind processing on a referral. A client may
   specify an instance of this class to be used on a single operation
   (through an LDAPConstraints object) or for all operations (through
   the LDAPConstraints object associated with the connection).


2.4.1 bind


   public LDAPConnection bind(String[] ldapurl, LDAPConnection conn)
                    throws LDAPReferralException

   This method is called by LDAPConnection when a referral or search
   continuation is received, and is responsible for binding to one of
   the hosts in the list specified by the ldapurl parameter (which
   corresponds exactly to the list of hosts returned in a single
   referral or search continuation response). An implementation may
   access the host, port, credentials, and other information in the
   original LDAPConnection object to decide on an appropriate
   authentication mechanism, and/or may interact with a user or external
   module. The object implementing LDAPBind creates a new LDAPConnection
   object to perform its connect and bind calls. It  returns the new
   connection when both the connect and bind operations succeed on one
   host from the list. The LDAPConnection object referral following code
   uses the new LDAPConnection object when it resends the search
   request, updated with the new search base and possibly search filter.
   An LDAPReferralException is thrown on failure.

   Parameters are:

Expires December, 2001                                       [Page 29]


JAVA LDAP API                                                June 2001



      ldapurl        List of LDAP server URLs.  There is no order
                      implied by the list.

      conn           An established connection to an LDAP server.


2.5 public class LDAPCompareAttrNames
                 implements LDAPEntryComparator

   An object of this class supports sorting search results by attribute
   name, in ascending or descending order. Sorting is by locale-
   sensitive Java String comparison, which may not correspond to the
   LDAP ordering rules by which an LDAP server would sort them.


2.5.1 Constructors

   public LDAPCompareAttrNames(String attrName)


   Constructs an object that will sort results by a single attribute, in
   ascending order.


   public LDAPCompareAttrNames(String attrName,
                               boolean ascendingFlag)

   Constructs an object that will sort results by a single attribute, in
   either ascending or descending order.


   public LDAPCompareAttrNames(String[] attrNames)

   Constructs an object that will sort by one or more attributes, in the
   order provided, in ascending order.


   public LDAPCompareAttrNames(String[] attrNames,
                               boolean[] ascendingFlags)
                               throws LDAPException

   Constructs an object that will sort by one or more attributes, in the
   order provided, in either ascending or descending order for each
   attribute.

   Parameters are:

      attrName       Name of an attribute to sort by.

      attrNames      Array of names of attributes to sort by.


Expires December, 2001                                       [Page 30]


JAVA LDAP API                                                June 2001


      ascendingFlag  true to sort in ascending order, false for
                      descending order.

      ascendingFlags Array of flags, one for each attrName, where each
                      one is true to sort in ascending order, false for
                      descending order. An LDAPException is thrown if
                      the length of ascendingFlags is not greater than
                      or equal to the length of attrNames.


2.5.2 getLocale

   public Locale getLocale()

   Returns the Locale to be used for sorting, if a Locale has been
   specified. If null, a basic String.compareTo() is used for collation.
   If non-null, a Locale-specific collation is used.


2.5.3 isGreater

   public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2)

   Returns true if entry1 is to be considered greater than entry2, for
   the purpose of sorting, based on the attribute name or names provided
   on object construction.

   Parameters are:

      entry1         Target entry for comparison.

      entry2         Entry to be compared to.


2.5.4 setLocale

   public void setLocale(Locale locale)

   Sets the Locale to be used for sorting.

   Parameters are:

      locale         The Locale to be used for sorting.


2.6 public class LDAPConnection
                 implements Cloneable

   LDAPConnection is the central class that encapsulates the connection
   to a Directory Server through the LDAP protocol. An LDAPConnection
   object is not connected on construction, and may only be connected to
   one server at one port. Multiple threads may share this single

Expires December, 2001                                       [Page 31]


JAVA LDAP API                                                June 2001


   connection, and an application may have more than one LDAPConnection
   object, connected to the same or different Directory Servers.


2.6.1 Constructors

   public LDAPConnection()

   Constructs a new LDAPConnection object, which represents a connection
   to an LDAP server.

   Calling the constructor does not actually establish the connection.
   The connect or bind methods are used to connect to the LDAP server.


   public LDAPConnection(LDAPSocketFactory factory)

   Constructs a new LDAPConnection object, which will use the supplied
   class factory to construct a socket connection during
   LDAPConnection.connect().

   Parameters are:

      factory         An object capable of producing a Socket.


2.6.2 abandon

   public void abandon(LDAPSearchResults results)
                       throws LDAPException

   public void abandon(LDAPSearchResults results, LDAPConstraints cons)
                       throws LDAPException

   public void abandon(int id)
                       throws LDAPException

   public void abandon(int id, LDAPConstraints cons)
                      throws LDAPException

   public void abandon(LDAPListener listener)
                      throws LDAPException

   public void abandon(LDAPListener listener, LDAPConstraints cons)
                      throws LDAPException

   Either notifies the server to not send additional results associated
   with this LDAPSearchResults object, and discards any results already
   received, or abandons one or all operations for an asynchronous
   response listener.



Expires December, 2001                                       [Page 32]


JAVA LDAP API                                                June 2001


   The application is responsible for not calling this method more than
   once with a particular id or LDAPSearchResults.

   Parameters are:

      results        An object returned from a search.

      id             The ID of the asynchronous operation to abandon.
                      The ID may be obtained from the response listener
                      for the operation.

      listener       Handler returned from an asynchronous request.
                      All outstanding operations that are managed by
                      the listener are abandoned.

      cons           Constraints specific to the operation.


2.6.3 add

   public void add(LDAPEntry entry)
                   throws LDAPException

   public void add(LDAPEntry entry,
                   LDAPConstraints cons)
                   throws LDAPException

   public LDAPResponseListener add(LDAPEntry entry,
                                   LDAPResponseListener listener)
                                   throws LDAPException


   public LDAPResponseListener add(LDAPEntry entry,
                                   LDAPResponseListener listener,
                                   LDAPConstraints cons)
                                   throws LDAPException

   Adds an entry to the directory.

   The application is responsible for specifying attribute values which
   are valid according to the syntax defined for the attributes. It is
   also responsible for including all attributes which are required for
   the entry.

   Parameters are:

      entry          LDAPEntry object specifying the distinguished
                      name and attributes of the new entry.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

Expires December, 2001                                       [Page 33]


JAVA LDAP API                                                June 2001



      cons           Constraints specific to the operation.


2.6.4 addUnsolicitedNotificationListener

   public void addUnsolicitedNotificationListener(
                       LDAPUnsolicitedNotificationListener listener)

   Registers an object to be notified on arrival of an unsolicited
   message from a server.

   Parameters are:

      listener       An object to be notified on arrival of an
                      unsolicited message from a server.


2.6.5 bind


   public void bind(int version,
                    String dn,
                    String passwd)
                    throws LDAPException

   public void bind(int version,
                    String dn,
                    byte[] passwd)
                    throws LDAPException

   public void bind(int version,
                    String dn,
                    String passwd,
                    LDAPConstraints cons)
                    throws LDAPException

   public void bind(int version,
                    String dn,
                    byte[] passwd,
                    LDAPConstraints cons)
                    throws LDAPException

   public LDAPResponseListener bind(int version,
                                    String dn,
                                    String passwd,
                                    LDAPResponseListener listener)
                                    throws LDAPException

   public LDAPResponseListener bind(int version,
                                    String dn,
                                    byte[] passwd,

Expires December, 2001                                       [Page 34]


JAVA LDAP API                                                June 2001


                                    LDAPResponseListener listener)
                                    throws LDAPException

   public LDAPResponseListener bind(int version,
                                    String dn,
                                    String passwd,
                                    LDAPResponseListener listener,
                                    LDAPConstraints cons)
                                    throws LDAPException

   public LDAPResponseListener bind(int version,
                                    String dn,
                                    byte[] passwd,
                                    LDAPResponseListener listener,
                                    LDAPConstraints cons)
                                    throws LDAPException


   Authenticates to the LDAP server (that the object is currently
   connected to) using the specified name and password, with the
   specified LDAP protocol version. This API is specifically designed
   for use with LDAPv3.  Unless the API provides specific support (as
   defined in other documents) for other versions of LDAP, version 3
   should be used. If the server does not support the requested protocol
   version, an exception is thrown.  If the object has been disconnected
   from an LDAP server, this method attempts to reconnect to the server.
   If the object had already authenticated, the old authentication is
   discarded.

   Parameters are:

      version        LDAP protocol version requested: currently 2 or
                      3.

      dn              If non-null and non-empty, specifies that the
                      connection and all operations through it SHOULD
                      be authenticated with dn as the distinguished
                      name.

      passwd         If non-null and non-empty, specifies that the
                      connection and all operations through it SHOULD
                      be authenticated with dn as the distinguished
                      name and passwd as password.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the operation.


   public void bind(String dn,

Expires December, 2001                                       [Page 35]


JAVA LDAP API                                                June 2001


                    String authzId,
                    Hashtable props,
                    javax.security.auth.callback.CallbackHandler cbh)
                    throws LDAPException


   public void bind(String dn,
                    String authzId,
                    Hashtable props,
                    javax.security.auth.callback.CallbackHandler cbh,
                    LDAPConstraints cons)
                    throws LDAPException


   public void bind(String dn,
                    String authzId,
                    String[] mechanisms,
                    Hashtable props,
                    javax.security.auth.callback.CallbackHandler cbh)
                    throws LDAPException

   public void bind(String dn,
                    String authzId,
                    String[] mechanisms,
                    Hashtable props,
                    javax.security.auth.callback.CallbackHandler cbh,
                    LDAPConstraints cons)
                    throws LDAPException


   Authenticates to the LDAP server (that the object is currently
   connected to) using the specified name and one of a specified set of
   mechanisms. If none of the requested SASL [SASL][AUTH][JAVASASL]
   mechanisms is available, an exception is thrown.  If the object has
   been disconnected from an LDAP server, this method attempts to
   reconnect to the server. If the object had already authenticated, the
   old authentication is discarded. A SASL bind call() may involved
   multiple protocol requests. An attempt to invoke an operation other
   than bind between bind requests in a multi-stage bind results in an
   LDAPException with the result code SASL_BIND_IN_PROGRESS.

   Parameters are:

      dn              The distinguished name to use as the bind name.
                      This value is not used as either a SASL
                      authentication nor authorization identity. The
                      application provides these identities through the
                      callback handler.

      authzId        If not null and not empty, an LDAP authzID [AUTH]
                      to be passed to the SASL layer.


Expires December, 2001                                       [Page 36]


JAVA LDAP API                                                June 2001


      mechanisms     An array of IANA-registered SASL mechanisms which
                      the client is willing to use for authentication.

      props          Optional qualifiers for the authentication
                      session.

      cbh            A class which may be called by the Mechanism
                      Driver to obtain additional information required,
                      such as additional credentials.

      cons           Constraints specific to the operation.


2.6.6 clone

   public Object clone()

   Returns a copy of the object with a private context, but sharing the
   network connection if there is one. The network connection remains
   open until all clones have disconnected or gone out of scope. Any
   connection opened after cloning is private to the object making the
   connection.

   The clone can freely modify options and search constraints, and issue
   requests, without affecting the source object or other clones. If the
   clone disconnects or reconnects, it is completely dissociated from
   the source object and other clones. Reauthenticating in a clone,
   however, is a global operation which will affect the source object
   and all associated clones, because it applies to the single shared
   physical connection. Any request by an associated object after one
   has reauthenticated will carry the new identity.

   Methods that are global in nature and which affect the source object
   are:

        addUnsolicitedNotificationListener
        bind
        connect
        disconnect
        finalize
        removeUnsolicitedNotificationListener
        setInputStream
        setOutputStream
        startTLS

    The following methods return data that is from the source object and
    is the same for all clones of LDAPConnection:

        getAuthenticationDN
        getAuthenticationMethod
        getHost
        getInputStream

Expires December, 2001                                       [Page 37]


JAVA LDAP API                                                June 2001


        getOutputStream
        getPort
        getProtocolVersion
        getSaslBindCallBackHandler
        getSaslBindProperties
        getSocketFactory
        isBound
        isConnected
        isTLS

    The following methods manipulate or retrieve data that is unique to
   each clone of LDAPConnection:

        getConstraints
        getProperty
        getResponseControls
        getSearchConstraints
        setConstraints
        setProperty
        setSearchConstraints


2.6.7 compare

   public boolean compare(String dn,
                          LDAPAttribute attr)
                          throws LDAPException

   public boolean compare(String dn,
                          LDAPAttribute attr,
                          LDAPConstraints cons)
                          throws LDAPException

   public LDAPResponseListener compare(String dn,
                                       LDAPAttribute attr,
                                       LDAPResponseListener listener)
                                       throws LDAPException

   public LDAPResponseListener compare(String dn,
                                       LDAPAttribute attr,
                                       LDAPResponseListener listener,
                                       LDAPConstraints cons)
                                       throws LDAPException

   Checks to see if an entry contains an attribute with a specified
   value. The synchronous methods return a value of true if the entry
   has the value, and false if the entry does not have the value or the
   attribute.

   Parameters are:



Expires December, 2001                                       [Page 38]


JAVA LDAP API                                                June 2001


      dn             The distinguished name of the entry to use in the
                      comparison.

      attr           The attribute to compare against the entry. The
                      method checks to see if the entry has an
                      attribute with the same name and value as this
                      attribute.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the operation.


2.6.8 connect

   public void connect(String host,
                       int port)
                       throws LDAPException

   Connects to the specified host and port. If this LDAPConnection
   object represents an open connection, the connection is closed first
   before the new connection is opened.  At this point there is no
   authentication, and any operations will be conducted as an anonymous
   client.

   Parameters are:

      host           Contains a host identifier consisting of a
                      hostname, an IPv4 dotted string, or an IPv6
                      reference [IPv6] representing the IP address of a
                      host running an LDAP server to connect to.
                      Alternatively, it may contain a list of host
                      identifiers, space-delimited.  Each host
                      identifier may include a trailing colon and port
                      number.  In the case where more than one host
                      identifier is specified, each host identifier in
                      turn will be contacted until a connection can be
                      established. Examples:

         "directory.example.com"
         "192.0.2.0"
         "[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:4389"
         "directory.example.com:1050 people.catalog.com 192.0.2.0"

      port           Contains the TCP port number to connect to or
                      contact. The default LDAP port is 389. "port" is
                      ignored for any host identifier which includes a
                      colon and port number.



Expires December, 2001                                       [Page 39]


JAVA LDAP API                                                June 2001


2.6.9 delete

   public void delete(String dn) throws LDAPException

   public void delete(String dn,
                      LDAPConstraints cons)
                      throws LDAPException

   public LDAPResponseListener delete(String dn,
                                      LDAPResponseListener listener)
                                      throws LDAPException

   public LDAPResponseListener delete(String dn,
                                      LDAPResponseListener listener,
                                      LDAPConstraints cons)
                                      throws LDAPException

   Deletes the entry for the specified DN from the directory.


   Parameters are:

      dn             Distinguished name of the entry to modify.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the operation.


2.6.10 disconnect

   public void disconnect() throws LDAPException

   public void disconnect(LDAPConstraints cons) throws LDAPException


   Disconnects from the LDAP server. The API implementation sends an
   Unbind request to the server with any controls specified by the
   LDAPConstraints object before closing the connection. Before the
   object can perform LDAP operations again, it MUST reconnect to the
   server by calling either connect or bind (bind will attempt to
   reconnect). The object is disassociated from any clones on calling
   disconnect.

   Parameters are:

      cons           Constraints to be sent with the unbind request.




Expires December, 2001                                       [Page 40]


JAVA LDAP API                                                June 2001


2.6.11 extendedOperation

   public LDAPExtendedResponse extendedOperation(
                                   LDAPExtendedOperation op )
                                   throws LDAPException

   public LDAPExtendedResponse extendedOperation(
                                   LDAPExtendedOperation op,
                                   LDAPConstraints cons )
                                   throws LDAPException

   public LDAPResponseListener extendedOperation(
                                   LDAPExtendedOperation op,
                                   LDAPResponseListener listener)
                                   throws LDAPException

   public LDAPResponseListener extendedOperation(
                                   LDAPExtendedOperation op,
                                   LDAPConstraints cons,
                                   LDAPResponseListener listener)
                                   throws LDAPException

   Provides a means to access extended, non-mandatory operations offered
   by a particular LDAP version 3 compliant server.

   Returns an operation-specific object, containing an OID and an Octet
   String or BER-encoded value(s).

   Parameters are:

      op             Object which contains an object identifier of the
                      extended operation, which SHOULD be one
                      recognized by the particular server this client
                      is connected to, and  operation-specific sequence
                      of Octet String or BER-encoded value(s).

      cons           Constraints specific to the operation.


2.6.12 finalize

   public void finalize() throws LDAPException

   Closes the connection if open and releases any other resources held
   by the object.


2.6.13 getAuthenticationDN

   public String getAuthenticationDN()



Expires December, 2001                                       [Page 41]


JAVA LDAP API                                                June 2001


   Returns the distinguished name (DN) used as the bind name during the
   last successful bind operation. null is returned if no authentication
   has been performed or if the bind resulted in an anonymous
   connection.


2.6.14 getAuthenticationMethod

   public String getAuthenticationMethod()

   Returns the method used to authenticate the connection. The return
   value is one of the following:

      "none"         The current authentication state has not been
                      established by use of the bind operation.  This
                      is the initial state upon connect().

      "simple"       Simple bind has completed successfully
                      (anonymous, unauthenticated, or authenticated)

      "sasl"         The current authentication state was established
                      by the successful completion of a SASL bind


2.6.15 getConstraints

   public LDAPConstraints getConstraints()

   Returns a copy of the set of constraints associated with this
   connection. These constraints apply to all operations performed
   through this connection (unless a different set of constraints is
   specified when calling an operation method).


2.6.16 getHost

   public String getHost()

   Returns the host name of the LDAP server to which the object is or
   was last connected, in the format originally specified.


2.6.17 getInputStream

   public InputStream getInputStream()

   Returns the stream used by the connection object for receiving data
   from the LDAP server.


2.6.18 getOutputStream


Expires December, 2001                                       [Page 42]


JAVA LDAP API                                                June 2001


   public OutputStream getOutputStream()

   Returns the stream used by the connection object to send data to the
   LDAP server.


2.6.19 getPort

   public int getPort()

   Returns the port number of the LDAP server to which the object is or
   was last connected.


2.6.20 getProperty

   public Object getProperty(String name) throws LDAPException

   Gets a property of a connection object.

   Parameters are:

      name            Name of the property to be returned.

                      The following read-only properties are available
                      for any given connection:


                      LDAP_PROPERTY_SDK ("version.sdk")  The version of
                                                    this SDK, as a
                                                    Float data type.


                      LDAP_PROPERTY_PROTOCOL ("version.protocol")  The
                                                    highest supported
                                                    version of the LDAP
                                                    protocol, as a
                                                    Float data type.


                      LDAP_PROPERTY_SECURITY ("version.security")  A
                                                    comma-separated
                                                    list of the types
                                                    of authentication
                                                    supported, as a
                                                    String.

      Other properties may be available in particular implementations
      of the class, and used to modify operations such as search.

      A deep copy of the property is provided where applicable; a
      client does not need to clone the object received.

Expires December, 2001                                       [Page 43]


JAVA LDAP API                                                June 2001




      An LDAPException is thrown if the requested property is not
      available.


2.6.21 getProtocolVersion

   public int getProtocolVersion ()

   Returns the protocol version that the connection is bound to (2 or
   3).


2.6.22 getResponseControls

   public LDAPControl[] getResponseControls()

   Returns the latest Server Controls returned by a Directory Server
   with a response to an LDAP request from the current thread. For
   asynchronous requests, the response controls are available in
   LDAPMessage instead.


2.6.23 getSaslBindCallbackHandler

   public javax.security.auth.callback.CallbackHandler
          getSaslBindCallbackHandler()

   Returns the callback handler, if any, specified on binding with a
   SASL mechanism.


2.6.24 getSaslBindProperties

   public Hashtable getSaslBindProperties()

   Returns the properties, if any, specified on binding with a SASL
   mechanism.


2.6.25 getSearchConstraints

   public LDAPSearchConstraints getSearchConstraints()

   Returns a copy of the set of search constraints associated with this
   connection. These constraints apply to search operations performed
   through this connection (unless a different set of constraints is
   specified when calling the search operation method). The search
   constraints include the base constraints returned by
   getConstraints().


Expires December, 2001                                       [Page 44]


JAVA LDAP API                                                June 2001



2.6.26 getSocketFactory

   public LDAPSocketFactory getSocketFactory()

   Returns the LDAPSocketFactory used to establish a connection to a
   server.


2.6.27 isBound

   public boolean isBound()

   Indicates whether the object has authenticated to the connected LDAP
   server (other than anonymously with simple bind). It returns false
   initially, false upon a bind request, and true after successful
   completion of the last outstanding non-anonymous simple bind.


2.6.28 isConnected

   public boolean isConnected()

   Indicates if the connection represented by this object is open at
   this time.


2.6.29 isTLS

   public boolean isTLS ()

   Indicates the session is currently protected by TLS. The
   method provides no indication of the level of protection provided.


2.6.30 modify

   public void modify(String dn,
                      LDAPModification mod)
                      throws LDAPException

   public void modify(String dn,
                      LDAPModification mod,
                      LDAPConstraints cons)
                      throws LDAPException

   public LDAPResponseListener modify(String dn,
                                      LDAPModification mod,
                                      LDAPResponseListener listener)
                                      throws LDAPException

   public LDAPResponseListener modify(String dn,

Expires December, 2001                                       [Page 45]


JAVA LDAP API                                                June 2001


                                      LDAPModification mod,
                                      LDAPResponseListener listener,
                                      LDAPConstraints cons)
                                      throws LDAPException

   Makes a single change to an existing entry in the directory (for
   example, changes the value of an attribute, adds a new attribute
   value, or removes an existing attribute value).

   The LDAPModification object specifies both the change to be made and
   the LDAPAttribute value to be changed.

   The application is responsible for specifying attribute values which
   are valid according to the syntax defined for the attributes.


   public void modify(String dn,
                      LDAPModificationSet mods)
                      throws LDAPException

   public void modify(String dn,
                      LDAPModificationSet mods,
                      LDAPConstraints cons)
                      throws LDAPException

   public LDAPResponseListener modify(String dn,
                                      LDAPModificationSet mods,
                                      LDAPResponseListener listener)
                                      throws LDAPException

   public LDAPResponseListener modify(String dn,
                                      LDAPModificationSet mods,
                                      LDAPResponseListener listener,
                                      LDAPConstraints cons)
                                      throws LDAPException

   Makes a set of changes to an existing entry in the directory (for
   example, changes attribute values, adds new attribute values, or
   removes existing attribute values).


   The application is responsible for specifying attribute values which
   are valid according to the syntax defined for the attributes.

   Parameters are:

      dn             Distinguished name of the entry to modify.

      mod            A single change to be made to the entry.

      mods           A set of changes to be made to the entry.


Expires December, 2001                                       [Page 46]


JAVA LDAP API                                                June 2001


      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the operation.


2.6.31 read

   public LDAPEntry read(String dn) throws LDAPException

   Reads the entry for the specified distiguished name (DN) and
   retrieves all attributes for the entry.


   public LDAPEntry read(String dn,
                         LDAPSearchConstraints cons)
                         throws LDAPException

   Reads the entry for the specified distiguished name (DN) and
   retrieves all attributes for the entry.


   public LDAPEntry read(String dn,
                         String[] attrs)
                         throws LDAPException

   public LDAPEntry read(String dn,
                         String[] attrs,
                         LDAPSearchConstraints cons)
                         throws LDAPException

   Reads the entry for the specified distinguished name (DN) and
   retrieves only the specified attributes from the entry.


   public static LDAPEntry read(LDAPUrl toGet) throws LDAPException

   public static LDAPEntry read(LDAPUrl toGet,
                                LDAPSearchConstraints cons)
                                throws LDAPException

   Reads the entry specified by the LDAP URL.

   When this method is called, a new connection is created
   automatically, using the host and port specified in the URL. After
   finding the entry, the method closes the connection (in other words,
   it disconnects from the LDAP server).

   If the URL specifies a scope other than base,
   IllegalArgumentException is thrown. Any critical extensions specified


Expires December, 2001                                       [Page 47]


JAVA LDAP API                                                June 2001


   in the URL must be processed or else an LDAPException is thrown with
   the result code UNSUPPORTED_OPERATION.

   The method returns the entry specified by the base DN.


   Parameters are:

      dn             Distinguished name of the entry to retrieve.

      cons           Constraints specific to the operation.

      attrs          Names of attributes to retrieve.

      toGet           LDAP URL specifying the entry to read.


   If the server does not return exactly one entry, an LDAPException is
   thrown with a result code of AMBIGIOUS_RESPONSE.

   Note: read is simply a helper method and uses the ldap search
   operation to achieve the results. As such, there is no asynchronous
   interface.


2.6.32 removeUnsolicitedNotificationListener

   public void removeUnsolicitedNotificationListener(
                       LDAPUnsolicitedNotificationListener listener)

   Deregisters an object so that it will no longer be notified on
   arrival of an unsolicited message from a server. If the object is
   null or was not previously registered for unsolicited notifications,
   the method does nothing.

   Parameters are:

      listener       An object to no longer be notified on arrival of
                      an unsolicited message from a server.


2.6.33 rename

   public void rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn)
                      throws LDAPException

   public void rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn,
                      LDAPConstraints cons)

Expires December, 2001                                       [Page 48]


JAVA LDAP API                                                June 2001


                      throws LDAPException

   public LDAPResponseListener rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn,
                      LDAPResponseListener listener)
                      throws LDAPException

   public LDAPResponseListener rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn,
                      LDAPResponseListener listener,
                      LDAPConstraints cons)
                      throws LDAPException

   Renames an existing entry in the directory.


   public void rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn)
                      throws LDAPException

   public void rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn,
                      LDAPConstraints cons)
                      throws LDAPException

   public LDAPResponseListener rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn,
                      LDAPResponseListener listener)
                      throws LDAPException

   public LDAPResponseListener rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn,
                      LDAPResponseListener listener,
                      LDAPConstraints cons)
                      throws LDAPException

   Renames an existing entry or subtree in the directory, possibly
   repositioning it
   in the directory tree.

   Parameters are:


Expires December, 2001                                       [Page 49]


JAVA LDAP API                                                June 2001


      dn             Current distinguished name of the entry.

      newRdn         New relative distinguished name for the entry.

      newParentdn    Distinguished name of the existing entry which is
                      to be the new parent of the entry.

      deleteOldRdn   If true, the old name is not retained as an
                      attribute value.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the operation.


2.6.34 search

   public LDAPSearchResults search(String base,
                                   int scope,
                                   String filter,
                                   String[] attrs,
                                   boolean typesOnly)
                                   throws LDAPException

   public LDAPSearchListener search(String base,
                                    int scope,
                                    String filter,
                                    String[] attrs,
                                    boolean typesOnly,
                                    LDAPSearchListener listener)
                                    throws LDAPException

   Performs the search specified by the parameters.


   public LDAPSearchResults search(String base,
                                   int scope,
                                   String filter,
                                   String[] attrs,
                                   boolean typesOnly,
                                   LDAPSearchConstraints cons)
                                   throws LDAPException

   public LDAPSearchListener search(String base,
                                    int scope,
                                    String filter,
                                    String[] attrs,
                                    boolean typesOnly,
                                    LDAPSearchListener listener,
                                    LDAPSearchConstraints cons)

Expires December, 2001                                       [Page 50]


JAVA LDAP API                                                June 2001


                                    throws LDAPException

   Performs the search specified by the parameters, also allowing
   specification of constraints for the search (such as the maximum
   number of entries to find or the maximum time to wait for search
   results).

   As part of the search constraints, the function allows specifying
   whether or not the results are to be delivered all at once or in
   smaller batches. If specified that the results are to be delivered in
   smaller batches, each iteration blocks only until the next batch of
   results is returned.


   public static LDAPSearchResults search(LDAPUrl toGet)
   throws LDAPException

   Performs the search specified by the LDAP URL, returning an
   enumerable LDAPSearchResults object.


   public static LDAPSearchResults search(LDAPUrl toGet,
                                          LDAPSearchConstraints cons)
                                          throws LDAPException

   Perfoms the search specified by the LDAP URL. This method also allows
   specifying constraints for the search (such as the maximum number of
   entries to find or the maximum time to wait for search results).

   When this method is called, a new connection is created
   automatically, using the host and port specified in the URL. After
   all search results have been received from the server, the method
   closes the connection (in other words, it disconnects from the LDAP
   server).

   As part of the search constraints, a choice can be made as to whether
   to have the results delivered all at once or in smaller batches. If
   the results are to be delivered in smaller batches, each iteration
   blocks only until the next batch of results is returned.


   Parameters are:

      base           The base distinguished name to search from.

      scope          The scope of the entries to search. The following
                      are the valid options:

             SCOPE_BASE   Search only the base DN

             SCOPE_ONE    Search only entries directly under the base
                           DN

Expires December, 2001                                       [Page 51]


JAVA LDAP API                                                June 2001



             SCOPE_SUB    Search the base DN and all entries within
                           its subtree

      filter         Search filter specifying the search criteria, as
                      defined in [FILTER]. The value null can be passed
                      to indicate that the filter "(objectclass=*)"
                      which matches all entries is to be used.

      attrs          Names of attributes to retrieve.

      typesOnly      If true, returns the names but not the values of
                      the attributes found.  If false, returns the
                      names and values for attributes found.

      toGet          LDAP URL specifying the entry to read.

      listener       Handler for messages returned from a server in
                      response to this request. If it is null, a
                      listener object is created internally.

      cons           Constraints specific to the search.

   Note: RFC 2251 [LDAPv3] indicates that extendedResponses on search
   requests may be defined in future versions of the LDAP protocol.
   There is no support for extendedResponses on search requests in this
   version of the Java LDAP API.


2.6.35 setConstraints

   public void setConstraints(LDAPConstraints cons)

   Sets the constraints that apply to all operations performed through
   this connection (unless a different set of constraints is specified
   when calling an operation method). An LDAPSearchConstraints object
   which is passed to this method will override all constraints, while
   an LDAPConstraints object will only affect the base constraints.


2.6.36 setInputStream

   public void setInputStream(InputStream stream)

   Sets the stream used by the connection object for receiving data from
   the LDAP server.


2.6.37 setOutputStream

   public void setOutputStream(OutputStream stream)


Expires December, 2001                                       [Page 52]


JAVA LDAP API                                                June 2001


   Sets the stream used by the connection object to send data to the
   LDAP server.


2.6.38 setProperty

   public void setProperty(String name, Object value)
        throws LDAPException

   Sets a property of a connection object.

   No property names have been defined at this time, but the mechanism
   is in place in order to support revisional as well as dynamic
   extensions to operation modifiers.

   Parameters are:

      name           Name of the property to set.

      value          Value to assign to the property.
                      An LDAPException is thrown if the specified
                      property is not supported.

2.6.39 setSocketFactory

   public static void setSocketFactory(LDAPSocketFactory factory)

   Establishes the default LDAPSocketFactory used when LDAPConnection
   objects are constructed unless an LDAPSocketFactory is specified in
   the LDAPConnection object constructor.

   This method sets the default LDAPSocketFactory used for all
   subsequent LDAPConnection objects constructed. If called after
   LDAPConnection objects are created, those already created are not
   affected even if they disconnect and establish a new connection. It
   affects LDAPConnection objects only as they are constructed.

   Parameters are:

      factory        A factory object which can construct socket
                      connections for an LDAPConnection.


2.6.40 startTLS

   public void startTLS()
   throws LDAPException

   Begin using the Transport Layer Security (TLS) protocol for session
   privacy [10]. If the socket factory of the connection is not capable
   of initiating a TLS session, an LDAPException is thrown with the
   error code TLS_NOT_SUPPORTED. If the server does not support the

Expires December, 2001                                       [Page 53]


JAVA LDAP API                                                June 2001


   transition to a TLS session, an LDAPException is thrown with the
   error code returned by the server. If there are outstanding LDAP
   operations on the connection, an LDAPException is thrown.



2.6.41 Constants of LDAPConnection

      ALL_USER_ATTRS ("*")     Used with search in an attribute list to
                      indicate that all attributes (other than
                      operational attributes) are to be returned.

      NO_ATTRS ("1.1")  Used with search instead of an attribute list
                      to indicate that no attributes are to be
                      returned.

      DEFAULT_PORT (389) Used on connect to indicate the default LDAP
                      port number.

      SCOPE_BASE (0) Used with search to indicate that only the entry
                      corresponding to the base DN is to be returned.

      SCOPE_ONE (1)  Used with search to indicate that only immediate
                      subordinates of the entry corresponding to the
                      base DN, and not the entry corresponding to the
                      base DN, are to be returned.

      SCOPE_SUB (2)  Used with search to indicate that the entry
                      corresponding to the base DN as well as all
                      direct and indirect subordinate entries are to be
                      returned.


2.7 public class public class LDAPConstraints

   A set of options to control any operation. There is always an
   LDAPConstraints associated with an LDAPConnection object; its
   values can be changed with LDAPConnection.setConstraints, or
   overridden by passing an LDAPConstraints object to an operation.


2.7.1 Constructors

   public LDAPConstraints()

   Constructs an LDAPConstraints object that specifies the default
   set of constraints.


   public LDAPConstraints(int msLimit,
                          boolean doReferrals,
                          LDAPReferralHandler binder,

Expires December, 2001                                       [Page 54]


JAVA LDAP API                                                June 2001


                          int hop_limit)

   Constructs a new LDAPConstraints object and allows specifying
   the operational constraints in that object.

   Parameters are:

      msLimit         Maximum time in milliseconds to wait for results
                      (0 by default, which means that there is no
                      maximum time limit). This is an interface-imposed
                      limit.

      doReferrals     Specify true to follow referrals automatically,
                      or false to throw an LDAPReferralException error
                      if the server sends back a referral (false by
                      default). It is ignored for asynchronous
                      operations.

      binder         Custom authentication processor, called when the
                      LDAPConnection needs to authenticate, typically
                      on following a referral. null MAY be specified to
                      indicate default authentication processing. The
                      object may implement either the LDAPBind or the
                      LDAPRebind interface. It is ignored for
                      asynchronous operations.

      hop_limit       Maximum number of referrals to follow in a
                      sequence when attempting to resolve a request,
                      when doing automatic referral following. It is
                      ignored for asynchronous operations.


2.7.2 getClientControls

   public LDAPControl[] getClientControls()

   Returns controls to be used by the interface.


2.7.3 getHopLimit

   public int getHopLimit()

   Returns the maximum number of hops to follow during automatic
   referral following.


2.7.4 getReferralFollowing

   public boolean getReferralFollowing()

   Specifies whether or not referrals are followed automatically.

Expires December, 2001                                       [Page 55]


JAVA LDAP API                                                June 2001


   Returns true if referrals are to be followed automatically, or false
   if referrals throw an LDAPReferralException.


2.7.5 getServerControls

   public LDAPControl[] getServerControls()

   Returns controls to be sent to the server.


2.7.6 getTimeLimit

   public int getTimeLimit()

   Returns the maximum number of milliseconds the client waits for any
   operation under these constraints. If 0, there is no maximum time
   limit on waiting for the operation results. The actual granularity of
   the timeout depends on the implementation.


2.7.7 setClientControls

   public void setClientControls( LDAPControl control )

   public void setClientControls( LDAPControl[] controls )

   Sets controls for use by the interface.

   Parameters are:

      control        A single client control.

      controls       An array of client controls.


2.7.8 setHopLimit

   public void setHopLimit(int hop_limit)

   Sets the maximum number of hops to follow in sequence during
   automatic referral following. The default is 10. 0 means no limit.

   Parameters are:

      hop_limit      Maximum number of chained referrals to follow
                      automatically.


2.7.9 setReferralFollowing

   public void setReferralFollowing(boolean doReferrals)

Expires December, 2001                                       [Page 56]


JAVA LDAP API                                                June 2001



   Specifies whether nor not referrals are followed automatically, or if
   referrals throw an LDAPReferralException.  Referrals of any type
   other than to an LDAP server (i.e. a referral URL other than
   ldap://something) are ignored on automatic referral following. The
   default is false.

   Parameters are:

      doReferrals    True to follow referrals automatically.


2.7.10 setReferralHandler

   public void setReferralHandler (LDAPReferralHandler binder)

   Specifies the object that will process authentication requests. The
   default is null.

   Parameters are:

      binder         An object that implements LDAPBind or LDAPRebind.


2.7.11 setServerControls

   public void setServerControls( LDAPControl control )

   public void setServerControls( LDAPControl[] controls )

   Sets controls to be sent to the server.

   Parameters are:

      control        A single control to be sent to the server.

      controls       An array of controls to be sent to the server.


2.7.12 setTimeLimit

   public void setTimeLimit(int msLimit)

   Sets the maximum number of milliseconds to wait for any operation
   under these constraints. If 0, there is no maximum time limit
   on waiting for the operation results. The actual granularity of the
   time limit depends on the implementation.

   Parameters are:

      msLimit        Maximum milliseconds to wait.


Expires December, 2001                                       [Page 57]


JAVA LDAP API                                                June 2001



2.8 public class LDAPControl
                 implements Cloneable

   An LDAPControl encapsulates optional additional parameters or
   constraints to be applied to LDAP operations. If set as a Server
   Control, it is sent to the server along with operation requests. If
   set as a Client Control, it is not sent to the server, but rather
   interpreted locally by the client.


2.8.1 Constructors

   public LDAPControl(String oid,
                      boolean critical,
                      byte[] value)

   Parameters are:

      oid            The type of the Control, as an OID.

      critical       If true, the LDAP operation will fail with
                      UNAVAILABLE_CRITICAL_EXTENSION if the server does
                      not support this Control.

      value          Control-specific data.


2.8.2 clone

   public Object clone()

   Returns a deep copy of the object.


2.8.3 getID

   public String getID()

   Returns the object identifier of the control.


2.8.4 getValue

   public byte[] getValue()

   Returns the control-specific data of the object.


2.8.5 isCritical

   public boolean isCritical()

Expires December, 2001                                       [Page 58]


JAVA LDAP API                                                June 2001



   Returns true if the control must be supported for an associated
   operation to be executed.


2.8.6 register

   public static void register(String oid, Class controlClass)

   Registers a class to be instantiated on receipt of a control with the
   given oid. Any previous registration for the oid is overridden. The
   controlClass MUST be an extension of LDAPControl.

   Parameters are:

      oid            The Object Identifier of the Control.

      controlClass   A class which can instantiate an LDAPControl.


2.8.7 setValue

   protected void setValue(byte[] value)

   Sets the control-specific data of the object. This method is for use
   by extensions of LDAPControl.

   Parameters are:

      value          The value to be assigned to the Control.


2.9 public class LDAPDITContentRuleSchema
                extends LDAPSchemaElement

   The LDAPDITContentRuleSchema class represents the definition of a DIT
   Content Rule. It is used to discover or modify additional auxiliary
   classes, mandatory and optional attributes, and restricted attributes
   in effect for an object class. See [ATTR] for a description of DIT
   content rule representation in LDAP.

2.9.1 Constructors

   public LDAPDITContentRuleSchema(String name,
                                   String oid,
                                   String description,
                                   boolean obsolete,
                                   String[] auxiliary,
                                   String[] required,
                                   String[] optional,
                                   String[] precluded,
                                   String[] aliases)

Expires December, 2001                                       [Page 59]


JAVA LDAP API                                                June 2001



   Constructs a DIT content rule for adding to or deleting from the
   schema.


   public LDAPDITContentRuleSchema(String raw)

   Constructs a DIT content rule from the raw String value returned on a
   schema query for "dITContentRules".

   Parameters are:

      name               Name of the content rule.

      oid                Object Identifier of the content rule - in
                         dotted-decimal format.

      description        Optional description of the content rule.

      obsolete           true if the content rule is obsolete.

      auxiliary          A list of auxiliary object classes allowed for
                         an entry to which this content rule applies.
                         These may either be specified by name or
                         numeric oid.

      required           A list of user attribute types that an entry
                         to which this content rule applies must
                         contain in addition to its normal set of
                         mandatory attributes. These may either be
                         specified by name or numeric oid.

      optional           A list of user attribute types that an entry
                         to which this content rule applies may contain
                         in addition to its normal set of optional
                         attributes. These may either be specified by
                         name or numeric oid.

      precluded          A list, consisting of a subset of the optional
                         user attribute types of the structural and
                         auxiliary object classes which are precluded
                         from an entry to which this content rule
                         applies. These may either be specified by name
                         or numeric oid.

      aliases            Optional list of additional names by which the
                         content rule may be known; null if there are
                         no aliases.


      raw                The raw String value returned on a Directory
                         query for "dITContentRules".

Expires December, 2001                                       [Page 60]


JAVA LDAP API                                                June 2001



2.9.2 getAuxiliaryClasses

   public String[] getAuxiliaryClasses()

   Returns the list of allowed auxiliary classes.

2.9.3 getOptionalAttributes

   public String[] getOptionalAttributes()

   Returns the list of additional optional attributes for an entry
   controlled by this content rule.


2.9.4 getPrecludedAttributes

   public String[] getPrecludedAttributes()

   Returns the list of precluded attributes for an entry controlled by
   this content rule.


2.9.5 getRequiredAttributes

   public String[] getRequiredAttributes()

   Returns the list of additional required attributes for an entry
   controlled by this content rule.


2.10 public class LDAPDITStructureRuleSchema
                extends LDAPSchemaElement

   The LDAPDITStructureRuleSchema class represents the definition of a
   DIT Structure Rule. It is used to discover or modify which object
   classes a particular object class may be subordinate to in the DIT.
   See [ATTR] for a description of DIT structure rule representation in
   LDAP.

2.10.1 Constructors

   public LDAPDITStructureRuleSchema(String name,
                                     int ruleID,
                                     String description,
                                     boolean obsolete,
                                     String nameForm,
                                     String[] superiorIDs,
                                     String[] aliases)

   Constructs a DIT structure rule for adding to or deleting from the
   schema.

Expires December, 2001                                       [Page 61]


JAVA LDAP API                                                June 2001




   public LDAPDITStructureRuleSchema(String raw)

   Constructs a DIT structure rule from the raw String value returned on
   a schema query for "dITStructureRules".

   Parameters are:

      name               Name of the structure rule.

      ruleID             Unique identifier of the structure rule. NOTE:
                         this is an integer, not a dotted-decimal
                         identifier. Structure rules aren't identified
                         by OID.

      description        Optional description of the structure rule.

      obsolete           true if the structure rule is obsolete.

      nameForm           Either the object identifier in dotted-decimal
                         form or the name of a name form. This is used
                         to indirectly refer to the object class that
                         this structure rule applies to.

      superiorIDs        List of superior structure rules - specified
                         by their integer ID. The object class
                         specified by this structure rule (via the
                         nameForm parameter) may only be subordinate in
                         the DIT to object classes of those represented
                         by the structure rules here; MAY be null.

      aliases            Optional list of additional names by which the
                         structure rule may be known; null if there are
                         no aliases.

      raw                The raw String value returned on a Directory
                         query for "dITStructureRules".

2.10.2 getNameForm

   public String getNameForm()

   Returns the NameForm that this structure rule controls. You can get
   the actual object class that this structure rule controls by calling
   getNameForm().getObjectClass().


2.10.3 getRuleID

   public int getRuleID()


Expires December, 2001                                       [Page 62]


JAVA LDAP API                                                June 2001


   Returns the rule ID for this structure rule. Note that this returns
   an integer rather than a dotted decimal OID. Objects of this class do
   not have an OID, thus getID will return null.


2.10.4 getSuperiors

   public String[] getSuperiors()

   Returns a list of all structure rules that are superior to this
   structure rule. To resolve to an object class, you need to first
   resolve the superior id to another structure rule, then call
   getNameForm().getObjectClass() on that structure rule.


2.11 public class LDAPDN

   A utility class representing a distinguished name (DN).


2.11.1 equals

   public static boolean equals(String dn1, String dn2)

   Compares the two strings per the distinguishedNameMatch matching rule
   [ATTR]. An API implementation MUST use caseIgnoreMatch equality
   matching for the attributes listed in section 2 of [ATTR].
   IllegalArgumentException is thrown if one or both DNs are invalid.
   UnsupportedOperationException is thrown if the API implementation is
   not able to determine if the DNs match or not.

   Parameters are:

      dn1            String form of first DN to compare.

      dn2            String form of second DN to compare.


2.11.2 escapeRDN

   public static String escapeRDN(String rdn)

   Returns the RDN after escaping the characters requiring escaping [4].
   For example, for the rdn "cn=Example, Inc", "cn=Example\, Inc" is
   returned.

   Parameters are:

      rdn            The RDN to escape.




Expires December, 2001                                       [Page 63]


JAVA LDAP API                                                June 2001


2.11.3 explodeDN

   public static String[] explodeDN(String dn,
                                    boolean noTypes)

   Returns the individual components of a distinguished name (DN).

   Parameters are:

      dn             Distinguished name, e.g. "cn=Babs
                      Jensen,ou=Accounting,dc=example,dc=com"

      noTypes        If true, returns only the values of the
                      components, and not the names, e.g. "Babs
                      Jensen", "Accounting", "Example", "com" - instead
                      of "cn=Babs Jensen","ou=Accounting","dc=Example",
                      and "dc=com".


2.11.4 explodeRDN

   public static String[] explodeRDN(String rdn,
                                     boolean noTypes)

   Returns the individual components of a relative distinguished name
   (RDN).

   Parameters are:

      rdn            Relative distinguished name, i.e. the left-most
                      component of a distinguished name.

      noTypes        If true, returns only the values of the
                      components, and not the names.

2.11.5 isValid

   public static boolean isValid(String dn)

   Returns true if the string conforms to distinguished name syntax
   (section 3 of [DN]. It MAY return true also if the string conforms to
   section 4 of [DN].

   Parameters are:

      dn             String to evaluate for distinguished name syntax.


2.11.6 normalize

   public static String normalize(String dn)


Expires December, 2001                                       [Page 64]


JAVA LDAP API                                                June 2001


   Returns the DN normalized by removal of non-significant space
   characters as per RFC 2253, section 4 [DN].

   Parameters are:

      dn             The DN to normalize.


2.11.7 unescapeRDN

   public static String unescapeRDN(String rdn)

   Returns the RDN after unescaping the characters requiring escaping
   [DN]. For example, for the rdn "cn=Example\, Inc", "cn=Example, Inc"
   is returned. IllegalArgumentException is thrown if the RDN cannot be
   parsed.

   Parameters are:

      rdn            The RDN to unescape.


2.12 public class LDAPEntry

   An LDAPEntry represents a single entry in a directory, consisting of
   a distinguished name (DN) and zero or more attributes. An instance of
   LDAPEntry is created in order to add an entry to a Directory, and
   instances are returned on a search by either enumerating an
   LDAPSearchResults, or calling LDAPSearchResult.getEntry.


2.12.1 Constructors

   public LDAPEntry()

   Constructs an empty entry.

   public LDAPEntry(String dn)

   Constructs a new entry with the specified distinguished name and with
   an empty attribute set.


   public LDAPEntry(String dn,
                    LDAPAttributeSet attrs)

   Constructs a new entry with the specified distinguished name and set
   of attributes.

   Parameters are:



Expires December, 2001                                       [Page 65]


JAVA LDAP API                                                June 2001


      dn             The distinguished name of the new entry. The
                      value is not validated. An invalid distinguished
                      name will cause adding of the entry to a
                      directory to fail.

      attrs          The initial set of attributes assigned to the
                      entry.


2.12.2 getAttribute

   public LDAPAttribute getAttribute(String attrName)

   Returns the attribute matching the specified attrName.

   Parameters are:

      attrName       The name of the attribute. See 2.3.5 for the
                      syntax and semantics relevant to this parameter.


2.12.3 getAttributeSet

   public LDAPAttributeSet getAttributeSet()

   Returns the attribute set of the entry. All base and subtype variants
   of all attributes are returned. The LDAPAttributeSet returned MAY be
   empty if there are no attributes in the entry.


   public LDAPAttributeSet getAttributeSet(String subtype)

   Returns an attribute set from the entry, consisting of only those
   attributes matching the specified subtype(s). This may be used to
   extract only a particular language variant subtype of each attribute,
   if it exists. "subtype" may be, for example, "lang-ja", "binary", or
   "lang-ja;phonetic". If more than one subtype is specified, separated
   with a semicolon, only those attributes with all of the named
   subtypes will be returned.  The LDAPAttributeSet returned may be
   empty if there are no matching attributes in the entry.

   Parameters are:

      subtype        One or more subtype specification(s), separated
                      with semicolons.  "lang-ja" and
                      "lang-en;phonetic" are valid subtype
                      specifications.


2.12.4 getDN

   public String getDN()

Expires December, 2001                                       [Page 66]


JAVA LDAP API                                                June 2001



   Returns the distinguished name of the entry.


2.13 public interface LDAPEntryComparator

   An object of this class can implement arbitrary sorting algorithms
   for search results.


2.13.1 isGreater

   public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2)

   Returns true if entry1 is to be considered greater than or equal to
   entry2, for the purpose of sorting.

   Parameters are:

      entry1         Target entry for comparison.

      entry2         Entry to be compared to.


2.14 public class LDAPException
                  extends Exception

   Thrown to indicate that an error has occurred. An LDAPException can
   result from physical problems (such as network errors) as well as
   problems with LDAP operations (for example, if the LDAP add operation
   fails because an entry already exists with the DN of the entry to be
   added).

   Most errors that occur throw this type of exception. The
   getLDAPResultCode() method returns the specific result code.


2.14.1 Constructors

   public LDAPException()

   Constructs a default exception with no specific error information.


   public LDAPException(String message,
                        int resultCode)

   Constructs an exception with a result code and a specified string as
   additional information.

   public LDAPException(String message,
                        int resultCode,

Expires December, 2001                                       [Page 67]


JAVA LDAP API                                                June 2001


                        Throwable rootException)

   Constructs an exception with a result code, a specified string, and
   an embedded root exception as additional information.

   public LDAPException(String message,
                        int resultCode,
                        String matchedDN)

   Constructs an exception with a result code, a specified string as
   additional information, and the maximal subset of a specified DN
   which could be matched by the server on a search operation.


   Parameters are:

      message        The additional error information

      resultCode     The result code returned

      matchedDN      The DN of the most immediate ancestor of a
                      specified search DN which could be found by the
                      server on a search operation

      rootException  An exception which caused the failure, if any


2.14.2 errorCodeToString

   public String errorCodeToString()

   Returns a String representing the result code in the default Locale.


   public static String errorCodeToString( int code )

   Returns a String representing an arbitrary result code in the default
   Locale, or null if there is no such code known to the API.


   public String errorCodeToString( Locale locale )

   Returns a String representing the result code in the specified
   Locale, or null if a String representation is not available for the
   requested Locale.


   public static String errorCodeToString( int code, Locale locale )

   Returns a String representing an arbitrary result code in the
   specified Locale, or null if there is no such code or if a String
   representation is not available for the requested Locale.

Expires December, 2001                                       [Page 68]


JAVA LDAP API                                                June 2001




   Parameters are:

      code           One of the result codes listed in "Result codes"
                      below.

      locale         A Locale in which to render the String.


2.14.3 getCause

   public Throwable getCause()

   Returns the lower level Exception which caused the failure, if any.
   For example, an IOException with additional information MAY be
   returned on a CONNECT_ERROR failure.


2.14.4 getLDAPErrorMessage

   public String getLDAPErrorMessage()

   Returns the error message, if this message is available (that is, if
   this message was set). If the message was not set, this method
   returns null.


2.14.5 getLDAPResultCode

   public int getLDAPResultCode()

   Returns the result code from the exception. The codes are defined as
   public final static int members of this class. If the exception is a
   result of error information returned from a directory operation, the
   code will be one of those defined in [LDAPv3]. Otherwise, a local
   error code is returned (see "Result codes" below).


2.14.6 getMatchedDN

   public String getMatchedDN()

   Returns the matchedDN value provided by the server in the response
   which generated this exception (it may be empty). If the exception is
   not due to a server response, null is returned.


2.14.7 toString

   public String toString()


Expires December, 2001                                       [Page 69]


JAVA LDAP API                                                June 2001


   Overrides the default toString implementation. It expands all the
   nested exceptions.


2.14.8 Result codes

   See [LDAPv3] for a discussion of the meanings and values of the
   codes. The corresponding ASN.1 name from [LDAPv3] is provided in
   parentheses.

        ADMIN_LIMIT_EXCEEDED (adminLimitExceeded)
        AFFECTS_MULTIPLE_DSAS (affectsMultipleDSAs)
        ALIAS_DEREFERENCING_PROBLEM (aliasDereferencingProblem)
        ALIAS_PROBLEM (aliasProblem)
        ATTRIBUTE_OR_VALUE_EXISTS (attributeOrValueExists)
        AUTH_METHOD_NOT_SUPPORTED (authMethodNotSupported)
        BUSY (busy)
        COMPARE_FALSE (compareFalse)
        COMPARE_TRUE (compareTrue)
        CONFIDENTIALITY_REQUIRED (confidentialityRequired)
        CONSTRAINT_VIOLATION (constraintViolation)
        ENTRY_ALREADY_EXISTS (entryAlreadyExists)
        INAPPROPRIATE_AUTHENTICATION (inappropriateAuthentication)
        INAPPROPRIATE_MATCHING (inappropriateMatching)
        INSUFFICIENT_ACCESS_RIGHTS (insufficientAccessRights)
        INVALID_ATTRIBUTE_SYNTAX (invalidAttributeSyntax)
        INVALID_CREDENTIALS (invalidCredentials)
        INVALID_DN_SYNTAX (invalidDNSyntax)
        IS_LEAF (isLeaf)
        LOOP_DETECT (loopDetect)
        NAMING_VIOLATION (namingViolation)
        NO_SUCH_ATTRIBUTE (noSuchAttribute)
        NO_SUCH_OBJECT (noSuchObject)
        NOT_ALLOWED_ON_NONLEAF (notAllowedOnNonLeaf)
        NOT_ALLOWED_ON_RDN (notAllowedOnRDN)
        OBJECT_CLASS_MODS_PROHIBITED (objectClassModsProhibited)
        OBJECT_CLASS_VIOLATION (objectClassViolation)
        OPERATIONS_ERROR (operationsError)
        OTHER (other)
        PROTOCOL_ERROR (protocolError)
        REFERRAL (referral)
        SASL_BIND_IN_PROGRESS (saslBindInProgress)
        SIZE_LIMIT_EXCEEDED (sizeLimitExceeded)
        STRONG_AUTH_REQUIRED (strongAuthRequired)
        SUCCESS (success)
        TIME_LIMIT_EXCEEDED (timeLimitExceeded)
        UNAVAILABLE (unavailable)
        UNAVAILABLE_CRITICAL_EXTENSION (unavailableCriticalExtension)
        UNDEFINED_ATTRIBUTE_TYPE (undefinedAttributeType)
        UNWILLING_TO_PERFORM (unwillingToPerform)

   Local errors, resulting from actions other than an operation on a

Expires December, 2001                                       [Page 70]


JAVA LDAP API                                                June 2001


   server, are among the following:

        AMBIGUOUS_RESPONSE (0x65)
        AUTH_UNKNOWN (0x56)
        CLIENT_LOOP  (0x60)
        CONNECT_ERROR (0x5b)
        CONTROL_NOT_FOUND (0x5d)
        DECODING_ERROR (0x54)
        ENCODING_ERROR (0x53)
        FILTER_ERROR (0x57)
        INVALID_RESPONSE (0x64)
        LOCAL_ERROR (0x52)
        LDAP_NOT_SUPPORTED (0x5c)
        LDAP_TIMEOUT (0x55)
        MORE_RESULTS_TO_RETURN (0x5f)
        NO_MEMORY (0x5a)
        NO_RESULTS_RETURNED (0x5e)
        REFERRAL_LIMIT_EXCEEDED (0x61)
        SERVER_DOWN (0x51)
        USER_CANCELLED (0x58)
        TLS_NOT_SUPPORTED (0x70)


2.15 public class LDAPExtendedOperation

   An LDAPExtendedOperation encapsulates an OID which uniquely
   identifies a particular extended operation, known to a particular
   server, and the data associated with the operation.


2.15.1 Constructors

   public LDAPExtendedOperation(String oid,
                                byte[] value)

   Constructs a new object with the specified object ID and data.

   Parameters are:

      oid            The object identifier of the operation.

      value          The operation-specific data of the operation.


2.15.2 getID

   public String getID()

   Returns the object identifier of the operation.




Expires December, 2001                                       [Page 71]


JAVA LDAP API                                                June 2001


2.15.3 getValue

   public byte[] getValue()

   Returns the operation-specific data (not a copy, a reference).


2.15.4 setValue

   protected void setValue(byte[] value)

   Sets the operation-specific data of the object. This method is for
   use by extensions of LDAPExtendedOperation.

   Parameters are:

      value          The value to be assigned to the object (as a
                      reference)


2.16 public class LDAPExtendedResponse
                  extends LDAPResponse

   An LDAPExtendedResponse object encapsulates a server response to an
   asynchronous extended operation request.


2.16.1 getID

   public String getID()

   Returns the OID of the response.


2.16.2 getValue

   public byte[] getValue()

   Returns the raw bytes of the value part of the response.


2.17 public interface LDAPListener

   Represents the message queue associated with a particular
   asynchronous LDAP operation or operations.


2.17.1 getMessageIDs

   public int[] getMessageIDs()



Expires December, 2001                                       [Page 72]


JAVA LDAP API                                                June 2001


   Returns the message IDs for all outstanding requests, i.e. requests
   for which a response has not been received from the server or which
   still have messages to be retrieved with getResponse. The last ID in
   the array is the messageID of the latest submitted request.


2.17.2 getResponse

   public LDAPMessage getResponse()throws LDAPException

   Blocks until a response is available, or until all operations
   associated with the object have completed or been canceled, and
   returns the response.

   public LDAPMessage getResponse(int msgid)throws LDAPException

   Blocks until a response is available for a particular message ID, or
   until all operations associated with the message ID have completed or
   been canceled, and returns the response. If there is no outstanding
   operation for the message ID (or if it is zero or a negative number),
   IllegalArgumentException is thrown.

   Parameters are:

      msgid              A particular message to query for responses
                         available.


2.17.3 isResponseReceived

   public boolean isResponseReceived()

   Reports true if any response has been received from the server and
   not yet retrieved with getResponse. If getResponse has been used to
   retrieve all messages received to this point, then isResponseReceived
   returns false.


   public boolean isResponseReceived(int msgid)

   Reports true if a response has been received from the server for a
   particular message ID but not retrieved with getResponse. If there is
   no outstanding operation for the message ID (or if it is zero or a
   negative number), IllegalArgumentException is thrown.


   Parameters are:

      msgid              A particular message to query for responses
                         available.



Expires December, 2001                                       [Page 73]


JAVA LDAP API                                                June 2001


2.17.4 merge

   public void merge(LDAPListener listener2)

   Merges two listeners. Moves/appends the content from another
   listener to this one.


2.18 public class LDAPMatchingRuleSchema
                  extends LDAPSchemaElement

   The LDAPMatchingRuleSchema class represents the definition of a
   matching rule. It is used to query matching rule syntax, and to add
   or delete a matching rule definition in a Directory. See [ATTR] for a
   description of matching rule representation in LDAP.


2.18.1 Constructors

   public LDAPMatchingRuleSchema(String name,
                                 String oid,
                                 String description,
                                 String[] attributes,
                                 String syntaxString,
                                 String[] aliases)

   public LDAPMatchingRuleSchema(String name,
                                 String oid,
                                 String description,
                                 boolean obsolete,
                                 String syntaxString,
                                 String[] aliases)

   Constructs a matching rule definition for adding to or deleting from
   a Directory.


   public LDAPMatchingRuleSchema(String rawMatchingRule,
                                 String rawMatchingRuleUse)

   Constructs a matching rule definition from the raw String values
   returned on a Directory query for "matchingRule" and for
   "matchingRuleUse" for the same rule.


   Parameters are:

      name               Name of the attribute.

      oid                Object Identifier of the attribute - in
                         dotted-decimal format.


Expires December, 2001                                       [Page 74]


JAVA LDAP API                                                June 2001


      description        Optional description of the attribute.

      attributes         OIDs of attributes to which the rule applies.
                         The parameter MAY be null.

      obsolete           true if this matching rule is obsolete.

      syntaxString       Object Identifier of the syntax that this
                         matching rule is valid for - in dotted-decimal
                         format.

      aliases            Optional list of additional names by which the
                         matching rule may be known; null if there are
                         no aliases.

      rawMatchingRule    The raw String value returned on a Directory
                         query for "matchingRule".


      rawMatchingRuleUse The raw String value returned on a Directory
                         query for "matchingRuleUse". The parameter MAY
                         be null.


2.18.2 getAttributes

   public String[] getAttributes()

   Returns the OIDs of the attributes to which this rule applies.


2.18.3 getSyntaxString

   public String getSyntaxString()

   Returns the OID of the syntax that this matching rule is valid for.


2.19 public class LDAPMatchingRuleUseSchema
                extends LDAPSchemaElement

   The LDAPMatchingRuleUseSchema class represents the definition of a
   matching rule use. It is used to discover or modify which attributes
   are suitable for use with an extensible matching rule. It contains
   the name and object identifier of a matching rule, and a list of
   attributes that it applies to.  See [ATTR] for a description of
   matching rule use representation in LDAP.

2.19.1 Constructors

   public LDAPMatchingRuleUseSchema(String name,
                                    String oid,

Expires December, 2001                                       [Page 75]


JAVA LDAP API                                                June 2001


                                    String description,
                                    boolean obsolete,
                                    String[] attributes,
                                    String[] aliases)

   Constructs a matching rule use definition for adding to or deleting
   from the schema.


   public LDAPMatchingRuleUseSchema(String raw)

   Constructs a matching rule use definition from the raw String value
   returned on a schema query for "matchingRuleUse".

   Parameters are:

      name               Name of the matching rule.

      oid                Object Identifier of the matching rule - in
                         dotted-decimal format.

      description        Optional description of the matching rule use.

      obsolete           true if the matching rule use is obsolete.

      attributes         List of attributes that this matching rule
                         applies to. These values may be either the
                         names or numeric oids of the attributes

      aliases            Optional list of additional names by which the
                         matching rule use may be known; null if there
                         are no aliases.

      raw                The raw String value returned on a Directory
                         query for "matchingRuleUse".

2.19.2 getAttributes

   public String[] getAttributes()

   Returns an array of all the attributes that this matching rule
   applies to.


2.20 public class LDAPMessage

   Base class for asynchronous LDAP request and response messages.


2.20.1 getControls

   public LDAPControl[] getControls()

Expires December, 2001                                       [Page 76]


JAVA LDAP API                                                June 2001



   Returns any controls in the message.


2.20.2 getMessageID

   public int getMessageID()

   Returns the message ID.


2.20.3 getType

   public int getType()

   Returns the LDAP operation type of the message. The type is one of
   the following:

      BIND_REQUEST (0x0)
      BIND_RESPONSE (0x1)
      UNBIND_REQUEST (0x2)
      SEARCH_REQUEST (0x3)
      SEARCH_RESPONSE (0x4)
      SEARCH_RESULT (0x5)
      MODIFY_REQUEST (0x6)
      MODIFY_RESPONSE (0x7)
      ADD_REQUEST (0x8)
      ADD_RESPONSE (0x9)
      DEL_REQUEST (0xa)
      DEL_RESPONSE (0xb)
      MODIFY_RDN_REQUEST (0xc)
      MODIFY_RDN_RESPONSE (0xd)
      COMPARE_REQUEST (0xe)
      COMPARE_RESPONSE (0xf)
      ABANDON_REQUEST (0x10)
      SEARCH_RESULT_REFERENCE (0x13)
      EXTENDED_REQUEST (0x17)
      EXTENDED_RESPONSE (0x18)


2.21 public class LDAPModification

   A single change specification for an LDAPAttribute.


2.21.1 Constructors

   public LDAPModification(int op,
                           LDAPAttribute attr)

   Specifies a modification to be made to an attribute.


Expires December, 2001                                       [Page 77]


JAVA LDAP API                                                June 2001


   Parameters are:

      op             The type of modification to make, which can be
                      one of the following:

               ADD                      The value should be added to
                                        the attribute

               DELETE                   The value should be removed
                                        from the attribute

               REPLACE                  The value should replace all
                                        existing values of the
                                        attribute

      attr           The attribute (possibly with values) to be
                      modified.


2.21.2 getAttribute

   public LDAPAttribute getAttribute()

   Returns the attribute (possibly with values) to be modified.


2.21.3 getOp

   public int getOp()

   Returns the type of modification specified by this object.


2.21.4 Constants of LDAPModification

      ADD     (0)    The value should be added to the attribute

      DELETE  (1)    The value should be removed from the attribute

      REPLACE (2)    The value should replace all existing values of
                      the attribute


2.22 public class LDAPModificationSet

   A collection of modifications to be made to the attributes of a
   single entry.


2.22.1 Constructors

   public LDAPModificationSet()

Expires December, 2001                                       [Page 78]


JAVA LDAP API                                                June 2001



   Constructs a new, empty set of modifications.


2.22.2 add

   public void add(int op,
                   LDAPAttribute attr)

   Specifies another modification to be added to the set of
   modifications.

   Parameters are:

      op             The type of modification to make, as described
                      for LDAPModification.

      attr           The attribute (possibly with values) to be
                      modified.


2.22.3 elementAt

   public LDAPModification elementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Retrieves a particular LDAPModification object at the position
   specified by the index.

   Parameters are:

      index          Index of the modification to get.


2.22.4 remove

   public void remove(String name)

   Removes the first attribute with the specified name in the set of
   modifications.

   Parameters are:

      name           Name of the attribute to be removed.


2.22.5 removeElementAt

   public void removeElementAt(int index)
                               throws ArrayIndexOutOfBoundsException



Expires December, 2001                                       [Page 79]


JAVA LDAP API                                                June 2001


   Removes a particular LDAPModification object at the position
   specified by the index.

   Parameters are:

      index          Index of the modification to remove.


2.22.6 size

   public int size()

   Retrieves the number of LDAPModification objects in this set.


2.23 public class LDAPNameFormSchema
                extends LDAPSchemaElement

   The LDAPNameFormSchema class represents the definition of a Name
   Form. It is used to discover or modify the allowed naming attributes
   for a particular object class. See [ATTR] for a description of name
   form representation in LDAP.

2.23.1 Constructors

   public LDAPNameFormSchema(String name,
                             String oid,
                             String description,
                             boolean obsolete,
                             String objectClass,
                             String[] required,
                             String[] optional,
                             String[] aliases)

   Constructs a name form for adding to or deleting from the schema.


   public LDAPNameFormSchema(String raw)

   Constructs a DIT content rule from the raw String value returned on a
   schema query for "nameForms".

   Parameters are:

      name               Name of the name form.

      oid                Object Identifier of the name form - in
                         dotted-decimal format.

      description        Optional description of the name form.

      obsolete           true if the name form is obsolete.

Expires December, 2001                                       [Page 80]


JAVA LDAP API                                                June 2001



      objectClass        The object to which this name form applies.
                         This may either be specified by name or
                         numeric oid.

      required           A list of the attributes that must be present
                         in the RDN of an entry that this name form
                         controls. These may either be specified by
                         name or numeric oid.

      optional           A list of the attributes that may be present
                         in the RDN of an entry that this name form
                         controls. These may either be specified by
                         name or numeric oid.

      aliases            Optional list of additional names by which the
                         name form may be known; null if there are no
                         aliases.

      raw                The raw String value returned on a Directory
                         query for "nameForms".


2.23.2 getObjectClass

   public String getObjectClass()

   Returns the name of the object class that this name form applies to.


2.23.3 getOptionalNamingAttributes

   public String[] getOptionalNamingAttributes()

   Returns the list of optional naming attributes for an entry
   controlled by this content rule.


2.23.4 getRequiredNamingAttributes

   public String[]getRequiredNamingAttributes()

   Returns the list of required naming attributes for an entry
   controlled by this name form.


2.24 public class LDAPObjectClassSchema
                extends LDAPSchemaElement

   The LDAPObjectClassSchema class represents the definition of an
   object class. It is used to query the syntax of an object class, and


Expires December, 2001                                       [Page 81]


JAVA LDAP API                                                June 2001


   to add or delete an object class definition in a Directory. See
   [ATTR] for a description of object class representation in LDAP.


2.24.1 Constructors

   public LDAPObjectClassSchema(String name,
                                String oid,
                                String[] superiors,
                                String description,
                                String[] required,
                                String[] optional,
                                int type,
                                String[] aliases,
                                boolean obsolete)

   Constructs an object class definition for adding to or deleting from
   a Directory.


   public LDAPObjectClassSchema(String raw)

   Constructs an object class definition from the raw String value
   returned on a Directory query for "objectclasses".


   Parameters are:

      name           Name of the object class.

      oid            Object Identifier of the object class - in
                      dotted-decimal format.

      description    Optional description of the object class.

      superiors      The object classes this one derives from.

      required       A list of attributes required for an entry with
                      this object class.

      optional       A list of attributes acceptable but not required
                      for an entry with this object class.

      type           One of ABSTRACT, AUXILIARY, or STRUCTURAL. These
                      are constants defined in LDAPObjectClassSchema.

      aliases        Optional list of additional names by which the
                     object class may be known; null if there are no
                     aliases.

      obsolete       true if this object class is obsolete.


Expires December, 2001                                       [Page 82]


JAVA LDAP API                                                June 2001


      raw            The raw String value returned on a Directory
                      query for "objectclasses".


2.24.2 getOptionalAttributes

   public String[] getOptionalAttributes()

   Returns a list of attributes acceptable but not required of an entry
   with this object class.


2.24.3 getRequiredAttributes

   public String[] getRequiredAttributes()

   Returns a list of attributes required of an entry with this object
   class.


2.24.4 getSuperiors

   public String[] getSuperiors()

   Returns the object classes which this one derives from.


2.24.5 getType

   public int getType()

   Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are
   constants defined in LDAPObjectClassSchema.


2.25 public interface LDAPRebind
                      extends LDAPReferralHandler

   Used to provide credentials for reauthentication on processing a
   referral.


2.25.1 getRebindAuthentication

   public LDAPRebindAuth getRebindAuthentication(String host, int port)


   Returns an object which can provide credentials for authenticating to
   a server at the provided host name and port number.

   Parameters are:


Expires December, 2001                                       [Page 83]


JAVA LDAP API                                                June 2001


      host           Contains a host identifier representing the IP
                      address of a host running an LDAP server. See
                      2.6.8 for a discussion of valid identifiers.

      port           Contains the TCP port number to connect to.


2.26 public class LDAPRebindAuth

   Represents information used to authenticate the client in cases where
   the client follows referrals automatically.

2.26.1 Constructors

   public LDAPRebindAuth( String dn,
                          String password )

   Constructs information that is used by the client for authentication
   when following referrals automatically.

   public LDAPRebindAuth( String dn,
                          byte[] password )

   Constructs information that is used by the client for authentication
   when following referrals automatically.


   Parameters are:

      dn             Distinguished name to use in authenticating to
                      the server.

      password       Password to use in authenticating to the server.


2.26.2 getDN

   public String getDN()

   Returns the distinguished name to be used for reauthentication on
   automatic referral following.


2.26.3 getPassword

   public byte[] getPassword()

   Returns the password to be used for reauthentication on automatic
   referral following.




Expires December, 2001                                       [Page 84]


JAVA LDAP API                                                June 2001


2.27 public class LDAPReferralException
                  extends LDAPException

   This exception, derived from LDAPException, is thrown when a server
   returns a referral or search reference on a synchronous request and
   automatic referral following has not been enabled.


2.27.1 Constructors

   public LDAPReferralException()

   Constructs a default exception with no specific error information.


   public LDAPReferralException(String message)

   Constructs a default exception with a specified string as additional
   information. This form is used for lower-level errors.


   public LDAPReferralException(String message,
                                Throwable rootException)

   Constructs a default exception with a specified string as additional
   information and an exception that indicates a failure to follow a
   referral.  This exception applies only to synchronous operations and
   is thrown only on receipt of a referral or search reference when the
   referral or search reference was not followed.


   public LDAPReferralException(String message,
                                int resultCode,
                                String serverMessage)

   public LDAPReferralException(String message,
                                int resultCode,
                                String serverMessage,
                                Throwable rootException)

   Parameters are:

      message        The additional error information.

      resultCode     The result code returned

      serverMessage  Error message specifying additional information
                      from the server.

      rootException  An exception which caused referral following to
                      fail


Expires December, 2001                                       [Page 85]


JAVA LDAP API                                                June 2001



2.27.2 getFailedReferral

   public String getFailedReferral()

   Gets the referral URL that could not be followed. If multiple URLs
   are in the list, and none could be followed, the method returns one
   of them.


2.27.3 getReferrals

   public String[] getReferrals()

   Gets the list of referral URLs (LDAP URLs to other servers) returned
   by the LDAP server.  If the scope field of a referral of type
   SearchResultReference must be modified in order to follow the
   referral, the API implementation MUST modify the scope field of the
   URL before returning the URL to the application.

   The referral list MAY include URLs of a type other than ones for an
   LDAP server (i.e. a referral URL other than ldap://something).



2.27.4 setFailedReferral

   public void setFailedReferral(String url)

   Sets a referral URL that could not be followed.


2.28 public interface LDAPReferralHandler

   Shared ancestor to the two types of referal objects - LDAPBind and
   LDAPRebind.


2.29 public class LDAPResponse
                  extends LDAPMessage

   Represents the response to a particular asynchronous LDAP operation.


2.29.1 getErrorMessage

   public String getErrorMessage()

   Returns any error message in the response.




Expires December, 2001                                       [Page 86]


JAVA LDAP API                                                June 2001


2.29.2 getMatchedDN

   public String getMatchedDN()

   Returns the partially matched DN field, if any, in a server response.


2.29.3 getReferrals

   public String[] getReferrals()

   Returns list of all referral URLs, if any, in a server response.


2.29.4 getResultCode

   public int getResultCode()

   Returns the result code in a server response, as defined in [5].


2.30 public class LDAPResponseListener
                  implements LDAPListener

   Represents the message queue associated with a particular
   asynchronous LDAP operation or operations.


2.30.1 getMessageIDs

   public int[] getMessageIDs()

   Returns the message IDs for all outstanding requests, i.e. requests
   for which a response has not been received from the server or which
   still have messages to be retrieved with getResponse. The last ID in
   the array is the messageID of the latest submitted request.


2.30.2 getResponse

   public LDAPMessage getResponse()throws LDAPException

   Blocks until a response is available, or until all operations
   associated with the object have completed or been canceled, and
   returns the response.

   public LDAPMessage getResponse(int msgid)throws LDAPException

   Blocks until a response is available for a particular message ID, or
   until all operations associated with the message ID have completed or
   been canceled, and returns the response. If there is no outstanding


Expires December, 2001                                       [Page 87]


JAVA LDAP API                                                June 2001


   operation for the message ID (or if it is zero or a negative number),
   IllegalArgumentException is thrown.

   Parameters are:

      msgid              A particular message to query for responses
                         available.


2.30.3 isResponseReceived

   public boolean isResponseReceived()

   Reports true if any response has been received from the server and
   not yet retrieved with getResponse. If getResponse has been used to
   retrieve all messages received to this point, then isResponseReceived
   returns false.


   public boolean isResponseReceived(int msgid)

   Reports true if a response has been received from the server for a
   particular message ID. If there is no outstanding operation for the
   message ID (or if it is zero or a negative number),
   IllegalArgumentException is thrown.


   Parameters are:

      msgid              A particular message to query for responses
                         available.

2.30.4 merge

   public void merge(LDAPListener listener2)

   Merges two response listeners. Moves/appends the content from another
   listener to this one.


2.31 public class LDAPSchema

   The LDAPSchema supports querying a Directory Server for its schema,
   and obtaining definitions of individual schema elements.


2.31.1 Constructors

   public LDAPSchema()

   Constructs an empty LDAPSchema object.


Expires December, 2001                                       [Page 88]


JAVA LDAP API                                                June 2001



2.31.2 fetchSchema

   public void fetchSchema(LDAPConnection ld) throws LDAPException

   Retrieves the entire schema from a Directory Server.

   public void fetchSchema(LDAPConnection ld,
                           String dn) throws LDAPException

   Retrieves the schema controlling a particular entry in the Directory
   Server.

   The fetchSchema methods are the only methods that interact with a
   Directory Server. The other methods access information acquired
   through fetchSchema. An LDAPException is thrown as for
   LDAPConnection.search() (2.6.34) if the schema cannot be retrieved
   with the specified connection, or if the subschemaSubentry attribute
   used to locate the schema contains multiple values.

   Parameters are:

      ld             An open connection to a Directory Server.

      dn             Distinguished name of the entry from which to
                      return schema. The subschemaSubentry attribute of
                      the entry is queried to find the location of the
                      schema to be returned.


2.31.3 getAttribute

   public LDAPAttributeSchema getAttribute( String name )

   Returns a particular attribute definition, or null if not found.

   Parameters are:

      name           Name of the attribute for which a definition is
                      to be returned.


2.31.4 getAttributeNames

   public Enumeration getAttributeNames()

   Returns an enumeration of attribute names.


2.31.5 getAttributes

   public Enumeration getAttributes()

Expires December, 2001                                       [Page 89]


JAVA LDAP API                                                June 2001



   Returns an enumeration of attribute definitions.


2.31.6 getDITContentRule

   public LDAPDITContentRuleSchema getDITContentRule( String name )

   Returns a particular content rule definition, or null if not found.

   Parameters are:

      name           Name of the content rule for which a definition
                      is to be returned.


2.31.7 getDITContentRuleNames

   public Enumeration getDITContentRuleNames ()

   Returns an enumeration of content rule names.


2.31.8 getDITContentRules

   public Enumeration getDITContentRules()

   Returns an enumeration of LDAPDITContentRuleSchema objects.


2.31.9 getDITStructureRule

   public LDAPDITStructureRuleSchema getDITStructureRule( String name )

   public LDAPDITStructureRuleSchema getDITStructureRule( int id )


   Returns a particular structure rule definition, or null if not found.

   Parameters are:

      name           Name of the structure rule for which a definition
                      is to be returned.

      id             Identifier of the structure rule for which a
                      definition is to be returned.


2.31.10 getDITStructureRuleNames

   public Enumeration getDITStructureRuleNames ()


Expires December, 2001                                       [Page 90]


JAVA LDAP API                                                June 2001


   Returns an enumeration of structure rule names.


2.31.11 getDITStructureRules

   public Enumeration getDITStructureRules()

   Returns an enumeration of LDAPDITStructureRuleSchema objects.


2.31.12 getMatchingRule

   public LDAPMatchingRuleSchema getMatchingRule( String name )

   Returns a particular matching rule definition, or null if not found.

   Parameters are:

      name           Name of the matching rule for which a definition
                      is to be returned.

2.31.13 getMatchingRuleNames

   public Enumeration getMatchingRuleNames()

   Returns an enumeration of matching rule names.


2.31.14 getMatchingRules

   public Enumeration getMatchingRules()

   Returns an enumeration of matching rule definitions.


2.31.15 getMatchingRuleUse

   public LDAPMatchingRuleUseSchema getMatchingRuleUse( String name )

   Returns a particular matching rule use definition, or null if not
   found.

   Parameters are:

      name           Name of the matching rule use for which a
                      definition is to be returned.


2.31.16 getMatchingRuleUseNames

   public Enumeration getMatchingRuleUseNames()


Expires December, 2001                                       [Page 91]


JAVA LDAP API                                                June 2001


   Returns an enumeration of matching rule use names.


2.31.17 getMatchingRuleUses

   public Enumeration getMatchingRuleUses()

   Returns an enumeration of LDAPMatchingRuleUseSchema objects.


2.31.18 getNameForm

   public LDAPNameFormSchema getNameForm( String name )

   Returns a particular name form definition, or null if not found.

   Parameters are:

      name           Name of the name form for which a definition is
                      to be returned.


2.31.19 getNameFormNames

   public Enumeration getNameFormNames ()

   Returns an enumeration of name form names.


2.31.20 getNameForms

   public Enumeration getNameForms()

   Returns an enumeration of LDAPNameFormSchema objects.


2.31.21 getObjectClass

   public LDAPObjectClassSchema getObjectClass( String name )

   Returns a particular object class definition, or null if not found.

   Parameters are:

      name           Name of the object class for which a definition
                      is to be returned.


2.31.22 getObjectClasses

   public Enumeration getObjectClasses()


Expires December, 2001                                       [Page 92]


JAVA LDAP API                                                June 2001


   Returns an enumeration of object class definitions.


2.31.23 getObjectClassNames

   public Enumeration getObjectClassNames()

   Returns an enumeration of object class names.


2.31.24 getSyntax

   public LDAPSyntaxSchema getSyntax( String oid )

   Returns a particular syntax definition, or null if not found.

   Parameters are:

      oid            Object identifier of the syntax for which a
                      definition
                     is to be returned.


2.31.25 getSyntaxes

   public Enumeration getSyntaxes()

   Returns an enumeration of LDAPSyntaxSchema objects.


2.32 public abstract class LDAPSchemaElement

   The LDAPSchemaElement class is the base class for representing schema
   elements in LDAP.


2.32.1 add

   public void add(LDAPConnection ld) throws LDAPException

   public void add(LDAPConnection ld, String dn) throws LDAPException

   Adds the definition to a Directory. An exception is thrown if the
   definition can't be added. The signature without a dn uses the root
   DSE ("") as the entry at which to find the subschemaSubentry. An
   LDAPException with the result code CONSTRAINT_VIOLATION is thrown if
   more than one subschemaSubentry value is found in the entry.

   Parameters are:




Expires December, 2001                                       [Page 93]


JAVA LDAP API                                                June 2001


      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to add a schema definition.

      dn             Entry at which to determine the subschemaSubentry
                      to which the schema element is to be added.


2.32.2 getAliases

   public String[] getAliases()

   Returns an array of alternative names of the element. With respect to
   the protocol-level schema element syntax definition of [ATTR], the
   array consists of all values but the first of the NAME qualifier.


2.32.3 getDescription

   public String getDescription()

   Returns the description of the element. With respect to the protocol-
   level schema element syntax definition of [ATTR], the value is that
   of the DESC qualifier.


2.32.4 getName

   public String getName()

   Returns the name of the element. With respect to the protocol-level
   schema element syntax definition of [ATTR], the value is that of the
   first NAME qualifier.


2.32.5 getID

   public String getID()

   Returns the Object Identifier of the element.


2.32.6 getQualifier

   public String[] getQualifier(String name)

   Returns an array of all values of a specified optional or
   experimental qualifier of the element. This method may be used to
   access the values of vendor-specific qualifiers (which begin with "X-
   " [ATTR]).

   Parameters are:

Expires December, 2001                                       [Page 94]


JAVA LDAP API                                                June 2001



      name           The name of the qualifier, case-sensitive.


2.32.7 getQualifierNames

   public Enumeration getQualifierNames()

   Returns an enumeration of all qualifiers of the element which are not
   defined in [ATTR].


2.32.8 getValue

   public String getValue()

   Returns a String in a format suitable for directly adding to a
   Directory, as a value of the particular schema element attribute.


2.32.9 isObsolete

   public boolean isObsolete()

   Returns true if the element has the OBSOLETE qualifier in its LDAP
   definition [ATTR].


2.32.10 modify

   public void modify(LDAPConnection ld
                      LDAPSchemaElement newValue) throws LDAPException

   public void modify(LDAPConnection ld
                      LDAPSchemaElement newValue,
                      String dn) throws LDAPException

   Replace a single value of the schema element definition in the
   schema. An exception is thrown if the definition can't be modified.

   Parameters are:

      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to modify a schema definition.

      newValue       The new schema element value.

      dn             Entry at which to determine the subschemaSubentry
                      to store the schema change in.



Expires December, 2001                                       [Page 95]


JAVA LDAP API                                                June 2001


2.32.11 remove

   public void remove(LDAPConnection ld) throws LDAPException

   public void remove(LDAPConnection ld, String dn) throws LDAPException

   Removes the definition from a Directory. An exception is thrown if
   the definition can't be removed.

   Parameters are:

      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to remove a schema definition.

      dn             Entry at which to determine the subschemaSubentry
                      to remove the schema element from.


2.32.12 setQualifier

   public void setQualifier(String name, String[] values)

   Sets the values of a specified optional or experimental qualifier of
   the element. This method may be used to set the values of vendor-
   specific qualifiers (which begin with "X-" [ATTR]).

   Parameters are:

      name           The name of the qualifier, case-sensitive.

      values         The values to set for the qualifier.


2.33 public class LDAPSearchConstraints
                  extends LDAPConstraints

   A set of options to control a search operation. There is always an
   LDAPSearchConstraints associated with an LDAPConnection object; its
   values can be changed with LDAPConnection.setSearchConstraints, or
   overridden by passing an LDAPConstraints object to the search
   operation.


2.33.1 Constructors

   public LDAPSearchConstraints()

   Constructs an LDAPSearchConstraints object that specifies the default
   set of search constraints.



Expires December, 2001                                       [Page 96]


JAVA LDAP API                                                June 2001


   public LDAPSearchConstraints(int msLimit,
                                int serverTimeLimit,
                                int dereference,
                                int maxResults,
                                boolean doReferrals,
                                int batchSize,
                                LDAPReferralHandler binder,
                                int hop_limit)

   Constructs a new LDAPSearchConstraints object and allows specifying
   the operational constraints in that object.

   Parameters are:

      msLimit         Maximum time in milliseconds to wait for results
                      (0 by default, which means that there is no
                      maximum time limit). This is an interface-imposed
                      limit.

      serverTimeLimit  Maximum time in seconds that the server should
                      spend returning results. This is a server-imposed
                      limit. The default of 0 means no time limit.

      dereference     Specifies when aliases should be dereferenced.
                      MUST be either DEREF_NEVER, DEREF_FINDING,
                      DEREF_SEARCHING, or DEREF_ALWAYS (DEREF_NEVER by
                      default).

      maxResults      Maximum number of search results to return (1000
                      by default).

      doReferrals     Specify true to follow referrals automatically,
                      or false to throw an LDAPReferralException error
                      if the server sends back a referral (false by
                      default). It is ignored for asynchronous
                      operations.

      batchSize       Specify the number of results to block on during
                      enumeration. 0 means to block until all results
                      are in (1 by default). It is ignored for
                      asynchronous operations.

      binder         Custom authentication processor, called when the
                      LDAPConnection needs to authenticate, typically
                      on following a referral. null MAY be specified to
                      indicate default authentication processing. The
                      object implements either the LDAPBind or the
                      LDAPRebind interface. It is ignored for
                      asynchronous operations.

      hop_limit       Maximum number of referrals to follow in a
                      sequence when attempting to resolve a request,

Expires December, 2001                                       [Page 97]


JAVA LDAP API                                                June 2001


                      when doing automatic referral following. It is
                      ignored for asynchronous operations. The value is
                      10 by default.


2.33.2 getBatchSize

   public int getBatchSize()

   Returns the number of results to block on during enumeration of
   search results. This SHOULD be 0 if intermediate results are not
   needed, and 1 if results are to be processed as they come in.


2.33.3 getDereference

   public int getDereference()

   Specifies when aliases should be dereferenced. Returns either
   DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or
   DEREF_ALWAYS.


2.33.4 getMaxResults

   public int getMaxResults()

   Returns the maximum number of search results to be returned; 0 means
   no limit.


2.33.5 getServerTimeLimit

   public int getServerTimeLimit()

   Reports the maximum number of seconds that the server is to wait when
   returning search results while using this constraint object


2.33.6 setBatchSize

   public void setBatchSize(int batchSize)

   Sets the suggested number of results to block on during enumeration
   of search results. This SHOULD be 0 if intermediate results are not
   needed, and 1 if results are to be processed as they come in.  The
   default is 1.

   Parameters are:

      batchSize      Blocking size on search enumerations.


Expires December, 2001                                       [Page 98]


JAVA LDAP API                                                June 2001



2.33.7 setDereference

   public void setDereference(int dereference)

   Sets a preference indicating whether or not aliases should be
   dereferenced, and if so, when.

   Parameters are:

      dereference    Either DEREF_NEVER, DEREF_FINDING,
                      DEREF_SEARCHING, or DEREF_ALWAYS.


2.33.8 setMaxResults

   public void setMaxResults(int maxResults)

   Sets the maximum number of search results to be returned; 0 means no
   limit.  The default is 1000.

   Parameters are:

      maxResults     Maximum number of search results to return.


2.33.9 setServerTimeLimit

   public void setServerTimeLimit(int seconds)

   Sets the maximum number of seconds that the server is to wait when
   returning search results. The parameter is only recognized on search
   operations.


2.33.10 Constants of LDAPSearchConstraints

      DEREF_NEVER (0)     Aliases are never dereferenced.

      DEREF_SEARCHING (1) Aliases are dereferenced when searching the
                      entries beneath the starting point of the search
                      (but not when finding the starting entry).

      DEREF_FINDING (2)   Aliases are dereferenced when finding the
                      starting point for the search (but not when
                      searching under that starting entry).

      DEREF_ALWAYS (3)   Aliases are always dereferenced (both when
                      finding the starting point for the search and
                      when searching under that starting entry).



Expires December, 2001                                       [Page 99]


JAVA LDAP API                                                June 2001


2.34 public class LDAPSearchListener
                  implements LDAPListener

   An LDAPSearchListener manages search results and references returned
   on one or more asynchronous search requests.


2.34.1 getMessageIDs

   public int[] getMessageIDs()

   Returns the message IDs for all outstanding requests, i.e. requests
   for which a response has not been received from the server or which
   still have messages to be retrieved with getResponse. The last ID in
   the array is the messageID of the latest submitted request.


2.34.2 getResponse

   public LDAPMessage getResponse() throws LDAPException

   Blocks until a response is available, or until all operations
   associated with the object have completed or been canceled, and
   returns the response.

   public LDAPMessage getResponse(int msgid) throws LDAPException

   Blocks until a response is available for a particular message ID, or
   until all operations associated with the message ID have completed or
   been canceled, and returns the response. If there is no outstanding
   operation for the message ID (or if it is zero or a negative number),
   IllegalArgumentException is thrown.

   Parameters are:

      msgid              A particular message to query for responses
                         available.


2.34.3 isComplete


   public boolean isComplete(int msgid)

   Reports true if all results have been received for a particular
   message ID. For search, it is true if a searchResultDone response has
   been received from the server for the id. There may still be messages
   waiting to be retrieved with getResponse. If there is no outstanding
   operation for the message ID (or if it is zero or a negative number),
   IllegalArgumentException is thrown.



Expires December, 2001                                      [Page 100]


JAVA LDAP API                                                June 2001


   Parameters are:

      msgid              A particular message to query for completion.


2.34.4 isResponseReceived

   public boolean isResponseReceived()

   Reports true if any response has been received from the server and
   not yet retrieved with getResponse. If getResponse has been used to
   retrieve all messages received to this point, then isResponseReceived
   returns false.


   public boolean isResponseReceived(int msgid)

   Reports true if a response has been received from the server for a
   particular message ID. If the message ID is zero or a negative
   number, IllegalArgumentException is thrown.


   Parameters are:

      msgid              A particular message to query for responses
                         available.


2.34.5 merge

   public void merge(LDAPSearchListener listener2)

   Merges two search listeners. Moves/appends the content from another
   search listener to this one.


2.35 public class LDAPSearchResult
                  extends LDAPMessage

   An LDAPSearchResult object encapsulates a single asynchronous search
   result.


2.35.1 getEntry

   public LDAPEntry getEntry()

   Returns the entry of a server search response.


2.36 public class LDAPSearchResultReference
                  extends LDAPMessage

Expires December, 2001                                      [Page 101]


JAVA LDAP API                                                June 2001



   An LDAPSearchResultReference object encapsulates a continuation
   reference from an asynchronous search operation.


2.36.1 getReferrals

   public String[] getReferrals()

   Returns the list of any continuation reference URLs in the object.


2.37 public class LDAPSearchResults
                  implements Enumeration

   An LDAPSearchResults object is returned from a synchronous search
   operation. It provides access to all results received during the
   operation (entries and exceptions).


2.37.1 getCount

   public int getCount()

   Returns a count of the entries and exceptions in the search result.
   If the search is asynchronous (batch size not 0), this reports the
   number of results received so far.


2.37.2 getResponseControls

   public LDAPControl[] getResponseControls()

   Returns the latest Server Controls returned by a Directory Server
   in the context of this search request.


2.37.3 hasMoreElements

   public boolean hasMoreElements()

   Specifies whether or not there are more search results in the
   enumeration. If true, there are more search results.


2.37.4 next

   public LDAPEntry next() throws LDAPException

   Returns the next result in the enumeration as an LDAPEntry. If



Expires December, 2001                                      [Page 102]


JAVA LDAP API                                                June 2001


   automatic referral following is disabled or a referral was not
   followed, next() will throw an LDAPReferralException when the
   referral is received.


2.37.5 nextElement

   public Object nextElement()

   Returns the next result in the enumeration as an Object. This the
   default implementation of Enumeration.nextElement(). The returned
   value may be an LDAPEntry or an LDAPException.


2.37.6 sort

   public void sort(LDAPEntryComparator comp)

   Sorts all entries in the results using the provided comparison
   object. If the object has been partially or completely enumerated,
   only remaining elements are sorted. Sorting the results requires that
   they all be present. This implies that
   LDAPSearchResults.nextElement() will always block until all results
   have been retrieved, after a sort operation.

   The LDAPCompareAttrNames class is provided to support the common need
   to collate by a single or multiple attribute values, in ascending or
   descending order.  Examples are:

       res.sort(new LDAPCompareAttrNames("cn"));

       res.sort(new LDAPCompareAttrNames("cn", false));

       String[] attrNames = { "sn", "givenname" };
       res.sort(new LDAPCompareAttrNames(attrNames));

   Parameters are:

      comp            An object that implements the LDAPEntryComparator
                      interface to compare two objects of type
                      LDAPEntry.


2.38 public interface LDAPSocketFactory

   Used to construct a socket connection for use in an LDAPConnection.
   An implementation of this interface may, for example, provide a
   TLSSocket connected to a secure server.


2.38.1 makeSocket


Expires December, 2001                                      [Page 103]


JAVA LDAP API                                                June 2001


   public Socket makeSocket(String host, int port)
                            throws IOException, UnknownHostException


   Returns a socket connected using the provided host name and port
   number.

   Parameters are:

      host           Contains a host identifier representing the IP
                      address of a host running an LDAP server to
                      connect to. See 2.6.8 for a discussion of valid
                      identifiers.

      port           Contains the TCP port number to connect to or
                      contact. The default LDAP port is 389.


2.39 public class LDAPSyntaxSchema
                extends LDAPSchemaElement

   The LDAPSyntaxSchema class represents the definition of a syntax. It
   is used to discover the known set of syntaxes in effect for the
   subschema. See [ATTR] for a description of syntax representation in
   LDAP.
   Note that though this extends LDAPSchemaElement, it does not use the
   name or obsolete members, subsequently calls to getName always return
   null and isObsolete always returns false. There is also no matching
   getSyntaxNames method in LDAPSchema.


2.39.1 Constructors

   public LDAPSyntaxSchema(String oid,
                           String description)

   Constructs a syntax for adding to or deleting from the schema. Note
   that adding and removing syntaxes is not typically a supported
   feature of LDAP servers.


   public LDAPSyntaxSchema(String raw)

   Constructs a syntax from the raw String value returned on a schema
   query for "LDAPSyntaxes".

   Parameters are:

      oid            Object Identifier of the syntax - in dotted-
                      decimal format.

      description    Optional description of the syntax.

Expires December, 2001                                      [Page 104]


JAVA LDAP API                                                June 2001



      raw            The raw String value returned on a Directory
                      query for "ldapSyntaxes".


2.40 public interface LDAPUnsolicitedNotificationListener

   An object that implements this interface can be notified when
   unsolicited messages arrive from the server. A client registers the
   object with LDAPConnection.addUnsolicitedNotificationListener.


2.40.1 messageReceived

   public void messageReceived(LDAPExtendedResponse msg)

   The method is called when an unsolicited message arrives from a
   server, if the object has registered with
   LDAPConnection.addUnsolicitedNotificationListener.

   Parameters are:

      msg            An unsolicited message received from the server.


2.41 public class LDAPUrl

   Encapsulates parameters of an LDAP Url query, as defined in
   [LDAPURL].  An LDAPUrl object can be passed to LDAPConnection.search
   to retrieve search results.


2.41.1 Constructors

   public LDAPUrl(String url) throws MalformedURLException

   Constructs a URL object with the specified string as URL.


   public LDAPUrl(String host,
                  int port,
                  String dn)

   Constructs a URL object with the specified host, port, and DN. This
   form is used to create URL references to a particular object in the
   directory.

   public LDAPUrl(String host,
                  int port,
                  String dn,
                  String[] attrNames,
                  int scope,

Expires December, 2001                                      [Page 105]


JAVA LDAP API                                                June 2001


                  String filter)

   Constructs an LDAP URL with all fields explicitly assigned, to
   specify an LDAP search operation.

   Parameters are:

      url            An LDAP URL string, e.g.
                      "ldap://ldap.example.com:80/dc=example,dc=com?cn,
                      sn?sub?(objectclass=inetOrgPerson)".

      host           Host identifier of LDAP server, or null for
                      "localhost". See 2.6.8 for a discussion of valid
                      identifiers.

      port           Port number for LDAP server (use
                      LDAPConnection.DEFAULT_PORT for default port).

      dn             Distinguished name of the base object of the
                      search.

      attrNames      Names or OIDs of attributes to retrieve.  Passing
                      a null array signifies that all user attributes
                      are to be retrieved. Passing a value of "*"
                      allows you to specify that all user attributes as
                      well as any specified operational attributes are
                      to be retrieved.

      scope          Depth of search (in DN namespace). Use one of
                      SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from
                      LDAPConnection.

      filter         Search filter specifying the search criteria, as
                      defined in [FILTER].


2.41.2 decode

   public static String decode(String URLEncoded) throws
   MalformedURLException

   Decodes a URL-encoded string. Any occurrences of %HH are decoded to
   the hex value represented. However, this method does NOT decode "+"
   into " ". See [URL] for details on URL encoding/decoding.

   Parameters are:

      URLEncoded     String to decode.


2.41.3 encode


Expires December, 2001                                      [Page 106]


JAVA LDAP API                                                June 2001


   public static String encode(String toEncode)

   Encodes an arbitrary string. Any illegal characters are encoded as
   %HH.

   Parameters are:

      toEncode       String to encode.


2.41.4 getAttributeArray

   public String[] getAttributeArray()

   Returns an array of attribute names specified in the URL.


2.41.5 getAttributes

   public Enumeration getAttributes()

   Returns an Enumerator for the attribute names specified in the URL.


2.41.6 getDN

   public String getDN()

   Returns the distinguished name encapsulated in the URL, or null if
   none is specified.


2.41.7 getExtensions

   public String[] getExtensions ()

   Returns any LDAP URL extensions specified, or null if none are
   specified. Each extension is a type=value expression. The =value part
   MAY be omitted. The expression MAY be prefixed with '!' if it is
   mandatory for evaluation of the URL.


2.41.8 getFilter

   public String getFilter()

   Returns the search filter [LDAPURL], or null if none was specified.


2.41.9 getHost

   public String getHost()

Expires December, 2001                                      [Page 107]


JAVA LDAP API                                                June 2001



   Returns the host name of the LDAP server to connect to.


2.41.10 getPort

   public int getPort()

   Returns the port number of the LDAP server to connect to.


2.41.11 getScope

   public int getScope()

   Returns the depth of search (in DN namespace) - one of SCOPE_BASE,
   SCOPE_ONE, SCOPE_SUB from LDAPConnection.


2.41.12 getUrl

   public String getUrl()

   Returns a valid string representation of this LDAP URL.



3. Implementation Considerations

3.1 Client and Server Controls

   LDAPv3 operations can be extended through the use of controls.
   Controls MAY be sent to a server or returned to the client with any
   LDAP message. These controls are referred to as server controls. The
   LDAP API also supports a client-side extension mechanism through the
   use of client controls (these controls affect the behavior of the
   LDAP API only and are never sent to a server). A common class is used
   to represent both types of controls - LDAPControl.

   Controls are set and retrieved in LDAPConnection with the
   setConstraints and getConstraints methods. Either a single
   LDAPControl or an array may be specified, e.g.

      LDAPControl control = new LDAPControl( type, critical, vals );
      LDAPConstraints cons = ld.getConstraints();
      cons.setServerControls( control );
      ld.setConstraints( cons );
   or
      LDAPControl[] controls = new LDAPControl[2];
      controls[0] = new LDAPControl( type0, critical0, vals0 );
      controls[1] = new LDAPControl( type1, critical1, vals1 );
      LDAPConstraints cons = ld.getConstraints();

Expires December, 2001                                      [Page 108]


JAVA LDAP API                                                June 2001


      cons.setServerControls( controls );
      ld.setConstraints( cons );

   Server controls returned to a client as part of the response to a
   synchronous operation can be obtained with
   LDAPConnection.getResponseControls(). Controls returned on an
   asynchronous operation are available with LDAPMessage.getControls().

   Support for specific controls is defined in a package "controls"
   subordinate to the main LDAP package.


3.2 Referral handling and exceptions

   Asynchronous requests

   No automatic referral following is supported for asynchronous
   requests.

   No LDAPExceptions are thrown for asynchronous requests except in the
   case of local errors. The Throwable causing the local error can be
   retrieved with LDAPConnection.getCause().

   When a referral is received, the application receives an LDAPResponse
   object with a result code of REFERRAL. If a continuation reference is
   received the application receives an LDAPSearchResultReference
   object.


   Synchronous requests

   Referral-following behavior depends on two things: if automatic
   referral following is enabled, and when enabled if an
   LDAPReferralHandler is provided by the application.

   - Behavior if automatic referral following is "false" (not enabled):

       An LDAPException is thrown for any non-zero result code.

       An LDAPException is thrown for local failures.

       An LDAPReferralException is thrown if the result code is
       REFERRAL. It contains the referral URL strings. This ends the
       request, i.e., there are no more results to retrieve.

       An LDAPReferralException is thrown for each
       SearchResultReference received during a search request. It
       contains the referral URL strings. This is not an error, there
       may be more data to retrieve.




Expires December, 2001                                      [Page 109]


JAVA LDAP API                                                June 2001


   - Behavior if automatic referral following is "true" and either no
     LDAPReferralHandler is registered in LDAPConstraints, or an
     LDAPRebind LDAPReferralHandler is registered in LDAPConstraints:

       Exception handling is the same whether or not an LDAPRebind
       handler is registered, but authentication to the server is not
       the same. The registration of an LDAPRebind handler allows
       connections to be authenticated.  No handler registered results
       in an anonymous (unauthenticated) connection.

       LDAPExceptions are thrown if errors occur during the normal
       processing of the command, i.e. NO_SUCH_OBJECT,
       NO_SUCH_ATTRIBUTE, etc.

       An LDAPReferralException is thrown only if the API could not
       connect and bind to any referral URL in the list of URLs
       included in an individual REFERRAL result or
       LDAPSearchResultReference.

       When problems occur during the establishment of an authenticated
       connection by the API during automatic referral following, the
       LDAPReferralException will contain the last tried URL String of
       the server the API attempted to connect/bind to (the referral
       can be retrieved with getFailedReferral()), and the Throwable
       that caused the Exception (which can be retrieved with
       getCause()).Some possible failures are IOException on the
       connection, MalformedURLException on the referral string, or
       authentication failures on the bind.

       Upon receipt of an LDAPReferral exception, the application knows
       that the API was not able to connect to any of the servers in
       the referral list (which can be retrieved with getReferrals())
       and was not able to follow the referral. The error indicated by
       getCause() occurred on the referral indicated with
       getFailedReferral(). In the case of search, any results starting
       at the indicated base of the referred to server are missing from
       the search results.

   - behavior if automatic referral following is "true", and an LDAPBind
   LDAPReferralHandler is registered in LDAPConstraints:

       LDAPExceptions are thrown if errors occur during the normal
       processing of the command, i.e. NO_SUCH_OBJECT,
       NO_SUCH_ATTRIBUTE, etc.

       An LDAPReferralException is thrown only if the LDAPBind handler
       throws an exception.

       Upon receipt of an LDAPReferral exception, the application knows
       that the LDAPBind object was not able or not willing to connect
       to any of the servers in the referral list and so was not able
       to follow the referral. The list of referrals that failed is

Expires December, 2001                                      [Page 110]


JAVA LDAP API                                                June 2001


       available with getReferrals() and the last failed referral with
       getFailedReferral(). The exception thrown by LDAPBind is
       available with getCause().


3.3 Notice of disconnection

   If a notice of disconnection is received by a connection object, the
   object MUST close the connection without accepting or sending
   additional messages. Any clones of the object are disconnected as a
   consequence of closing the connection.


3.4 Level of compatibility

   Implementations of the API are to be binary compatible, and MUST be
   implemented with the package name org.ietf.ldap. Any implementation
   MUST behave as defined above with any application written to the API
   specification.


3.5 Invalid responses

   If a message is received by an API implementation from the server and
   the message cannot be interpreted as an LDAP PDU, an LDAPException
   MUST be thrown with a result code of INVALID_RESPONSE.


3.6 Array Return Values

   Methods that return arrays MUST return an empty array if no values
   are present to return, unless otherwise specified.


4. Security Considerations

   LDAP supports security through protocol-level authentication, using
   clear-text passwords or other more secure mechanisms.  It also
   supports running over TLS, which provides strong security at the
   transport layer.

   If a TLS session is terminated by the server but the client TLS
   provider and LDAP API implementation continue to use the socket
   rather than closing it, the application is notified through an
   LDAPException on the first operation request subsequent to
   termination of the TLS session.

   An interface to using SASL for configurable authentication and
   session protection is provided, but implementations are outside the
   scope of this document. Implementations of this API MUST ensure that
   a SASL provider is configured to comply with the minimal security
   guidelines of RFC 2829 [AUTH].

Expires December, 2001                                      [Page 111]


JAVA LDAP API                                                June 2001



   Implementations of this API SHOULD be cautious when handling
   authentication credentials. In particular, keeping long-lived copies
   of credentials without the application's knowledge is discouraged.

   Implementations of this API MUST discard information about the server
   obtained prior to negotiation of security protections provided by
   SASL and/or TLS [AUTH].


5. Acknowledgements

   The proposed API builds on earlier work done in collaboration with
   Thomas Kwan and Stephan Gudmundson, then of NCware Technologies Corp.
   It also includes suggestions by Steven Merrill of Novell and
   benefited from extensive review and comments by Kurt Zeilenga of
   OpenLDAP. Parts of the overview of the LDAP model are taken from
   draft-ietf-ldapext-ldap-c-api.


6. Bibliography

   [X500]  The Directory: Overview of Concepts, Models, and Services.
        CCITT, Recommendation X.500, 2nd edition, 1993

   [ATTR]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
        Directory Access Protocol: Attribute Syntax Definitions",
        RFC 2252, December 1997

   [FILTER]  T. Howes, "A String Representation of LDAP Search Filters,"
        RFC 2254, December 1997.

   [DN]  S. Kille, " UTF-8 String Representation of Distinguished
        Names," RFC 2253, December 1997.

   [LDAPv3]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
        Protocol (v3)", RFC 2251, December 1997.

   [LDAPURL]  T. Howes, M. Smith, "An LDAP URL Format", RFC 2255,
        December 1997.

   [URL] T. Berners-Lee, R. Fielding, L. Masinter, " Uniform Resource
        Identifiers (URI): Generic Syntax", RFC 2396, August 1998.

   [LANG] H. Alvestrans, "Tags for the Identification of Languages", RFC
        3066, January 2001.

   [LDAPLANG] M. Wahl, T. Howes, " Use of Language Codes in LDAP", RFC
        2596, May 1999

   [TLS] T. Dierks, C. Allen, "The TLS Protocol", RFC 2246, January
        1999.

Expires December, 2001                                      [Page 112]


JAVA LDAP API                                                June 2001



   [LDAPTLS] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory
        Access Protocol (v3): Extension for Transport Layer Security",
        RFC 2830, May 2000.

   [SASL] J. Myers, "Simple Authentication and Security Layer (SASL)",
        RFC 2222, October 1997.


   [AUTH] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
        Methods for LDAP", RFC 2829, May 2000

   [JAVA] B. Joy, G. Steele, J. Gosling, G. Bracha, "The Java Language
        Specification", Second Edition, Addison-Wesley, June 2000

   [IPv6] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6
        Addresses in URL's", RFC 2732, December 1999

   [JAVASASL] "Java SASL Specification", Java Community Process, JSR28

   [KEYWORDS] "Key words for use in RFCs to Indicate Requirement
        Levels", Bradner, S., RFC 2119, March 1997



7. Authors' Addresses

   Rob Weltman
   Coscend Corp.
   3290 W. Bayshore Road
   Palo Alto, CA  94303
   +1 650 461 1708
   robw@coscend.com

   Christine Tomlinson
   Sun Microsystems, Inc.
   8911 Capital of Texas Highway
   Suite 4140
   Austin, TX  US  78759
   +1 512 231 1600
   christine.tomlinson@sun.com

   Miodrag Kekic
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 650 937-5663
   miodrag@netscape.com

   Steven Sonntag
   Novell, Inc.

Expires December, 2001                                      [Page 113]


JAVA LDAP API                                                June 2001


   1800 South Novell Place
   Provo, UT 84606
   USA
   +1 801 861 7097
   vtag@novell.com

   Jim Sermersheim
   Novell, Inc.
   1800 South Novell Place
   Provo, UT 84606
   USA
   +1 801 861 3088
   jimse@novell.com

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 650 937-3477
   mcs@netscape.com

   Tim Howes
   Loudcloud, Inc.
   599 N. Mathilda Ave.
   Sunnyvale, CA 94086
   USA
   +1 650 321-4565 x111
   howes@loudcloud.com
























Expires December, 2001                                      [Page 114]


JAVA LDAP API                                                June 2001


8. Appendix A - Sample java LDAP programs

8.1 Java LDAP programs using synchronous methods

   import org.ietf.ldap.*;
   import java.util.*;

   public class SearchJensen {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );
               /* Authentication not required for an anonymous
                  connection */

               /* search for all entries with surname of Jensen */
               String MY_FILTER = "(sn=Jensen)";
               String MY_SEARCHBASE = "dc=example,dc=com";

               LDAPSearchConstraints cons = ld.getSearchConstraints();
               /* Setting the batchSize to one will cause the result
                  enumeration below to block on one result at a time,
                  allowing us to update a list or do other things as
                  results come in. */
               /* We could set it to 0 if we just wanted to get all
                  results and were willing to block until then */
               cons.setBatchSize( 1 );
               LDAPSearchResults res = ld.search( MY_SEARCHBASE,
                                                  ld.SCOPE_ONE,
                                                  MY_FILTER,
                                                  null,
                                                  false,
                                                  cons );

               /* Loop on results until finished */
               while ( res.hasMoreElements() ) {

                   /* Next directory entry */
                   LDAPEntry findEntry = (LDAPEntry)res.nextElement();
                   System.out.println( findEntry.getDN() );

                   /* Get the attributes of the entry */
                   LDAPAttributeSet findAttrs =
                                        findEntry.getAttributeSet();
                   Enumeration enumAttrs = findAttrs.getAttributes();
                   System.out.println( "Attributes: " );
                   /* Loop on attributes */
                   while ( enumAttrs.hasMoreElements() ) {

Expires December, 2001                                      [Page 115]


JAVA LDAP API                                                June 2001


                       LDAPAttribute anAttr =
                           (LDAPAttribute)enumAttrs.nextElement();
                       String attrName = anAttr.getName();
                       System.out.println( "  " + attrName );
                       /* Loop on values for this attribute.
                          Note: we are assuming all values are UTF-8
                          strings
                       */
                       Enumeration enumVals = anAttr.getStringValues();
                       while ( enumVals.hasMoreElements() ) {
                           String aVal = (String)enumVals.nextElement();
                           System.out.println( "  " + aVal );
                       }
                   }
               }
           }
           catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() ) {
               ld.disconnect();
           }
       }
   }




























Expires December, 2001                                      [Page 116]


JAVA LDAP API                                                June 2001


   import org.ietf.ldap.*;
   import java.io.*;
   import java.util.*;
   import javax.security.sasl.*;
   import javax.security.auth.callback.*;

   public class ModifyEmail {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

                /* Callback handler to supply credentials for SASL */
                CallbackHandler cbh = new CallbackHandler() {
                    public void handle( Callback[] callbacks )
                      throws IOException, UnsupportedCallbackException {
                        for ( int i = 0; i < callbacks.length; i++ ) {
                            if ( callbacks[i] instanceof NameCallback ){
                                ((NameCallback)callbacks[i]).setName(
                                        "bjensen" );
                            } else if ( callbacks[i] instanceof
                                        PasswordCallback ) {
                           ((PasswordCallback)callbacks[i]).setPassword(
                                        "MysteryLady" );

                            } else {
                                throw new UnsupportedCallbackException (
                                        callbacks[i],
                                        "Unrecognized Callback" );
                            }
                        }
                    }
                };
                /* SASL bind */
                ld.bind( "cn=Barbara Jensen,dc=example,dc=com",
                         "bjensen", null, cbh );

               /* Prepare to change my email address */
               LDAPAttribute attrEmail =
                       new LDAPAttribute( "mail", "babs@example.com" );
               LDAPModification mod =
                       new LDAPModification( LDAPModification.REPLACE,
                                             attrEmail );

               /* Now modify the entry in the directory */
               ld.modify( MY_NAME, mod );
               System.out.println( "Entry modified"  );


Expires December, 2001                                      [Page 117]


JAVA LDAP API                                                June 2001


           }
           catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() ) {
               ld.disconnect();
           }
       }
   }











































Expires December, 2001                                      [Page 118]


JAVA LDAP API                                                June 2001


   import org.ietf.ldap.*;
   import java.util.*;

   public class ShowSchema {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

               /* Fetch the schema (anonymous is okay for reading) */
               LDAPSchema schema = new LDAPSchema();
               schema.fetchSchema( ld );

               /* What is the definition of "userPassword"? */
               LDAPAttributeSchema a =
                                 schema.getAttribute( "userpassword" );
               if ( a != null ) {
                  String syntax = a.getSyntaxString();
                  String syntaxString = "string";
                  if ( syntax.equals(BINARY_SYNTAX) )
                      syntaxString = "binary";
                  else if (syntax.equals(INTEGER_SYNTAX) )
                      syntaxString = "integer";
                  String single = "multi-valued";
                  if ( a.isSingleValued() )
                      single = "single-valued";
                  System.out.println( "userPassword. " +
                                      "OID = " + a.getID() +
                                      ", type = " + syntaxString +
                                      ", " + single );
               );

               /* What are the possible attributes for "person"? */
               LDAPObjectClassSchema o =
                                 schema.getObjectClass( "person" );
               if ( o != null ) {
                  Enumeration required = o.getRequiredAttributes();
                  Enumeration optional = o.getOptionalAttributes();
                  System.out.println(
                              "Required attributes for person:" );
                  while( required.hasMoreElements() )
                      System.out.println( "  " +
                              (String)required.nextElement() );
                  System.out.println(
                              "Optional attributes for person:" );
                  while( optional.hasMoreElements() )
                      System.out.println( "  " +
                              (String) optional.nextElement() );

Expires December, 2001                                      [Page 119]


JAVA LDAP API                                                June 2001


               );

           } catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() ) {
               ld.disconnect();
           }
       }
       protected static final String BINARY_SYNTAX =
                                     "1.3.6.1.4.1.1466.115.121.1.5";
       protected static final String INTEGER_SYNTAX =
                                     "1.3.6.1.4.1.1466.115.121.1.27";
   }






































Expires December, 2001                                      [Page 120]


JAVA LDAP API                                                June 2001


8.2 Java LDAP programs using asynchronous methods

   import org.ietf.ldap.*;
   import java.util.*;

   public class SearchJensen {
       public static void main( String[] args ) {
           try {
               LDAPConnection ld = new LDAPConnection();
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

               /* Asynchronous authentication */
               LDAPResponseListener r =
                   ld.bind( "uid=admin, o=Airius.com",
                            "password", null );

               /* Do something else, just to show that we're not
                  blocked yet */
               System.out.println( "Started authenticating" );

               /* Wait until it completes */
               LDAPResponse response = (LDAPResponse)r.getResponse();
               int resultCode = response.getResultCode();
               if (resultCode != LDAPException.SUCCESS) {
                   throw new LDAPException ( "error result",
                                             resultCode,
                                             response.getMatchedDN() );
               }

               /* search for all entries with surname of Jensen */
               String MY_FILTER = "(sn=Jensen)";
               String MY_SEARCHBASE = "dc=example,dc=com";

               LDAPSearchListener l =
                   ld.search( MY_SEARCHBASE,
                              ld.SCOPE_ONE,
                              MY_FILTER,
                              null,
                              false,
                              null,
                             (LDAPSearchListener)null );

               /* Loop on results until finished */
               LDAPMessage msg;
               while( (msg = l.getResponse()) != null ) {
                   if ( msg instanceof LDAPSearchResultReference ) {
                       String[] urls =
                         (LDAPSearchResultReference)msg).getReferrals();
                       // Do something with the referrals...

Expires December, 2001                                      [Page 121]


JAVA LDAP API                                                June 2001


                   } else if ( msg instanceof LDAPSearchResult ) {
                       LDAPEntry entry =
                           ((LDAPSearchResult)msg).getEntry();
                       // The rest of the processing is the same as for
                       // a synchronous search
                       System.out.println( entry.getDN() );
                   } else {
                       // A search response
                       LDAPResponse res = (LDAPResponse)msg;
                       int status = res.getResultCode();
                       if ( status == LDAPException.SUCCESS ) {
                           // Nothing to do
                       } else {
                           String err =
                               LDAPException.errorCodeToString(status);
                           throw new LDAPException(err,
                                                   status,
                                                   res.getMatchedDN());
                       }
                   }
               }
           } catch ( LDAPException e ) {
               System.err.println( e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() ) {
               ld.disconnect();
           }
       }
   }























Expires December, 2001                                      [Page 122]


JAVA LDAP API                                                June 2001


   import org.ietf.ldap.*;
   import java.util.*;

   /* This example multiplexes the input from three different servers */

   public class MultiplexServers {
       public static void main( String[] args )
       {
           try {
               LDAPConnection [] ld = new LDAPConnection [FILTER];
               String[] hosts = { "foo1", "foo2", "foo3" };
               int[] ports = { 389, 389, 2018 }
               String[] bases = { "dc=example,dc=com",
                                  "o=example.com",
                                  "dc=example2,dc=com" };
               /* search for all entries with surname of Jensen */
               String MY_FILTER = "(sn=Jensen)";

               for( int i = 0; i < ld.length; i++ ) {
                   ld[i] = new LDAPConnection ();
                   /* Connect to server */
                   ld[i].connect( hosts[i], ports[i] );
               }

               /* Get a response listener for one search */
               LDAPSearchListener l =
                   ld[0].search( bases[0],
                                 ld.SCOPE_SUB,
                                 MY_FILTER,
                                 null,
                                 false,
                                (LDAPSearchListener)null );
               /* Share the listener */
               for( i = 1; i < ld.length; i++ ) {
                   ld[i].search( bases[i],
                              ld[i].SCOPE_SUB,
                              MY_FILTER,
                              null,
                              false,
                              l );
               }

               /* Loop on results until finished */
               LDAPMessage msg;
               while( (msg = l.getResponse()) != null ) {
                   /* The rest is the same as in the previous example */
                   /* ... */






Expires December, 2001                                      [Page 123]


JAVA LDAP API                                                June 2001


   import org.ietf.ldap.*;
   import java.util.*;

   /* This example multiplexes the input from three searches in
      different subtrees of the same server */

   public class MultiplexTrees {
       public static void main( String[] args )
       {
           try {
               LDAPConnection ld = new LDAPConnection ();
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );
               String MY_FILTER = "(sn=Jensen)";
               String[] bases = { "dc=example,dc=com",
                                  "o=example.com",
                                  "dc=example2,dc=com" };

               /* Get a response listener for one search */
               LDAPSearchListener l =
                   ld.search( bases[0],
                              ld.SCOPE_SUB,
                              MY_FILTER,
                              null,
                              false,
                              (LDAPSearchListener)null );
               /* Share the listener */
               for( i = 1; i < bases.length; i++ ) {
                   ld.search( bases[i],
                              ld.SCOPE_SUB,
                              MY_FILTER,
                              null,
                              false,
                              l );
               }

               /* The rest is the same as in the MultiplexServers
                  example */
               /* ... */












Expires December, 2001                                      [Page 124]


JAVA LDAP API                                                June 2001


   import org.ietf.ldap.*;
   import java.util.*;

   public class ModifyEmail {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

               /* Use TLS to authenticate and secure the connection */
               ld.startTLS();
               /* Use SASL external on completed TLS client auth */
               ld.bind( null, null, new String[] { "external" },
                        null, null );

               /* Prepare to change my email address */
               LDAPAttribute attrEmail =
                       new LDAPAttribute( "mail", "babs@example.com" );
               LDAPModification mod =
                       new LDAPModification( LDAPModification.REPLACE,
                                             attrEmail );

               /* Now modify the entry in the directory */
               ld.modify( MY_NAME, mod );
               System.out.println( "Entry modified"  );

           }
           catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() ) {
               ld.disconnect();
           }
       }
   }













Expires December, 2001                                      [Page 125]


JAVA LDAP API                                                June 2001



9. Appendix B - Revision history


9.1 Changes from ldap-java-api-14.txt


   LDAPAttributeSchema

        Changed isModifiable() to isUserModifiable()


   LDAPConnection

        Added bind() signatures that take byte[] as password parameter,
        removed bind() signatures which do not take a version parameter

        Use Hashtable, not Properties, in all SASL bind signatures

        Removed setSearchConstraints()

        rename() takes newParentdn before deleteOldRdn (one of the
        eight signatures had the order reversed)


   LDAPException

        Defined how the toString method overrides the default toString
        behavior


   LDAPMatchingRuleSchema

        Changed return of getSyntaxString from String[] to String


   LDAPUrl

        Removed constructor signature which takes "secure" as a
        parameter

        Removed isSecure()

        getFilter() returns null instead of "(objectclass=*)" if no
        filter was specified


   Examples

        Use SASL to bind in synchronous ModifyEmail example and TLS in
        asynchronous ModifyEmail example (instead of simple bind)


Expires December, 2001                                      [Page 126]


JAVA LDAP API                                                June 2001



   General

        Put methods of LDAPAttributeSchema in alphabetical order

        Clarifications and editorial changes




9.2 Changes from ldap-java-api-13.txt


   Notice of disconnection, Invalid responses, Level of compatibility

        New section


   Result codes

        Added INVALID_RESPONSE, AMBIGUOUS_RESPONSE
        Removed PARAM_ERROR


   LDAPConnection

        Removed getAuthenticationPassword()
        Added bind() signatures that take a byte array for password
        bind() signatures for SASL take an authzId parameter
        disconnect() may take an LDAPConstraints parameter
        read() throws LDAPException with AMBIGUOUS_RESPONSE if there is
        more than one result


   LDAPConstraints

        Removed getReferralHandler


   LDAPRebindAuth

        Added a signature of the constructor which takes byte[] as
        parameter
        getPassword() returns byte[] instead of String


   LDAPReferralException

        Clarified that getReferrals() must return LDAP URL strings with
        the scope rewritten if necessary (for SearchResultReferences on
        search continuation).


Expires December, 2001                                      [Page 127]


JAVA LDAP API                                                June 2001



   LDAPDN

        Added normalize() and isValid().


   LDAPUnsolicitedNotificationListener

        The argument to messageReceived() is LDAPExtendedResponse and
        not LDAPMessage.


   Security Considerations

        Added implementation guidelines


   General

        All classes and methods in alphabetical order
        Many clarifications and editorial changes


9.3 Changes from ldap-java-api-12.txt


   Abstract

        Removed references to RFC 1823 and to an earlier draft on an
        asynchronous interface.


   LDAPConnection

        Under clone(), added a listing of which methods affect an
        individual clone and which ones affect all related clones.


   LDAPException

        Can take Throwable as root exception argument in an additional
        constructor signature. Added getCause() to return the root
        exception. Removed reference to LDAP_PARTIAL_RESULTS among
        result codes.


   LDAPBind

        bind() throws LDAPReferralException instead of LDAPException.


   LDAPReferralException

Expires December, 2001                                      [Page 128]


JAVA LDAP API                                                June 2001



        Can take Throwable as root exception argument instead of
        LDAPException. getFailureException() was removed and replaced
        by getCause() in LDAPException. Added getFailedReferral() and
        setFailedReferral().


   LDAPControl

        Removed newInstance(). An implementation of the API can
        instantiate a control using the LDAPControl constructor.
        Removed a sentence saying that LDAPv2 doesn't support controls.


   Referral handling

        Added section outlining the handling of exceptions on
        referrals.


   References

        Added references to RFCs 2222 and 2830.


   Host names

        May be IPv6 references as well as hostnames or IPv4 addresses.


   LDAPMessage

        Restored the values of the message types to correspond to the
        message type values in ldap-java-api-11.txt.


   LDAPEntry

        getAttribute returns a single attribute.


   Unsolicited notifications in LDAPConnection

        Removed getUnsolicitedNotifications and
        setUnsolicitedNotifications. Added
        addUnsolicitedNotificationListener and
        removeUnsolicitedNotificationListener. Added interface
        LDAPUnsolicitedNotificationListener.


9.4 Changes from ldap-java-api-11.txt


Expires December, 2001                                      [Page 129]


JAVA LDAP API                                                June 2001



   LDAPConnection

        Eliminated the interfaces (LDAPv2 and LDAPv3) that
        LDAPConnection implemented.

        Eliminated setOption and getOption (there are corresponding
        properties in LDAPConstraints and LDAPSearchConstraints).

        Removed the signatures of connect which took DN, password, and
        protocol version as arguments. The previous signatures were
        utility methods that combined connect and bind.

        Added a signature of extendedOperation which takes
        LDAPConstraints as argument.

        Added isTLS.

        Added getProtocolVersion.

        Added signatures of abandon which take LDAPConstraints as
        argument.

        extendedOperation returns LDAPExtendedResponse, not
        LDAPExtendedOperation.

        Added signatures of SASL bind that take LDAPConstraints as
        argument.

        Added getSaslBindProperties.

        Added getSaslBindCallbackHandler.

        Added getUnsolicitedNotifications and
        setUnsolicitedNotifications.

        The default protocol version to bind with is LDAPv3, not
        LDAPv2.

        Constants: LDAP_DEREF_NEVER, etc changed to DEREF_NEVER, etc.
        Values of DEREF_SEARCHING and DEREF_FINDING corrected to those
        of RFC 2251. The values are now defined in
        LDAPSearchConstraints instead of in LDAPConnection.


   LDAPControl

        Added setValue.


   LDAPExtendedOperation


Expires December, 2001                                      [Page 130]


JAVA LDAP API                                                June 2001


        Added setValue.


   LDAPSearchResultReference

        Changed getURLs to getReferrals, which returns String[].


   LDAPUrl

        Added method isSecure.

        Added constructors that take a boolean for isSecure.


   LDAPReferralException

        Added getReferralFailureException.
        Changed getURLs to getReferrals, which returns String[].


   LDAPConstraints

        Takes a new interface LDAPReferralHandler as parameter, instead
        of LDAPBind and LDAPRebind.
        Changed getReferrals to getReferralFollowing.
        Changed setReferrals to setReferralFollowing.


   LDAPReferralHandler

        New common ancestor to LDAPBind and LDAPRebind.


   LDAPListener

        New common ancestor to LDAPSearchListener and
        LDAPResponseListener.


   LDAPSearchListener

        Implements LDAPListener.

        Added signature of isResponseReceived and of getResponse that
        takes a message ID as parameter.

        Added isComplete.


   LDAPResponseListener


Expires December, 2001                                      [Page 131]


JAVA LDAP API                                                June 2001


        Implements LDAPListener.

        Added signatures isResponseReceived and getResponse that take a
        message ID as parameter.


   LDAPBind

        Changed the signature of bind to return LDAPConnection instead
        of void, and take an LDAP URL string list as argument.


   LDAPException

        Defined the values of symbolic result codes generated by the
        interface. Added a constructor that takes matchedDN as
        parameter.


   LDAPMessage

        Redefined the values of the message types to correspond to the
        message type values in [LDAPv3].


9.5 Changes from ldap-java-api-10.txt

   Overview of the LDAP model

        Allowed for character set conversion from/to T.61 (in addition
        to UTF-8).

   LDAPConnection

        Added startTLS. Added STRING_FORMAT option to setOption. Added
        numerical values to options in setOption and search. Changed
        REFERRALS_AUTHENTICATION to REFERRALS_REBIND_PROC. Clarified
        that getAuthenticationPassword returns null if no simple bind
        has been performed. Added asynchronous methods (from [TLS]).

   LDAPConstraints

        Default for setHopLimit is 10, not 5.


   LDAPUrl

        Added getScope and getExtensions.


   Schema classes


Expires December, 2001                                      [Page 132]


JAVA LDAP API                                                June 2001


        Added parameters to constructors (aliases, obsolete,
        collective).


   Various classes

        Removed all "synchronized" qualifier on methods. Added a
        statement that implementations should ensure thread-safety.


9.6 Changes from ldap-java-api-09.txt


   Overview of LDAP API use

        Clarifications were added on the behavior of the SDK for null
        values of LDAPConstraints and for a DN.


   LDAPAttributeSet

        Return type of getAttribute is LDAPAttribute, not
        LDAPAttribute[].


   LDAPV2

        Added convenience method of add that does not take
        LDAPConstraints, added read method that does take
        LDAPSearchConstraints.


   Error Codes

        Changed to Result Codes. Added TLS_NOT_SUPPORTED.


   LDAPSearchResults

        Clarified in declaration that it implements Enumeration.


   LDAPV3

        Added constants NO_ATTRS and ALL_USER_ATTRS.


   Schema classes

        Added LDAPDITContentRuleSchema, LDAPDITStructureRuleSchema,
        LDAPMatchingRuleUseSchema, LDAPNameFormSchema, LDAPSyntaxSchema.


Expires December, 2001                                      [Page 133]


JAVA LDAP API                                                June 2001



9.7 Changes from ldap-java-api-08.txt


   Standards track

        Added intended category to first page header.

   SASL references

        Removed all references to a Java SASL internet draft.

   LDAPv2

        Removed static methods search(LDAPUrl url). The methods are
        still present in LDAPConnection.


9.8 Changes from ldap-java-api-07.txt


   LDAPAttributeSchema

        Removed getAliases() because it is already defined in the
        superior class LDAPSchemaElement. Removed getSyntax() which
        returned an integer.

   LDAPConnection

        Added getAuthenticationMethod().

   LDAPSchemaElement

        Changed getOID() to getID().


9.9 Changes from ldap-java-api-06.txt


   LDAPAttributeSchema

        Added a constructor that takes the attribute syntax as a String,
        an optional superior attribute type, and an optional list of
        aliases. Removed previous constructor.
        Added getSuperior()and getSyntaxString().


   LDAPConnection

        Added getInputStream()getOutputStream(), setInputStream()
        (2.6.36), and setOutputStream(). They are used when establishing


Expires December, 2001                                      [Page 134]


JAVA LDAP API                                                June 2001


        a security layer with SASL, and may also be used to interpose a
        proxy.


   LDAPDN

        Added equals().


   LDAPException

        Added additional error codes defined in [URL].


   LDAPMatchingRuleSchema

        Added a constructor that takes the attribute syntax as a String
        and an optional list of aliases. Removed previous constructor.


   LDAPObjectClassSchema

        Added a constructor that takes an array of superior object class
        names, a type (ABSTRACT, AUXILIARY, or STRUCTURAL), and an
        optional list of aliases. Removed previous constructor.
        Added getSuperiors()and getType(). Removed getSuperior().


   LDAPSchemaElement

        Added overloaded methods of add, remove, and modify which take a
        DN as parameter, for specifying where in the DIT to determine
        the subschemaSubentry for the modification.
        Added getAliases(), getQualifier(), getQualiferNames(),
        isObsolete(), and setQualifier().


9.10 Changes from ldap-java-api-05.txt


   LDAPConnection

        Distinguished between getConstraints() and
        getSearchConstraints(), and between setConstraints() and
        setSearchConstraints().


   LDAPConstraints

        LDAPBind and LDAPRebind should not be specified in the same
        constructor. Added setClientControls().


Expires December, 2001                                      [Page 135]


JAVA LDAP API                                                June 2001



   LDAPSearchConstraints

        LDAPBind and LDAPRebind should not be specified in the same
        constructor.


   LDAPControl

        newInstance() is now static.


   LDAPv3

        Changed the signature of the bind() methods to match the Java
        SASL Internet Draft.


9.11 Changes from ldap-java-api-04.txt


   LDAPAttribute

        Added getByteValueArray() and getStringValueArray().


   LDAPCompareAttrNames

        Added getLocale() and setLocale().


   LDAPSchemaElement

        Added modify().


   LDAPSchemaElement

        Added fetchSchema(LDAPConnection, String).


9.12 Changes from ldap-java-api-03.txt


   LDAPBind

        New interface, to support sophisticated reauthentication
        mechanisms.


   LDAPControl


Expires December, 2001                                      [Page 136]


JAVA LDAP API                                                June 2001


        Added methods register() and newInstance(), to support dynamic
        registration and instantiation of server response controls.


   LDAPConstraints

        Separated interface time limit from server search time limit.
        Moved all search-only constraints to LDAPSearchConstraints.


   LDAPRebind

        Reverted back to original name, instead of LDAPReauthentication
        as it was in the previous draft.


   LDAPRebindProc

        Reverted back from LDAPCredentials.


   LDAPSearchConstraints

        Reinstated this class, to represent all constraints applicable
        to a search. LDAPConstraints (which it extends) only represents
        common constraints for all operations.

   LDAPSearchResults

        Added getResponseControls().


   LDAPv2

        Added abandon(). Separated interface time limit from server
        search time limit. Changed authenticate() to bind().


   LDAPv3

        Changed authenticate() to bind().


9.13 Changes from ldap-java-api-02.txt


   LDAPSearchConstraints

        Renamed to LDAPConstraints, since it can be applied to
        operations other than search.



Expires December, 2001                                      [Page 137]


JAVA LDAP API                                                June 2001


   LDAPRebind

        Renamed to LDAPReauthentication. Added a definition of its
        single method.

   LDAPRebindProc

        Renamed to LDAPCredentials.


9.14 Changes from ldap-java-api-01.txt


   LDAPAttribute

        Added a copy constructor.
        Added support for subtypes, and for language subtypes in
        particular.


   LDAPAttributeSet

        LDAPAttributeSet implements Cloneable.
        Added getSubset() for subtype support.


   LDAPDN

        Added support for escaping and unescaping an RDN.


   LDAPException

        Added the SASL_BIND_IN_PROGRESS error code.


   LDAPSearchResults

        Added getCount(), to report the number of results returned.


   LDAPConnection

        Added a signature that passes LDAPConstraints to read(LDAPURL).


   LDAPv2

        Added signatures that pass LDAPConstraints to the following
        methods:
                add()
                compare()

Expires December, 2001                                      [Page 138]


JAVA LDAP API                                                June 2001


                modify()
                read()
                rename()

   LDAPv3

        Removed "Preferred Language", because it has been dropped from
        the extension work.
        Added a signature that passes LDAPConstraints to rename().












































Expires December, 2001                                      [Page 139]