Subject: Submission: draft-ietf-ldapext-ldap-java-api-12.txt

From: Rob Weltman <[email-masked]>
Date: Mon, 06 Nov 2000 12:06:58 -0800

The attached update of the Java LDAP API draft was submitted for publication last night.

Rob

Network Working Group                                        Rob Weltman 
INTERNET-DRAFT                                       Christine Tomlinson 
Intended Category: Standards Track                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. 
                                                          November, 2000 

               The Java LDAP Application Program Interface 
                  draft-ietf-ldapext-ldap-java-api-12.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 language application program interface 
   to the lightweight directory access protocol (LDAP), in the form of a 
   class library. It complements but does not replace RFC 1823 [7], 
   which describes a C language application program interface. It 
   updates the previous draft in correcting a few minor errors which are 
   listed in appendix B. It also includes the asynchronous layer of the 
   API which was previously defined in draft-ietf-ldapext-ldap-java-api-
   asynch. 

Expires May, 2001                                             [Page 1] 

JAVA LDAP API                                            November 2000 

1. Overview of the LDAP model..........................................9 
2. Overview of the LDAP classes.......................................10 
2.1 The LDAP asynchronous methods.....................................10 
2.2 Interfaces........................................................11 
2.3 Classes...........................................................12 
2.4 Exceptions........................................................15 
3. Overview of LDAP API use...........................................15 
4. The Java LDAP classes..............................................16 
4.1 public class LDAPAttribute........................................16 
4.1.1 Constructors....................................................16 
4.1.2 addValue........................................................17 
4.1.3 getByteValues...................................................18 
4.1.4 getStringValues.................................................18 
4.1.5 getByteValueArray...............................................18 
4.1.6 getStringValueArray.............................................18 
4.1.7 getLangSubtype..................................................18 
4.1.8 getBaseName.....................................................18 
4.1.9 getName.........................................................19 
4.1.10 getSubtypes....................................................19 
4.1.11 hasSubtype.....................................................19 
4.1.12 hasSubtypes....................................................19 
4.1.13 removeValue....................................................20 
4.1.14 size...........................................................20 
4.2 public class LDAPAttributeSchema..................................20 
4.2.1 Constructors....................................................20 
4.2.2 getSyntaxString.................................................22 
4.2.3 isSingleValued..................................................22 
4.2.4 getSuperior.....................................................22 
4.2.5 getEqualityMatchingRule.........................................22 
4.2.6 getOrderingMatchingRule.........................................22 
4.2.7 getSubstringMatchingRule........................................22 
4.2.8 isCollective....................................................23 
4.2.9 isModifiable....................................................23 
4.2.10 getUsage.......................................................23 
4.2.11 Constants of LDAPAttributeSchema...............................23 
4.3 public class LDAPAttributeSet.....................................23 
4.3.1 Constructors....................................................24 
4.3.2 add.............................................................24 
4.3.3 clone...........................................................24 
4.3.4 elementAt.......................................................24 
4.3.5 getAttribute....................................................24 
4.3.6 getAttributes...................................................26 
4.3.7 getSubset.......................................................26 
4.3.8 remove..........................................................26 
4.3.9 removeElementAt.................................................27 
4.3.10 size...........................................................27 
4.4 public interface LDAPBind.........................................27 
4.4.1 bind............................................................27 
4.5 public class LDAPCompareAttrNames.................................28 
4.5.1 Constructors....................................................28 
4.5.2 getLocale.......................................................29 
4.5.3 setLocale.......................................................29 
  
Expires May, 2001                                             [Page 2] 

JAVA LDAP API                                            November 2000 

4.5.4 isGreater.......................................................29 
4.6 public class LDAPConnection.......................................30 
4.6.1 Constructors....................................................30 
4.6.2 abandon.........................................................30 
4.6.3 add.............................................................31 
4.6.4 bind............................................................32 
4.6.5 clone...........................................................35 
4.6.6 compare.........................................................35 
4.6.7 connect.........................................................36 
4.6.8 delete..........................................................37 
4.6.9 disconnect......................................................37 
4.6.10 extendedOperation..............................................37 
4.6.11 finalize.......................................................38 
4.6.12 getAuthenticationDN............................................38 
4.6.13 getAuthenticationMethod........................................39 
4.6.14 getAuthenticationPassword......................................39 
4.6.15 getConstraints.................................................39 
4.6.16 getHost........................................................39 
4.6.17 getInputStream.................................................39 
4.6.18 getOutputStream................................................39 
4.6.19 getPort........................................................40 
4.6.20 getProperty....................................................40 
4.6.21 getProtocolVersion.............................................41 
4.6.22 getResponseControls............................................41 
4.6.23 getSaslBindCallbackHandler.....................................41 
4.6.24 getSaslBindProperties..........................................41 
4.6.25 getSearchConstraints...........................................41 
4.6.26 getSocketFactory...............................................42 
4.6.27 getUnsolicitedNotifications....................................42 
4.6.28 isBound........................................................42 
4.6.29 isConnected....................................................42 
4.6.30 isTLS..........................................................42 
4.6.31 modify.........................................................42 
4.6.32 read...........................................................44 
4.6.33 rename.........................................................45 
4.6.34 search.........................................................47 
4.6.35 setConstraints.................................................49 
4.6.36 setInputStream.................................................49 
4.6.37 setOutputStream................................................49 
4.6.38 setProperty....................................................49 
4.6.39 setSearchConstraints...........................................50 
4.6.40 setSocketFactory...............................................50 
4.6.41 setUnsolicitedNotifications....................................50 
4.6.42 startTLS.......................................................51 
4.6.43 Constants of LDAPConnection....................................51 
4.7 public class public class LDAPConstraints.........................51 
4.7.1 Constructors....................................................52 
4.7.2 getHopLimit.....................................................52 
4.7.3 getReferralHandler..............................................53 
4.7.4 getReferralFollowing............................................53 
4.7.5 getTimeLimit....................................................53 
4.7.6 setHopLimit.....................................................53 
  
Expires May, 2001                                             [Page 3] 

JAVA LDAP API                                            November 2000 

4.7.7 setReferralHandler..............................................53 
4.7.8 setReferralFollowing............................................54 
4.7.9 setTimeLimit....................................................54 
4.7.10 getClientControls..............................................54 
4.7.11 getServerControls..............................................54 
4.7.12 setClientControls..............................................54 
4.7.13 setServerControls..............................................55 
4.8 public class LDAPControl..........................................55 
4.8.1 Constructors....................................................55 
4.8.2 clone...........................................................56 
4.8.3 getID...........................................................56 
4.8.4 getValue........................................................56 
4.8.5 isCritical......................................................56 
4.8.6 newInstance.....................................................56 
4.8.7 register........................................................56 
4.8.8 setValue........................................................57 
4.9 public class LDAPDITContentRuleSchema.............................57 
4.9.1 Constructors....................................................57 
4.9.2 getAuxiliaryClasses.............................................58 
4.9.3 getRequiredAttributes...........................................58 
4.9.4 getOptionalAttributes...........................................58 
4.9.5 getPrecludedAttributes..........................................59 
4.10 public class LDAPDITStructureRuleSchema..........................59 
4.10.1 Constructors...................................................59 
4.10.2 getRuleID......................................................60 
4.10.3 getNameForm....................................................60 
4.10.4 getSuperiors...................................................60 
4.11 public class LDAPDN..............................................60 
4.11.1 equals.........................................................60 
4.11.2 escapeRDN......................................................61 
4.11.3 unescapeRDN....................................................61 
4.11.4 explodeDN......................................................61 
4.11.5 explodeRDN.....................................................62 
4.12 public class LDAPEntry...........................................62 
4.12.1 Constructors...................................................62 
4.12.2 getAttribute...................................................63 
4.12.3 getAttributeSet................................................63 
4.12.4 getDN..........................................................63 
4.13 public interface LDAPEntryComparator.............................64 
4.13.1 isGreater......................................................64 
4.14 public class LDAPException.......................................64 
4.14.1 Constructors...................................................64 
4.14.2 errorCodeToString..............................................65 
4.14.3 getLDAPErrorMessage............................................66 
4.14.4 getLDAPResultCode..............................................66 
4.14.5 getMatchedDN...................................................66 
4.14.6 Result codes...................................................66 
4.15 public class LDAPExtendedOperation...............................68 
4.15.1 Constructors...................................................68 
4.15.2 getID..........................................................68 
4.15.3 getValue.......................................................68 
4.15.4 setValue.......................................................68 
  
Expires May, 2001                                             [Page 4] 

JAVA LDAP API                                            November 2000 

4.16 public class LDAPExtendedResponse................................69 
4.16.1 getID..........................................................69 
4.16.2 getValue.......................................................69 
4.17 public interface LDAPListener....................................69 
4.17.1 getMessageIDs..................................................69 
4.17.2 getResponse....................................................69 
4.17.3 isResponseReceived.............................................70 
4.17.4 merge..........................................................70 
4.18 public class LDAPMatchingRuleSchema..............................70 
4.18.1 Constructors...................................................70 
4.18.2 getAttributes..................................................71 
4.18.3 getSyntaxString................................................72 
4.19 public class LDAPMatchingRuleUseSchema...........................72 
4.19.1 Constructors...................................................72 
4.19.2 getAttributes..................................................73 
4.20 public class LDAPMessage.........................................73 
4.20.1 getControls....................................................73 
4.20.2 getMessageID...................................................73 
4.20.3 getType........................................................73 
4.21 public class LDAPModification....................................74 
4.21.1 Constructors...................................................74 
4.21.2 getAttribute...................................................74 
4.21.3 getOp..........................................................74 
4.21.4 Constants of LDAPModification..................................75 
4.22 public class LDAPModificationSet.................................75 
4.22.1 Constructors...................................................75 
4.22.2 add............................................................75 
4.22.3 elementAt......................................................75 
4.22.4 remove.........................................................76 
4.22.5 removeElementAt................................................76 
4.22.6 size...........................................................76 
4.23 public class LDAPNameFormSchema..................................76 
4.23.1 Constructors...................................................76 
4.23.2 getObjectClass.................................................77 
4.23.3 getRequiredNamingAttributes....................................78 
4.23.4 getOptionalNamingAttributes....................................78 
4.24 public class LDAPObjectClassSchema...............................78 
4.24.1 Constructors...................................................78 
4.24.2 getSuperiors...................................................79 
4.24.3 getRequiredAttributes..........................................79 
4.24.4 getOptionalAttributes..........................................79 
4.24.5 getType........................................................79 
4.25 public class LDAPRebindAuth......................................80 
4.25.1 Constructors...................................................80 
4.25.2 getDN..........................................................80 
4.25.3 getPassword....................................................80 
4.26 public interface LDAPRebind......................................80 
4.26.1 getRebindAuthentication........................................80 
4.27 public class LDAPReferralException...............................81 
4.27.1 Constructors...................................................81 
4.27.2 getReferralFailureException....................................82 
4.27.3 getReferrals...................................................82 
  
Expires May, 2001                                             [Page 5] 

JAVA LDAP API                                            November 2000 

4.28 public interface LDAPReferralHandler.............................82 
4.29 public class LDAPResponse........................................82 
4.29.1 getErrorMessage................................................82 
4.29.2 getMatchedDN...................................................82 
4.29.3 getReferrals...................................................83 
4.29.4 getResultCode..................................................83 
4.30 public class LDAPResponseListener................................83 
4.30.1 getMessageIDs..................................................83 
4.30.2 getResponse....................................................83 
4.30.3 isResponseReceived.............................................84 
4.30.4 merge..........................................................84 
4.31 public class LDAPSchema..........................................84 
4.31.1 Constructors...................................................84 
4.31.2 fetchSchema....................................................84 
4.31.3 getAttribute...................................................85 
4.31.4 getObjectClass.................................................85 
4.31.5 getMatchingRule................................................85 
4.31.6 getMatchingRuleUse.............................................86 
4.31.7 getDITStructureRule............................................86 
4.31.8 getDITContentRule..............................................86 
4.31.9 getNameForm....................................................86 
4.31.10 getSyntax.....................................................87 
4.31.11 getAttributes.................................................87 
4.31.12 getObjectClasses..............................................87 
4.31.13 getMatchingRules..............................................87 
4.31.14 getMatchingRuleUses...........................................87 
4.31.15 getDITStructureRules..........................................87 
4.31.16 getDITContentRules............................................88 
4.31.17 getNameForms..................................................88 
4.31.18 getSyntaxes...................................................88 
4.31.19 getAttributeNames.............................................88 
4.31.20 getObjectClassNames...........................................88 
4.31.21 getMatchingRuleNames..........................................88 
4.31.22 getMatchingRuleUseNames.......................................88 
4.31.23 getDITStructureRuleNames......................................88 
4.31.24 getDITContentRuleNames........................................89 
4.31.25 getNameFormNames..............................................89 
4.32 public abstract class LDAPSchemaElement..........................89 
4.32.1 getAliases.....................................................89 
4.32.2 getDescription.................................................89 
4.32.3 getName........................................................89 
4.32.4 getID..........................................................90 
4.32.5 getQualifier...................................................90 
4.32.6 getQualifierNames..............................................90 
4.32.7 isObsolete.....................................................90 
4.32.8 getValue.......................................................90 
4.32.9 setQualifier...................................................90 
4.32.10 add...........................................................91 
4.32.11 remove........................................................91 
4.32.12 modify........................................................91 
4.33 public class LDAPSearchConstraints...............................92 
4.33.1 Constructors...................................................92 
  
Expires May, 2001                                             [Page 6] 

JAVA LDAP API                                            November 2000 

4.33.2 getBatchSize...................................................93 
4.33.3 getDereference.................................................93 
4.33.4 getMaxResults..................................................94 
4.33.5 getServerTimeLimit.............................................94 
4.33.6 setBatchSize...................................................94 
4.33.7 setDereference.................................................94 
4.33.8 setMaxResults..................................................94 
4.33.9 setServerTimeLimit.............................................95 
4.33.10 Constants of LDAPSearchConstraints............................95 
4.34 public class LDAPSearchListener..................................95 
4.34.1 getMessageIDs..................................................95 
4.34.2 getResponse....................................................96 
4.34.3 isResponseReceived.............................................96 
4.34.4 isComplete.....................................................96 
4.34.5 merge..........................................................97 
4.35 public class LDAPSearchResult....................................97 
4.35.1 getEntry.......................................................97 
4.36 public class LDAPSearchResultReference...........................97 
4.36.1 getReferrals...................................................97 
4.37 public class LDAPSearchResults...................................97 
4.37.1 getCount.......................................................98 
4.37.2 getResponseControls............................................98 
4.37.3 hasMoreElements................................................98 
4.37.4 next...........................................................98 
4.37.5 nextElement....................................................98 
4.37.6 sort...........................................................98 
4.38 public interface LDAPSocketFactory...............................99 
4.38.1 makeSocket.....................................................99 
4.39 public class LDAPSyntaxSchema...................................100 
4.39.1 Constructors..................................................100 
4.40 public class LDAPUrl............................................100 
4.40.1 Constructors..................................................100 
4.40.2 decode........................................................102 
4.40.3 encode........................................................102 
4.40.4 getAttributeArray.............................................102 
4.40.5 getAttributes.................................................102 
4.40.6 getDN.........................................................102 
4.40.7 getExtensions.................................................102 
4.40.8 getFilter.....................................................103 
4.40.9 getHost.......................................................103 
4.40.10 getPort......................................................103 
4.40.11 getScope.....................................................103 
4.40.12 getUrl.......................................................103 
4.40.13 isSecure.....................................................103 
4.41 Client and Server Controls......................................104 
5. Security Considerations...........................................104 
6. Acknowledgements..................................................104 
7. Bibliography......................................................105 
8. Authors' Addresses................................................105 
9. Appendix A - Sample java LDAP programs............................107 
9.1 Java LDAP programs using synchronous methods.....................107 
9.2 Java LDAP programs using asynchronous methods....................112 
  
Expires May, 2001                                             [Page 7] 

JAVA LDAP API                                            November 2000 

10. Appendix B - Changes from ldap-java-api-11.txt...................117 
11. Appendix C - Changes from ldap-java-api-10.txt...................119 
12. Appendix D - Changes from ldap-java-api-09.txt...................120 
13. Appendix E - Changes from ldap-java-api-08.txt...................121 
14. Appendix F - Changes from ldap-java-api-07.txt...................121 
15. Appendix G - Changes from ldap-java-api-06.txt...................121 
16. Appendix H - Changes from ldap-java-api-05.txt...................122 
17. Appendix I - Changes from ldap-java-api-04.txt...................123 
18. Appendix J - Changes from ldap-java-api-03.txt...................123 
19. Appendix K - Changes from ldap-java-api-02.txt...................124 
20. Appendix L - Changes from ldap-java-api-01.txt...................125 

Expires May, 2001                                             [Page 8] 

JAVA LDAP API                                            November 2000 

   Introduction 
    
   The LDAP 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. Overview of the LDAP model 
 
   LDAP is the lightweight directory access protocol, described in [2] 
   and [5]. 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 [1] and is based on the 
   entry, which contains information about some object (e.g., a person). 
   Entries are composed of attributes, which have a type and one or more 
   values. Each attribute has a syntax that determines what kinds of 
   values are allowed in the attribute (e.g., ASCII characters, a jpeg 
   photograph, etc.) and how those values behave during directory 
   operations (e.g., is case significant during comparisons). 
    
   Entries may be organized in a tree structure, usually based on 
   political, geographical, and organizational boundaries. Other 
   structures are possible, including a flat namespace. Each entry is 
   uniquely named relative to its sibling entries by its relative 
   distinguished name (RDN) consisting of one or more distinguished 
   attribute values from the entry. At most one value from each 
   attribute may be used in the RDN. For example, the entry for the 
   person Babs Jensen might be named with the "Barbara Jensen" value 
   from the commonName attribute. 
    
   A globally unique name for an entry, called a distinguished name or 
   DN, is constructed by concatenating the sequence of RDNs from the 
   entry up to the root of the tree. For example, if Babs worked for the 
   University of Michigan, the DN of her U-M entry might be "cn=Barbara 
   Jensen, o=University of Michigan, c=US". The DN format used by LDAP 
   is defined in [4]. 
    
   Operations are provided to authenticate, search for and retrieve 
   information, modify information, and add and delete entries from the 
   tree. 
    
   An LDAP server may return referrals if it cannot completely service a 
   request (for example if the request specifies a directory base 
   outside of the tree managed by the server). The LDAP class library 
   offers the programmer three options: the programmer can catch these 
   referrals as exceptions and explicitly issue new requests to the 
  
Expires May, 2001                                             [Page 9] 

JAVA LDAP API                                            November 2000 

   referred-to servers, the programmer can provide an object to 
   establish a new connection to a referred-to server, or the programmer 
   can let the library automatically follow the referrals.  In the 
   latter case, the programmer may also provide a reauthentication 
   object, allowing automatic referrals to proceed with appropriate 
   credentials. If no such object is provided, referrals are followed 
   with anonymous credentials, and the protocol level of the original 
   connection is used. If the original connection used a socket factory 
   or TLS, the referral connection will use the same. 
    
   Before the client encodes and sends a string value to a server, the 
   string values are converted from the Java 16-bit Unicode format to 
   UTF-8 format, which is the standard string encoding for LDAPv3 
   servers. The integrity of double-byte and other non-ASCII character 
   sets is fully preserved. 
    
   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. 

2.  Overview of the LDAP classes 
    
   The central LDAP class is LDAPConnection. It provides methods to 
   establish an authenticated or anonymous connection to an LDAP server, 
   as well as methods to search for, modify, compare, and delete entries 
   in the directory. 
    
   The LDAPConnection class also provides fields for storing settings 
   that are specific to the LDAP session (such as limits on the number 
   of results returned or timeout limits). An LDAPConnection object can 
   be cloned, allowing objects to share a single network connection but 
   use different settings (using LDAPConstraints or 
   LDAPSearchConstraints). 
    
   A synchronous search conducted by an LDAPConnection object returns 
   results in an LDAPSearchResults object, which can be enumerated to 
   access the entries found. Each entry (represented by an LDAPEntry 
   object) provides access to the attributes (represented by 
   LDAPAttribute objects) returned for that entry. Each attribute can 
   produce the values found as byte arrays or as Strings. 

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

Expires May, 2001                                            [Page 10] 

JAVA LDAP API                                            November 2000 

   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. 

2.2 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 
                              implement this interface. If LDAPRebind 
                              or LDAPBind are not used, automatically 
                              followed referrals will use anonymous 
                              authentication. 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. 

   LDAPBind                   This interface allows a programmer to 
                              override the default authentication and 
                              reauthentication behavior when 
                              automatically following referrals. It is 
                              typically used to control the 
  
Expires May, 2001                                            [Page 11] 

JAVA LDAP API                                            November 2000 

                              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. 

2.3 Classes 

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

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

   LDAPAttributeSet           A collection of LDAPAttributes. 

   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. 

Expires May, 2001                                            [Page 12] 

JAVA LDAP API                                            November 2000 

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

   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 
  
Expires May, 2001                                            [Page 13] 

JAVA LDAP API                                            November 2000 

                              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 of a particular 
                              Directory Server. 

   LDAPSchemaElement          Base class for representing LDAP schema 
                              elements. 

   LDAPSyntaxSchema           Represents a specific syntax definition 
                              in the directory schema. 

   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. 

Expires May, 2001                                            [Page 14] 

JAVA LDAP API                                            November 2000 

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

2.4 Exceptions 

   LDAPException         General exception, which includes an error 
                         message and an LDAP error code. 

   LDAPReferralException Derived from LDAPException and contains a list 
                         of URLs corresponding to referrals received on 
                         an LDAP operation. 

3. Overview of LDAP API use 
    
   An application generally uses the LDAP API in four steps. 
    
   -    Construct an LDAPConnection.  Initialize an LDAP session with a 
        directory server. The LDAPConnection.connect() call establishes 
        a handle to the session, allowing multiple sessions to be open 
        at once, on different instances of LDAPConnection. 
    
   -    Authenticate to the LDAP server with LDAPConnection.bind(). 
    
   -    Perform some LDAP operations and obtain some results. 
        The synchronous version of LDAPConnection.search() returns an 
        LDAPSearchResults which can be enumerated to access all entries 
        found. The asynchronous version of LDAPConnection.search() 
        returns an LDAPSearchListener, which is used to read the 
        results of the search. LDAPConnection.read() returns a single 
        entry. 
    
   -    Close the connection. The LDAPConnection.disconnect() call 
        closes the connection. 
    
   There are both synchronous and asynchronous versions of the LDAP 
   protocol operations 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 

Expires May, 2001                                            [Page 15] 

JAVA LDAP API                                            November 2000 

   operation is passed in to one or more other operations, rather than 
   passing in null. 
 
   For the asynchronous methods, exceptions are raised only for 
   connection errors. LDAP result messages are converted into 
   LDAPResponse objects which are to be checked by the client for errors 
   and referrals, whereas the synchronous methods throw an LDAPException 
   on result codes other than 0. 
    
   To facilitate user feedback during synchronous searches, intermediate 
   search results can be obtained before the entire search operation is 
   completed by specifying the number of entries to return at a time.  
   Standard Java Enumerations are used to parse synchronous search 
   results.  
    
   Errors result in the throwing of an LDAPException, with a specific 
   error code and context-specific textual information available. 
    
   If null is passed as the value of an LDAPConstraints or 
   LDAPSearchConstraints parameter to an operation, the default 
   constraints are used for that operation. 
    
   If null is passed as the value of a DN to an operation it is treated 
   as if it was the empty string. 
    
   The API doesn't distinguish between LDAP search continuation 
   references and LDAP referrals, presenting a unified interface to the 
   client for handling the two. 
    
   Implementations of the API MUST ensure that the LDAPConnection class 
   is thread-safe. Other classes and methods MAY be thread-safe and the 
   implementor MUST indicate which classes and methods are thread-safe. 
    
   The following sections describe the LDAP classes in more detail. 

4. The Java LDAP classes 

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

4.1.1 Constructors 
    
   public LDAPAttribute(LDAPAttribute attr) 

Expires May, 2001                                            [Page 16] 

JAVA LDAP API                                            November 2000 

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

4.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: 
  
Expires May, 2001                                            [Page 17] 

JAVA LDAP API                                            November 2000 

      attrString     Value of the attribute as a String. 
       
      attrBytes      Value of the attribute as raw bytes. 

4.1.3 getByteValues 
    
   public Enumeration getByteValues() 
    
   Returns an enumerator for the values of the attribute in byte[] 
   format. 

4.1.4 getStringValues 
    
   public Enumeration getStringValues() 
    
   Returns an enumerator for the string values of an attribute. 

4.1.5 getByteValueArray 
    
   public byte[][] getByteValueArray() 
    
   Returns the values of the attribute as an array of byte[]. 

4.1.6 getStringValueArray 
    
   public String[] getStringValueArray() 
    
   Returns the values of the attribute as an array of Strings. 

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

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

Expires May, 2001                                            [Page 18] 

JAVA LDAP API                                            November 2000 

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

4.1.9 getName 
    
   public String getName() 
    
   Returns the name of the attribute. 

4.1.10 getSubtypes 
    
   public String[] getSubtypes() 
    
   public static String[] getSubtypes(String attrName) 
    
   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. 

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

4.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: 

Expires May, 2001                                            [Page 19] 

JAVA LDAP API                                            November 2000 

      subtypes       An array of subtypes to check for. 

4.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. 
       
      attrBytes      Value of the attribute as raw bytes. 

4.1.14 size 
    
   public int size() 
    
   Returns the number of values of the attribute. 

4.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 [2] for a description of 
   attribute representation in LDAP. 

4.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, 
  
Expires May, 2001                                            [Page 20] 

JAVA LDAP API                                            November 2000 

                              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. 
       
      oid            Unique Object Identifier of the attribute - in 
                      dotted numerical format. 
       
      description    Optional description of the attribute. 
       
      syntaxString   Unique Object Identifier of the syntax of the 
                      attribute - in dotted numerical 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       Unique Object Identifier of the equality matching 
                      rule for the attribute - in dotted numerical 
                      format; may be null. 
    
      ordering       Unique Object Identifier of the ordering matching 
                      rule for the attribute - in dotted numerical 
                      format; may be null. 
    
      substring      Unique Object Identifier of the substring 
                      matching rule for the attribute - in dotted 
                      numerical format; may be null. 
    
      collective     true if this is a collective attribute. 
    
      userMod        true if the attribute is modifiable by users. 

Expires May, 2001                                            [Page 21] 

JAVA LDAP API                                            November 2000 

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

4.2.2 getSyntaxString 
    
   public String getSyntaxString() 
    
   Returns the Unique Object Identifier of the syntax of the attribute 
   in dotted numerical format. 

4.2.3 isSingleValued 
    
   public boolean isSingleValued() 
    
   Returns true if the attribute is single-valued. 

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

4.2.5 getEqualityMatchingRule 
    
   public String getEqualityMatchingRule () 
    
   Returns the Unique Object Identifier of the equality matching rule in 
   effect for this attribute, or null if there is none. 

4.2.6 getOrderingMatchingRule 
    
   public String getOrderingMatchingRule () 
    
   Returns the Unique Object Identifier of the ordering matching rule in 
   effect for this attribute, or null if there is none. 

4.2.7 getSubstringMatchingRule 

Expires May, 2001                                            [Page 22] 

JAVA LDAP API                                            November 2000 

   public String getSubstringMatchingRule () 
    
   Returns the Unique Object Identifier of the substring matching rule 
   in effect for this attribute, or null if there is none. 

4.2.8 isCollective 
    
   public boolean isCollective () 
    
   Returns true if the attribute is collective. 
    
4.2.9 isModifiable 
    
   public boolean isModifiable () 
    
   Returns true if the attribute is modifiable. 

4.2.10 getUsage 
    
   public int getUsage () 
    
   Returns one of the following: 
    
        USER_APPLICATIONS 
        DIRECTORY_OPERATION 
        DISTRIBUTED_OPERATION 
        DSA_OPERATION 

4.2.11 Constants of LDAPAttributeSchema 
    
     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 

4.3 public class LDAPAttributeSet 
                 implements Cloneable 

Expires May, 2001                                            [Page 23] 

JAVA LDAP API                                            November 2000 

   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. 

4.3.1 Constructors 
    
   public LDAPAttributeSet() 
    
   Constructs a new set of attributes. This set is initially empty. 

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

4.3.3 clone 
    
   public Object clone() 
    
   Returns a deep copy of this attribute set. 

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

4.3.5 getAttribute 

   public LDAPAttribute getAttribute(String attrName) 
    
   Returns the attribute matching the specified attrName. For example, 
       
        getAttribute("cn")          returns only the "cn" attribute 

Expires May, 2001                                            [Page 24] 

JAVA LDAP API                                            November 2000 

        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. 
    
   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. 
    
   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 [9], with optional 
                      subtypes appended using "-" as separator. "lang-
  
Expires May, 2001                                            [Page 25] 

JAVA LDAP API                                            November 2000 

                      en", "lang-en-us", "lang-ja", and "lang-ja-JP-
                      kanji" are valid language specification. 

4.3.6 getAttributes 
    
   public Enumeration getAttributes() 
    
   Returns an enumeration of the attributes in this attribute set. 

4.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;phonetic;lang-ja 
         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;phonetic;lang-ja 

   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 

4.3.8 remove 
    
   public void remove(String name) 

Expires May, 2001                                            [Page 26] 

JAVA LDAP API                                            November 2000 

   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() ); 

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

4.3.10 size 
    
   public int size() 
    
   Returns the number of attributes in this set. 

4.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). 

4.4.1 bind 

   public LDAPConnection bind(String[] ldapurl, LDAPConnection conn) 
                    throws LDAPException 
    
   This method is called by LDAPConnection when a referral is received, 
   and is responsible to bind 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 response). An implementation may 
   access the host, port, credentials, and other information in the 
  
Expires May, 2001                                            [Page 27] 

JAVA LDAP API                                            November 2000 

   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 LDAPException is thrown on failure, as in LDAPConnection.bind(). 
    
   Parameters are: 
    
      ldapurl        List of LDAP server URLs.  There is no order 
                      implied by the list and all servers are equally 
                      capable of satisfying the request. 
       
      conn           An established connection to an LDAP server. 

4.5 public class LDAPCompareAttrNames 
                 implements LDAPEntryComparator 
    
   An object of this class supports sorting search results by attribute 
   name, in ascending or descending order. 

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

Expires May, 2001                                            [Page 28] 

JAVA LDAP API                                            November 2000 

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

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

4.5.3 setLocale 
    
   public void setLocale(Locale locale) 
       
   Sets the Locale to be used for sorting. 
       
   Parameters are: 
       
      locale         The Locale to be used for sorting. 

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

Expires May, 2001                                            [Page 29] 

JAVA LDAP API                                            November 2000 

      entry2         Entry to be compared to. 

4.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 
   connection, and an application may have more than one LDAPConnection 
   object, connected to the same or different Directory Servers. 

4.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. 
   To connect to the LDAP server, use the connect method. 

   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. 

4.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 
  
Expires May, 2001                                            [Page 30] 

JAVA LDAP API                                            November 2000 

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

4.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. 
    
   Parameters are: 
    
      entry          LDAPEntry object specifying the distinguished 
                      name and attributes of the new entry. 

Expires May, 2001                                            [Page 31] 

JAVA LDAP API                                            November 2000 

      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. 

4.6.4 bind 
    
   public void bind(String dn, 
                    String passwd) 
                    throws LDAPException 
    
   public void bind(String dn, 
                    String passwd, 
                    LDAPConstraints cons, 
                    throws LDAPException 
    
   public LDAPResponseListener bind(String dn, 
                                    String passwd, 
                                    LDAPResponseListener listener) 
                                    throws LDAPException 
    
   public LDAPResponseListener bind(String dn, 
                                    String passwd, 
                                    LDAPResponseListener listener, 
                                    LDAPConstraints cons) 
                                    throws LDAPException 
    
   Authenticates with LDAPv3 protocol to the LDAP server (that the 
   object is currently connected to) using the specified name and 
   password.  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: 
    
      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. It is 
                      recommended that either the synchronous version 

Expires May, 2001                                            [Page 32] 

JAVA LDAP API                                            November 2000 

                      of this method is used or that the client blocks 
                      until the listener returns a response. 
       
      cons           Constraints specific to the operation. 

   public void bind(int version, 
                    String dn, 
                    String passwd) 
                    throws LDAPException 
    
   public void bind(int version, 
                    String dn, 
                    String 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, 
                                    String 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. 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 
  
Expires May, 2001                                            [Page 33] 

JAVA LDAP API                                            November 2000 

                      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, 
                    Properties props, 
                    javax.security.auth.callback.CallbackHandler cbh) 
                    throws LDAPException 

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

   public void bind(String dn, 
                    String[] mechanisms, 
                    Hashtable props, 
                    javax.security.auth.callback.CallbackHandler cbh) 
                    throws LDAPException 
    
   public void bind(String dn, 
                    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 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. If mechanisms is null, or if the first version of the 
   method is called, the LDAP server will be interrogated for its 
   supportedSaslMechanisms attribute of its root DSE. 
    
   Parameters are: 
    
      dn              If non-null and non-empty, specifies that the 
                      connection and all operations through it should 

Expires May, 2001                                            [Page 34] 

JAVA LDAP API                                            November 2000 

                      be authenticated with dn as the distinguished 
                      name. 
       
      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. 

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

4.6.6 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 

Expires May, 2001                                            [Page 35] 

JAVA LDAP API                                            November 2000 

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

4.6.7 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 hostname or dotted string representing 
                      the IP address of a host running an LDAP server 
                      to connect to. Alternatively, it may contain a 
                      list of host names, space-delimited.  Each host 
                      name may include a trailing colon and port 
                      number.  In the case where more than one host 
                      name is specified, each host name in turn will be 
                      contacted until a connection can be established. 
                      Examples: 

Expires May, 2001                                            [Page 36] 

JAVA LDAP API                                            November 2000 

         "directory.knowledge.com" 
         "199.254.1.2" 
         "directory.knowledge.com:1050 people.catalog.com 199.254.1.2" 
    
      port           Contains the TCP or UDP port number to connect to 
                      or contact. The default LDAP port is 389. "port" 
                      is ignored for any host name which includes a 
                      colon and port number. 

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

4.6.9 disconnect 
    
   public void disconnect() throws LDAPException 
    
   Disconnects from the LDAP server. Before the object can perform LDAP 
   operations again, it must reconnect to the server by calling connect. 

4.6.10 extendedOperation 
    
   public LDAPExtendedResponse extendedOperation( 
  
Expires May, 2001                                            [Page 37] 

JAVA LDAP API                                            November 2000 

                                   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 ID and an Octet 
   String or BER-encoded value(s). 
    
   Parameters are: 
    
      op             Object which contains an 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. 

4.6.11 finalize 
    
   public void finalize() throws LDAPException 
    
   Closes the connection if open and releases any other resources held 
   by the object. 

4.6.12 getAuthenticationDN 
    
   public String getAuthenticationDN() 
    
   Returns the distinguished name (DN) used for authentication by this 
   object. null is returned if no authentication has been performed. 

Expires May, 2001                                            [Page 38] 

JAVA LDAP API                                            November 2000 

4.6.13 getAuthenticationMethod 
    
   public String getAuthenticationMethod() 
    
   Returns the method used to authenticate the connection. The return 
   value is one of the following: 
    
      "none"         If the connection is not authenticated 
       
      "simple"       If simple authentication was used, also if a null 
                      or empty authentication DN was specified 
       
      "sasl"         If a SASL mechanism was used to authenticate 

4.6.14 getAuthenticationPassword 
    
   public String getAuthenticationPassword() 
    
   Returns the password used for simple authentication by this object. 
   null is returned if no authentication has been performed. 

4.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). 

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

4.6.17 getInputStream 
    
   public InputStream getInputStream() 
    
   Returns the stream used by the connection object for receiving data 
   from the LDAP server. 

4.6.18 getOutputStream 
    
   public OutputStream getOutputStream() 
  
Expires May, 2001                                            [Page 39] 

JAVA LDAP API                                            November 2000 

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

4.6.19 getPort 
    
   public int getPort() 
    
   Returns the port number of the LDAP server to which the object is or 
   was last connected. 

4.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 May, 2001                                            [Page 40] 

JAVA LDAP API                                            November 2000 

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

4.6.21 getProtocolVersion 
    
   public int getProtocolVersion () 
    
   Returns the protocol level that the connection is bound to (2 or 3). 

4.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, or null 
   if the latest response contained no Server Controls. The method 
   always returns null for asynchronous requests. For asynchronous 
   requests, the response controls are available in LDAPMessage. 

4.6.23 getSaslBindCallbackHandler 
    
   public javax.security.auth.callback.CallbackHandler 
          getSaslBindCallbackHandler() 
    
   Returns the callback handler, if any, specified on binding with a 
   SASL mechanism. 

4.6.24 getSaslBindProperties 
    
   public Hashtable getSaslBindProperties() 
    
   Returns the properties, if any, specified on binding with a SASL 
   mechanism. 

4.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 May, 2001                                            [Page 41] 

JAVA LDAP API                                            November 2000 

4.6.26 getSocketFactory 
    
   public LDAPSocketFactory getSocketFactory() 
    
   Returns the LDAPSocketFactory used to establish a connection to a 
   server. 

4.6.27 getUnsolicitedNotifications 
    
   public boolean getUnsolicitedNotifications() 
    
   Indicates if unsolicited messages from the server are accepted or 
   not. An unsolicited message has the ID 0. If unsolicited 
   notifications are enabled, unsolicited messages can be queried and 
   retrieved from a response listener with isResponseReceived(0) and 
   getResponse(0). The default is for unsolicited messages to be 
   discarded. 

4.6.28 isBound 
    
   public boolean isBound() 
    
   Indicates whether the object has authenticated to the connected LDAP 
   server. 

4.6.29 isConnected 
    
   public boolean isConnected() 
    
   Indicates if the connection represented by this object is open at 
   this time. 

4.6.30 isTLS 
    
   public boolean isTLS () 
    
   Indicates if the connection uses TLS, i.e. startTLS has completed. 

4.6.31 modify 
    
   public void modify(String dn, 
                      LDAPModification mod) 
                      throws LDAPException 
    
   public void modify(String dn, 
                      LDAPModification mod, 
                      LDAPConstraints cons) 
  
Expires May, 2001                                            [Page 42] 

JAVA LDAP API                                            November 2000 

                      throws LDAPException 
    
   public LDAPResponseListener modify(String dn, 
                                      LDAPModification mod, 
                                      LDAPResponseListener listener) 
                                      throws LDAPException 
    
   public LDAPResponseListener modify(String dn, 
                                      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. 

   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). 
    
   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 May, 2001                                            [Page 43] 

JAVA LDAP API                                            November 2000 

      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. 

4.6.32 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). 

Expires May, 2001                                            [Page 44] 

JAVA LDAP API                                            November 2000 

   If the URL specifies a filter and scope, these are not used. Of the 
   information specified in the URL, this method only uses the LDAP host 
   name and port number, the base distinguished name (DN), and the list 
   of attributes to return. 
    
   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. 
       
   Note: read is simply a helper method and uses the ldap search 
   operation to achieve the results. As such, there is no asynchronous 
   interface. 

4.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) 
                      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. 

Expires May, 2001                                            [Page 45] 

JAVA LDAP API                                            November 2000 

   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, 
                      boolean deleteOldRdn) 
                      String newParentdn, 
                      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 in the directory, possibly repositioning it 
   in the directory tree. 
    
   Parameters are: 
    
      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. 

Expires May, 2001                                            [Page 46] 

JAVA LDAP API                                            November 2000 

4.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) 
                                    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 

Expires May, 2001                                            [Page 47] 

JAVA LDAP API                                            November 2000 

   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 under the base DN 
              
             SCOPE_SUB    Search the base DN and all entries within 
                           its subtree 
    
      filter         Search filter specifying the search criteria, as 
                      defined in [3]. 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. 

Expires May, 2001                                            [Page 48] 

JAVA LDAP API                                            November 2000 

      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. 

4.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). 

4.6.36 setInputStream 
    
   public void setInputStream(InputStream stream) 
    
   Sets the stream used by the connection object for receiving data from 
   the LDAP server. 

4.6.37 setOutputStream 
    
   public void setOutputStream(OutputStream stream) 
    
   Sets the stream used by the connection object to send data to the 
   LDAP server. 

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

Expires May, 2001                                            [Page 49] 

JAVA LDAP API                                            November 2000 

4.6.39 setSearchConstraints 
    
   public void setSearchConstraints(LDAPSearchConstraints cons) 
    
   Sets the constraints that apply to all search operations performed 
   through this connection (unless a different set of constraints is 
   specified when calling a search operation method). 
    
   Typically, the setSearchConstraints method is used to create a 
   slightly different set of search constraints to apply to a particular 
   search. 

4.6.40 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. 
    
   A typical usage would be: 
    
       if (usingTLS) { 
           LDAPConnection.setSocketFactory(myTLSFactory); 
       } 
       ... 
       LDAPConnection conn = new LDAPConnection(); 
       conn.connect(myHost, myPort); 
    
   In this example, connections are constructed with the default 
   LDAPSocketFactory.  At application start-up time, the default may be 
   set to use a particular provided TLS socket factory. 
    
   Parameters are: 
    
      factory        A factory object which can construct socket 
                      connections for an LDAPConnection. 

4.6.41 setUnsolicitedNotifications 
    
   public void setUnsolicitedNotifications (boolean allow) 
    
   Enables or disables the processing of unsolicited messages from the 
   server. An unsolicited message has the ID 0. If unsolicited 
  
Expires May, 2001                                            [Page 50] 

JAVA LDAP API                                            November 2000 

   notifications are enabled, unsolicited messages can be queried and 
   retrieved from a response listener with isResponseReceived(0) and 
   getResponse(0). The default is for unsolicited messages to be 
   discarded. 
    
   Parameters are: 
    
      allow          If true, keep unsolicited notifications and make 
                      them available as message ID 0. 

4.6.42 startTLS 
    
   public void startTLS() 
    
   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 
   transition to a TLS session, an LDAPException is thrown with the 
   error code UNWILLING_TO_PERFORM. 

4.6.43 Constants of LDAPConnection 
    
      ALL_USER_ATTRS ("*")     Used with search instead of an attribute 
                      list to indicate that all 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. 

4.7 public class public class LDAPConstraints 

Expires May, 2001                                            [Page 51] 

JAVA LDAP API                                            November 2000 

   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. 

4.7.1 Constructors 
    
   public LDAPConstraints() 
    
   Constructs an LDAPConstraints object that specifies the default 
   set of constraints. 

   public LDAPConstraints(int msLimit, 
                          boolean doReferrals, 
                          LDAPReferralHandler binder, 
                          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. 

4.7.2 getHopLimit 
    
   public int getHopLimit() 
  
Expires May, 2001                                            [Page 52] 

JAVA LDAP API                                            November 2000 

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

4.7.3 getReferralHandler 
    
   public LDAPReferralHandler getReferralHandler() 
    
   Returns an object that can process authentication. It may be null. 

4.7.4 getReferralFollowing 
    
   public boolean getReferralFollowing() 
    
   Specifies whether or not referrals are followed automatically. 
   Returns true if referrals are to be followed automatically, or false 
   if referrals throw an LDAPReferralException. 

4.7.5 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. 
    
4.7.6 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. 

4.7.7 setReferralHandler 
    
   public void setReferralHandler (LDAPReferralHandler binder) 
    
   Specifies the object that will process authentication requests. The 
   default is null. 
    
   Parameters are: 

Expires May, 2001                                            [Page 53] 

JAVA LDAP API                                            November 2000 

      binder         An object that implements LDAPBind or LDAPRebind. 

4.7.8 setReferralFollowing 
    
   public void setReferralFollowing(boolean doReferrals) 
    
   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. 

4.7.9 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 
   timeout depends on the implementation. 
    
   Parameters are: 
    
      msLimit        Maximum milliseconds to wait. 

4.7.10 getClientControls 
    
   public LDAPControl[] getClientControls()  
    
   Returns controls to be used by the interface.  

4.7.11 getServerControls 
    
   public LDAPControl[] getServerControls()  
    
   Returns controls to be sent to the server.  

4.7.12 setClientControls 
    
   public void setClientControls( LDAPControl control )  
    
   public void setClientControls( LDAPControl[] controls )  

Expires May, 2001                                            [Page 54] 

JAVA LDAP API                                            November 2000 

   Sets controls for use by the interface.  
    
   Parameters are:  
    
      control        A single client control.  
       
      controls       An array of client controls.  

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

4.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. LDAPControl is an LDAPv3 
   extension, and is not supported in an LDAPv2 environment. 

4.8.1 Constructors 
    
   public LDAPControl(String id, 
                      boolean critical, 
                      byte[] vals) 
    
   Parameters are: 
    
      id             The type of the Control, as a string. 
       
      critical       True if the LDAP operation should be discarded if 
                      the server does not support this Control. 
       
      vals           Control-specific data. 

Expires May, 2001                                            [Page 55] 

JAVA LDAP API                                            November 2000 

4.8.2 clone 
    
   public Object clone() 
    
   Returns a deep copy of the object. 

4.8.3 getID 
    
   public String getID() 
    
   Returns the identifier of the control. 

4.8.4 getValue 
    
   public byte[] getValue() 
    
   Returns the control-specific data of the object. 

4.8.5 isCritical 
    
   public boolean isCritical() 
    
   Returns true if the control must be supported for an associated 
   operation to be executed. 

4.8.6 newInstance 
    
   public static LDAPControl newInstance(byte[] data) 
    
   Instantiates a control, given the raw data representing it in an LDAP 
   message. 

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

Expires May, 2001                                            [Page 56] 

JAVA LDAP API                                            November 2000 

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

4.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 [2] for a description of DIT 
   content rule representation in LDAP. 
    
4.9.1 Constructors 
    
   public LDAPDITContentRuleSchema(String name, 
                                   String oid, 
                                   String description, 
                                   boolean obsolete, 
                                   String[] auxiliary, 
                                   String[] required, 
                                   String[] optional, 
                                   String[] precluded, 
                                   String[] aliases) 
    
   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                Unique Object Identifier of the content rule - 
                         in dotted numerical format. 
       
      description        Optional description of the content rule. 
       
      obsolete           true if the content rule is obsolete.  
  
Expires May, 2001                                            [Page 57] 

JAVA LDAP API                                            November 2000 

      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". 
    
4.9.2 getAuxiliaryClasses 
    
   public String[] getAuxiliaryClasses() 
    
   Returns the list of allowed auxiliary classes. 
    
4.9.3 getRequiredAttributes 
    
   public String[] getRequiredAttributes() 
    
   Returns the list of additional required attributes for an entry 
   controlled by this content rule. 
     
4.9.4 getOptionalAttributes 
    
   public String[] getOptionalAttributes() 
    
   Returns the list of additional optional attributes for an entry 
   controlled by this content rule. 
  
Expires May, 2001                                            [Page 58] 

JAVA LDAP API                                            November 2000 

4.9.5 getPrecludedAttributes 
    
   public String[]getPrecludedAttributes() 
    
   Returns the list of precluded attributes for an entry controlled by 
   this content rule. 

4.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 [2] for a description of DIT structure rule representation in 
   LDAP. 
    
4.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. 

   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 numerical 
                         identifier. Structure rules aren't identified 
                         by OID. 
       
      description        Optional description of the structure rule. 
       
      obsolete           true if the structure rule is obsolete.  

Expires May, 2001                                            [Page 59] 

JAVA LDAP API                                            November 2000 

      nameForm           Either the identifier or 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". 
       
4.10.2 getRuleID 
    
   public int getRuleID() 
    
   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. 
    
4.10.3 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(). 
     
4.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. 

4.11 public class LDAPDN 
    
   A utility class representing a distinguished name (DN). 

4.11.1 equals 
    
   public static boolean equals(String dn1, String dn2) 
  
Expires May, 2001                                            [Page 60] 

JAVA LDAP API                                            November 2000 

   Returns true if the two strings correspond to the same DN, after 
   appropriate normalization. 
    
   Parameters are: 
    
      dn1            String form of first DN to compare. 
       
      dn2            String form of second DN to compare. 

4.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=Acme, Inc”, “cn=Acme\, Inc” is returned. 
    
   Parameters are: 
    
      rdn            The RDN to escape. 

4.11.3 unescapeRDN 
    
   public static String unescapeRDN(String rdn) 
    
   Returns the RDN after unescaping the characters requiring escaping 
   [4]. For example, for the rdn “cn=Acme\, Inc”, “cn=Acme, Inc” is 
   returned. 
    
   Parameters are: 
    
      rdn            The RDN to unescape. 

4.11.4 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,o=Acme,c=us" 
       
      noTypes        If true, returns only the values of the 
                      components, and not the names, e.g. "Babs 
                      Jensen", "Accounting", "Acme", "us" - instead of 

Expires May, 2001                                            [Page 61] 

JAVA LDAP API                                            November 2000 

                      "cn=Babs Jensen", "ou=Accounting", "o=Acme", and 
                      "c=us". 

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

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

4.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: 
    
      dn             The distinguished name of the new entry. The 
                      value is not validated. An invalid distinguished 
  
Expires May, 2001                                            [Page 62] 

JAVA LDAP API                                            November 2000 

                      name will cause adding of the entry to a 
                      directory to fail. 
       
      attrs          The initial set of attributes assigned to the 
                      entry. 

4.12.2 getAttribute 
    
   public LDAPAttribute[] getAttribute(String attrName) 
    
   Returns the attributes matching the specified attrName. 
    
   Parameters are: 
    
      attrName       The name of the attribute or attributes to 
                      return. See 4.3.5for the syntax and semantics 
                      relevant to this parameter. 

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

4.12.4 getDN 
    
   public String getDN() 

Expires May, 2001                                            [Page 63] 

JAVA LDAP API                                            November 2000 

   Returns the distinguished name of the entry. 

4.13 public interface LDAPEntryComparator 
    
   An object of this class can implement arbitrary sorting algorithms 
   for search results. 

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

4.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 of a duplicate entry). 
    
   Most errors that occur throw this type of exception.  The 
   getLDAPResultCode() method returns the specific result code, which 
   can be compared against standard LDAP result codes as defined in [5], 
   section 4. 

4.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 May, 2001                                            [Page 64] 

JAVA LDAP API                                            November 2000 

                        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 maximal subset of a specified DN which could 
                      be matched by the server on a search operation 

4.14.2 errorCodeToString 
    
   public String errorCodeToString() 
    
   Returns a String representing the internal error code, in the default 
   Locale. 

   public static String errorCodeToString( int code ) 
    
   Returns a String representing an arbitrary error code, in the default 
   Locale, or null if there is no such code. 

   public String errorCodeToString( Locale locale ) 
    
   Returns a String representing the internal error 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 error 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. 

   Parameters are: 
    
      code           One of the error codes listed in "Result codes" 
                      below. 
       
      locale         A Locale in which to render the error String. 

Expires May, 2001                                            [Page 65] 

JAVA LDAP API                                            November 2000 

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

4.14.4 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 [5]. Otherwise, a local error 
   code is returned (see "Result codes" below). 

4.14.5 getMatchedDN 
    
   public String getMatchedDN() 
    
   Returns the part of a submitted distinguished name which could be 
   matched by the server. If the exception was caused by a local error, 
   such as no server available, the return value is null. If the 
   exception resulted from an operation being executed on a server, the 
   value is an empty String except when the result of the operation was 
   one of the following: 
    
      NO_SUCH_OBJECT 
      ALIAS_PROBLEM 
      INVALID_DN_SYNTAX 
      ALIAS_DEREFERENCING_PROBLEM 

4.14.6 Result codes 
    
   See [5] for a discussion of the meanings and values of the codes. The 
   corresponding ASN.1 name from [5] 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) 
  
Expires May, 2001                                            [Page 66] 

JAVA LDAP API                                            November 2000 

        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) 
        LDAP_PARTIAL_RESULTS 
        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) 
    
   Note: LDAP_PARTIAL_RESULTS (9) is not defined in [5], but is returned 
   by a number of LDAP servers to LDAPv2 clients as an indication of a 
   referral (subordinate reference). 
    
   Local errors, resulting from actions other than an operation on a 
   server, are among the following: 
    
        AUTH_UNKNOWN (0x56) 
        CLIENT_LOOP  (0x60) 
        CONNECT_ERROR (0x5b) 
        CONTROL_NOT_FOUND (0x5d) 
        DECODING_ERROR (0x54) 
        ENCODING_ERROR (0x53) 
        FILTER_ERROR (0x57) 
        LOCAL_ERROR (0x52) 
        LDAP_NOT_SUPPORTED (0x5c) 
        LDAP_TIMEOUT (0x55) 
        MORE_RESULTS_TO_RETURN (0x5f) 
        NO_MEMORY (0x5a) 
  
Expires May, 2001                                            [Page 67] 

JAVA LDAP API                                            November 2000 

        NO_RESULTS_RETURNED (0x5e) 
        PARAM_ERROR (0x59) 
        REFERRAL_LIMIT_EXCEEDED (0x61) 
        SERVER_DOWN (0x51) 
        USER_CANCELLED (0x58) 
        TLS_NOT_SUPPORTED (0x70) 

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

4.15.1 Constructors 
    
   public LDAPExtendedOperation(String oid, 
                                byte[] vals) 
    
   Constructs a new object with the specified object ID and data. 
    
   Parameters are: 
    
      oid            The unique identifier of the operation. 
       
      vals           The operation-specific data of the operation. 

4.15.2 getID 
    
   public String getID() 
    
   Returns the unique identifier of the operation. 

4.15.3 getValue 
    
   public byte[] getValue() 
    
   Returns the operation-specific data (not a copy, a reference). 

4.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: 

Expires May, 2001                                            [Page 68] 

JAVA LDAP API                                            November 2000 

      value          The value to be assigned to the object. 

4.16 public class LDAPExtendedResponse 
                  extends LDAPResponse 
    
   An LDAPExtendedResponse object encapsulates a server response to an 
   asynchronous extended operation request. 
    
4.16.1 getID 
    
   public String getID() 
    
   Returns the OID of the response. 

4.16.2 getValue 
    
   public byte[] getValue() 
    
   Returns the raw bytes of the value part of the response. 

4.17 public interface LDAPListener 
    
   Represents the message queue associated with a particular 
   asynchronous LDAP operation or operations. 
    
4.17.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. 
    
4.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. 
    
   Parameters are: 
  
Expires May, 2001                                            [Page 69] 

JAVA LDAP API                                            November 2000 

      msgid              A particular message to query for responses 
                         available. 

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

   Parameters are: 
    
      msgid              A particular message to query for responses 
                         available. 
    
4.17.4 merge 
    
   public void merge(LDAPListener listener2) 
    
   Merges two listeners. Moves/appends the content from another            
   listener to this one. 

4.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 [2] for a 
   description of matching rule representation in LDAP. 

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

Expires May, 2001                                            [Page 70] 

JAVA LDAP API                                            November 2000 

   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                Unique Object Identifier of the attribute - in 
                         dotted numerical format. 
       
      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       Unique Object Identifier of the syntax that 
                         this matching rule is valid for - in dotted 
                         numerical 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. 

4.18.2 getAttributes 

Expires May, 2001                                            [Page 71] 

JAVA LDAP API                                            November 2000 

   public String[] getAttributes() 
    
   Returns the OIDs of the attributes to which this rule applies. 
    
4.18.3 getSyntaxString 
    
   public String[] getSyntaxString() 
    
   Returns the OID of the syntax that this matching rule is valid for. 

4.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 identifier of a matching rule, and a list off attributes 
   that it applies to.  See [2] for a description of matching rule use 
   representation in LDAP. 
    
4.19.1 Constructors 
    
   public LDAPMatchingRuleUseSchema(String name, 
                                    String oid, 
                                    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                Unique Object Identifier of the matching rule 
                         - in dotted numerical format. 
       
      description        Optional description of the matching rule use. 
       
      obsolete           true if the matching rule use is obsolete.  

Expires May, 2001                                            [Page 72] 

JAVA LDAP API                                            November 2000 

      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". 
    
4.19.2 getAttributes 
    
   public String[] getAttributes() 
    
   Returns an array of all the attributes that this matching rule 
   applies to.  

4.20 public class LDAPMessage 
    
   Base class for asynchronous LDAP request and response messages. 
    
4.20.1 getControls 
    
   public LDAPControl[] getControls() 
    
   Returns any controls in the message. 
    
4.20.2 getMessageID 
    
   public int getMessageID() 
    
   Returns the message ID. 
    
4.20.3 getType 
    
   public int getType() 
    
   Returns the LDAP operation type of the message. The type is one of 
   the following: 
    
      BIND_REQUEST (0x60) 
      BIND_RESPONSE (0x61) 
      UNBIND_REQUEST (0x42) 
      SEARCH_REQUEST (0x63) 
      SEARCH_RESPONSE (0x64) 
      SEARCH_RESULT (0x65) 
      MODIFY_REQUEST (0x66) 
      MODIFY_RESPONSE (0x67) 
      ADD_REQUEST (0x68) 
      ADD_RESPONSE (0x69) 
  
Expires May, 2001                                            [Page 73] 

JAVA LDAP API                                            November 2000 

      DEL_REQUEST (0x4a) 
      DEL_RESPONSE (0x6b) 
      MODIFY_RDN_REQUEST (0x6c) 
      MODIFY_RDN_RESPONSE (0x6d) 
      COMPARE_REQUEST (0x6e) 
      COMPARE_RESPONSE (0x6f) 
      ABANDON_REQUEST (0x50) 
      SEARCH_RESULT_REFERENCE (0x73) 
      EXTENDED_REQUEST (0x77) 
      EXTENDED_RESPONSE (0x78) 

4.21 public class LDAPModification 
    
   A single change specification for an LDAPAttribute. 

4.21.1 Constructors 
    
   public LDAPModification(int op, 
                           LDAPAttribute attr) 
    
   Specifies a modification to be made to an attribute. 
    
   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. 

4.21.2 getAttribute 
    
   public LDAPAttribute getAttribute() 
    
   Returns the attribute (possibly with values) to be modified. 

4.21.3 getOp 

Expires May, 2001                                            [Page 74] 

JAVA LDAP API                                            November 2000 

   public int getOp() 
    
   Returns the type of modification specified by this object. 

4.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 
       
      MODIFY (2)     The value should replace all existing values of 
                      the attribute 

4.22 public class LDAPModificationSet 
    
   A collection of modifications to be made to the attributes of a 
   single entry. 

4.22.1 Constructors 
    
   public LDAPModificationSet() 
    
   Constructs a new, empty set of modifications. 

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

4.22.3 elementAt 
    
   public LDAPModification elementAt(int index) 
                               throws ArrayIndexOutOfBoundsException 
    
   Retrieves a particular LDAPModification object at the position 
   specified by the index. 
  
Expires May, 2001                                            [Page 75] 

JAVA LDAP API                                            November 2000 

   Parameters are: 
    
      index          Index of the modification to get. 

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

4.22.5 removeElementAt 
    
   public void removeElementAt(int index) 
                               throws ArrayIndexOutOfBoundsException 
    
   Removes a particular LDAPModification object at the position 
   specified by the index. 
    
   Parameters are: 
    
      index          Index of the modification to remove. 

4.22.6 size 
    
   public int size() 
    
   Retrieves the number of LDAPModification objects in this set. 

4.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 [2] for a description of same form 
   representation in LDAP. 
 
4.23.1 Constructors 
    
   public LDAPNameFormSchema(String name, 
                             String oid, 
                             String description, 
                             boolean obsolete, 
  
Expires May, 2001                                            [Page 76] 

JAVA LDAP API                                            November 2000 

                             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                Unique Object Identifier of the name form - in 
                         dotted numerical format. 
       
      description        Optional description of the name form. 
       
      obsolete           true if the name form is obsolete.  
       
      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". 

4.23.2 getObjectClass 
    
   public String getObjectClass() 
    
   Returns the name of the object class that this name form applies to. 

Expires May, 2001                                            [Page 77] 

JAVA LDAP API                                            November 2000 

4.23.3 getRequiredNamingAttributes 
    
   public String[]getRequiredNamingAttributes() 
    
   Returns the list of required naming attributes for an entry 
   controlled by this name form. 
    
4.23.4 getOptionalNamingAttributes 
    
   public String[]getOptionalNamingAttributes() 
    
   Returns the list of optional naming attributes for an entry 
   controlled by this content rule. 

4.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 
   to add or delete an object class definition in a Directory. See [2] 
   for a description of object class representation in LDAP. 

4.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            Unique Object Identifier of the object class - in 
                      dotted numerical format. 
  
Expires May, 2001                                            [Page 78] 

JAVA LDAP API                                            November 2000 

      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. 
       
      raw            The raw String value returned on a Directory 
                      query for "objectclasses". 

4.24.2 getSuperiors 
    
   public String[] getSuperiors() 
    
   Returns the object classes which this one derives from. 

4.24.3 getRequiredAttributes 
    
   public String[] getRequiredAttributes() 
    
   Returns a list of attributes required of an entry with this object 
   class. 

4.24.4 getOptionalAttributes 
    
   public String[] getOptionalAttributes() 
    
   Returns a list of attributes acceptable but not required of an entry 
   with this object class. 
    
4.24.5 getType 
    
   public int getType() 
    
   Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are 
   constants defined in LDAPObjectClassSchema. 
  
Expires May, 2001                                            [Page 79] 

JAVA LDAP API                                            November 2000 

    
4.25 public class LDAPRebindAuth 
    
   Represents information used to authenticate the client in cases where 
   the client follows referrals automatically. 

4.25.1 Constructors 
    
   public LDAPRebindAuth( String dn, 
                          String 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. 
       
4.25.2 getDN 
    
   public String getDN() 
    
   Returns the distinguished name to be used for reauthentication on 
   automatic referral following. 

4.25.3 getPassword 
    
   public String getPassword() 
    
   Returns the password to be used for reauthentication on automatic 
   referral following. 

4.26 public interface LDAPRebind 
                      extends LDAPReferralHandler 
 
   Used to provide credentials for reauthentication on processing a 
   referral. 

4.26.1 getRebindAuthentication 
    
   public LDAPRebindAuth getRebindAuthentication(String host, int port) 

Expires May, 2001                                            [Page 80] 

JAVA LDAP API                                            November 2000 

   Returns an object which can provide credentials for authenticating to 
   a server at the provided host name and port number. 
    
   Parameters are: 
    
      host           Contains a hostname or dotted string representing 
                      the IP address of a host running an LDAP server. 
       
      port           Contains the TCP or UDP port number to connect 
                      to. 

4.27 public class LDAPReferralException 
                  extends LDAPException 
    
   This exception, derived from LDAPException, is thrown when a server 
   returns a referral and automatic referral following has not been 
   enabled. 

4.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, 
                                LDAPException 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 when the referral was not 
   followed. 

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

Expires May, 2001                                            [Page 81] 

JAVA LDAP API                                            November 2000 

   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 

4.27.2 getReferralFailureException 
    
   public LDAPException getReferralFailureException () 
    
   Returns the LDAPException which caused the referral to fail, if any. 
    
4.27.3 getReferrals 
    
   public String[] getReferrals() 
    
   Gets the list of referrals (LDAP URLs to other servers) returned by 
   the LDAP server 
   The referrals may include URLs of a type other than ones for an LDAP 
   server (i.e. a referral URL other than ldap://something). 

4.28 public interface LDAPReferralHandler 
    
   Shared ancestor to the two types of referal objects - LDAPBind and 
   LDAPRebind. 

4.29 public class LDAPResponse 
                  extends LDAPMessage 
    
   Represents the response to a particular asynchronous LDAP operation. 

4.29.1 getErrorMessage 
    
   public String getErrorMessage() 
    
   Returns any error message in the response. 

4.29.2 getMatchedDN 
    
   public String getMatchedDN() 

Expires May, 2001                                            [Page 82] 

JAVA LDAP API                                            November 2000 

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

4.29.3 getReferrals 
    
   public String[] getReferrals() 
    
   Returns all referrals, if any, in a server response. 

4.29.4 getResultCode 
    
   public int getResultCode() 
    
   Returns the result code in a server response, as defined in [5]. 

4.30 public class LDAPResponseListener 
                  implements LDAPListener 
    
   Represents the message queue associated with a particular 
   asynchronous LDAP operation or operations. 

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

4.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. 
    
   Parameters are: 
    
      msgid              A particular message to query for responses 
                         available. 
  
Expires May, 2001                                            [Page 83] 

JAVA LDAP API                                            November 2000 

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

   Parameters are: 
    
      msgid              A particular message to query for responses 
                         available. 
    
4.30.4 merge 
    
   public void merge(LDAPListener listener2) 
    
   Merges two response listeners. Moves/appends the content from another            
   listener to this one. 

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

4.31.1 Constructors 
    
   public LDAPSchema() 
    
   Constructs an empty LDAPSchema object. 

4.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 
  
Expires May, 2001                                            [Page 84] 

JAVA LDAP API                                            November 2000 

   Retrieves the schema in effect at 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() (4.6.34) if the schema cannot be retrieved 
   with the specified connection. 
    
   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. 

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

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

4.31.5 getMatchingRule 
    
   public LDAPMatchingRuleSchema getMatchingRule( String name ) 
    
   Returns a particular matching rule definition, or null if not found. 
    
   Parameters are: 

Expires May, 2001                                            [Page 85] 

JAVA LDAP API                                            November 2000 

      name           Name of the matching rule for which a definition 
                      is to be returned. 
 
4.31.6 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. 

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

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

4.31.9 getNameForm 
    
   public LDAPNameFormSchema getNameForm( String name ) 
    
   Returns a particular name form definition, or null if not found. 

Expires May, 2001                                            [Page 86] 

JAVA LDAP API                                            November 2000 

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

4.31.10 getSyntax 
    
   public LDAPSyntaxSchema getSyntax( String oid ) 
    
   Returns a particular syntax definition, or null if not found. 
    
   Parameters are: 
    
      oid            Identifier of the syntax for which a definition 
                     is to be returned. 

4.31.11 getAttributes 
    
   public Enumeration getAttributes() 
    
   Returns an enumeration of attribute definitions. 

4.31.12 getObjectClasses 
    
   public Enumeration getObjectClasses() 
    
   Returns an enumeration of object class definitions. 

4.31.13 getMatchingRules 
    
   public Enumeration getMatchingRules() 
    
   Returns an enumeration of matching rule definitions. 

4.31.14 getMatchingRuleUses 
    
   public Enumeration getMatchingRuleUses() 
    
   Returns an enumeration of LDAPMatchingRuleUseSchema objects. 

4.31.15 getDITStructureRules 
    
   public Enumeration getDITStructureRules() 
    
   Returns an enumeration of LDAPDITStructureRuleSchema objects. 

Expires May, 2001                                            [Page 87] 

JAVA LDAP API                                            November 2000 

4.31.16 getDITContentRules 
    
   public Enumeration getDITContentRules() 
    
   Returns an enumeration of LDAPDITContentRuleSchema objects. 

4.31.17 getNameForms 
    
   public Enumeration getNameForms() 
    
   Returns an enumeration of LDAPNameFormSchema objects. 

4.31.18 getSyntaxes 
    
   public Enumeration getSyntaxes() 
    
   Returns an enumeration of LDAPSyntaxSchema objects. 

4.31.19 getAttributeNames 
    
   public Enumeration getAttributeNames() 
    
   Returns an enumeration of attribute names. 

4.31.20 getObjectClassNames 
    
   public Enumeration getObjectClassNames() 
    
   Returns an enumeration of object class names. 

4.31.21 getMatchingRuleNames 
    
   public Enumeration getMatchingRuleNames() 
    
   Returns an enumeration of matching rule names. 

4.31.22 getMatchingRuleUseNames 
    
   public Enumeration getMatchingRuleUseNames() 
    
   Returns an enumeration of matching rule use names. 

4.31.23 getDITStructureRuleNames 

Expires May, 2001                                            [Page 88] 

JAVA LDAP API                                            November 2000 

   public Enumeration getDITStructureRuleNames () 
    
   Returns an enumeration of structure rule names. 

4.31.24 getDITContentRuleNames 
    
   public Enumeration getDITContentRuleNames () 
    
   Returns an enumeration of content rule names. 

4.31.25 getNameFormNames 
    
   public Enumeration getNameFormNames () 
    
   Returns an enumeration of name form names. 

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

4.32.1 getAliases 
    
   public String[] getAliases() 
    
   Returns an array of alternative names of the element, or null if 
   there are none. With respect to the protocol-level schema element 
   syntax definition of [2], the array consists of all values but the 
   first of the NAME qualifier. 

4.32.2 getDescription 
    
   public String getDescription() 
    
   Returns the description of the element. With respect to the protocol-
   level schema element syntax definition of [2], the value is that of 
   the DESC qualifier. 

4.32.3 getName 
    
   public String getName() 
    
   Returns the name of the element. With respect to the protocol-level 
   schema element syntax definition of [2], the value is that of the 
   first NAME qualifier. 

Expires May, 2001                                            [Page 89] 

JAVA LDAP API                                            November 2000 

4.32.4 getID 
    
   public String getID() 
    
   Returns the Unique Object Identifier of the element. 

4.32.5 getQualifier 
    
   public String[] getQualifier(String name) 
    
   Returns an array of all values of a specified optional or non-
   standard qualifier of the element. This method may be used to access 
   the values of vendor-specific qualifiers (which begin with "X-" [2]). 
    
   Parameters are: 
    
      name           The name of the qualifier, case-sensitive. 

4.32.6 getQualifierNames 
    
   public Enumeration getQualifierNames() 
    
   Returns an enumeration of all qualifiers of the element which are not 
   defined in [2]. 

4.32.7 isObsolete 
    
   public boolean isObsolete() 
    
   Returns true if the element is obsolete (has the OBSOLETE qualifier 
   in its LDAP definition [2]. 

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

4.32.9 setQualifier 
    
   public void setQualifier(String name, String[] values) 
    
   Sets the values of a specified optional or non-standard qualifier of 
   the element. This method may be used to set the values of vendor-
   specific qualifiers (which begin with "X-" [2]). 
  
Expires May, 2001                                            [Page 90] 

JAVA LDAP API                                            November 2000 

   Parameters are: 
    
      name           The name of the qualifier, case-sensitive. 
       
      values         The values to set for the qualifier. 

4.32.10 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. 
    
   Parameters are: 
    
      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. 

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

4.32.12 modify 
    
   public void modify(LDAPConnection ld 
                      LDAPSchemaElement newValue) throws LDAPException 
    
   public void modify(LDAPConnection ld 
  
Expires May, 2001                                            [Page 91] 

JAVA LDAP API                                            November 2000 

                      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. 

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

4.33.1 Constructors 
    
   public LDAPSearchConstraints() 
    
   Constructs an LDAPSearchConstraints object that specifies the default 
   set of search constraints. 

   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 
  
Expires May, 2001                                            [Page 92] 

JAVA LDAP API                                            November 2000 

                      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, 
                      when doing automatic referral following. It is 
                      ignored for asynchronous operations. The value is 
                      10 by default. 

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

4.33.3 getDereference 

Expires May, 2001                                            [Page 93] 

JAVA LDAP API                                            November 2000 

   public int getDereference() 
    
   Specifies when aliases should be dereferenced. Returns either 
   DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or 
   DEREF_ALWAYS. 

4.33.4 getMaxResults 
    
   public int getMaxResults() 
    
   Returns the maximum number of search results to be returned; 0 means 
   no limit. 

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

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

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

4.33.8 setMaxResults 

Expires May, 2001                                            [Page 94] 

JAVA LDAP API                                            November 2000 

   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. 

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

4.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). 

4.34 public class LDAPSearchListener 
                  implements LDAPListener 
    
   An LDAPSearchListener manages search results and references returned 
   on one or more asynchronous search requests. 

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

Expires May, 2001                                            [Page 95] 

JAVA LDAP API                                            November 2000 

4.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. 
    
   Parameters are: 
    
      msgid              A particular message to query for responses 
                         available. 

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

   Parameters are: 
    
      msgid              A particular message to query for responses 
                         available. 

4.34.4 isComplete 

   public boolean isComplete(int msgid) 
    
   Reports true if all results have been received for a particular 
   message id, i.e. a response has been received from the server for the 
   id. There may still be messages waiting to be retrieved with 
   getResponse. 
  
Expires May, 2001                                            [Page 96] 

JAVA LDAP API                                            November 2000 

    
   Parameters are: 
    
      msgid              A particular message to query for completion. 

4.34.5 merge 
    
   public void merge(LDAPSearchListener listener2) 
    
   Merges two search listeners. Moves/appends the content from another            
   search listener to this one. 

4.35 public class LDAPSearchResult 
                  extends LDAPMessage 
    
   An LDAPSearchResult object encapsulates a single asynchronous search 
   result. 

4.35.1 getEntry 
    
   public LDAPEntry getEntry() 
    
   Returns the entry of a server search response. 

4.36 public class LDAPSearchResultReference 
                  extends LDAPMessage 
    
   An LDAPSearchResultReference object encapsulates a continuation 
   reference from an asynchronous search operation. 

4.36.1 getReferrals 
    
   public String[] getReferrals() 
    
   Returns any referral URLs in the object. 

4.37 public class LDAPSearchResults 
                  implements Enumeration 
    
   An LDAPSearchResults object is returned from a synchronous search 
   operation. It implements Enumeration, thereby providing access to all 
   entries retrieved during the operation. 

Expires May, 2001                                            [Page 97] 

JAVA LDAP API                                            November 2000 

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

4.37.2 getResponseControls 
    
   public LDAPControl[] getResponseControls() 
    
   Returns the latest Server Controls returned by a Directory Server 
   in the context of this search request, or null 
   if no Server Controls were returned. 

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

4.37.4 next 
    
   public LDAPEntry next() throws LDAPException 
    
   Returns the next result in the enumeration as an LDAPEntry. If 
   automatic referral following is disabled or a referral was not 
   followed, next() will throw an LDAPReferralException when the 
   referral is received. 

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

4.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 
  
Expires May, 2001                                            [Page 98] 

JAVA LDAP API                                            November 2000 

   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. 

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

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

   Returns a socket connected using the provided host name and port 
   number. 
    
   There may be additional makeSocket methods defined when interfaces to 
   establish TLS and SASL authentication in the Java environment have 
   been standardized. 
    
   Parameters are: 
    
      host           Contains a hostname or dotted string representing 
                      the IP address of a host running an LDAP server 
                      to connect to. 
       
      port           Contains the TCP or UDP port number to connect to 
                      or contact. The default LDAP port is 389. 

Expires May, 2001                                            [Page 99] 

JAVA LDAP API                                            November 2000 

4.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 [2] 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. 

4.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            Unique Object Identifier of the syntax - in 
                      dotted numerical format. 
       
      description    Optional description of the syntax. 
       
      raw            The raw String value returned on a Directory 
                      query for "ldapSyntaxes". 

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

4.40.1 Constructors 
    
   public LDAPUrl(String url) throws MalformedURLException 
    
   Constructs a URL object with the specified string as URL. 

Expires May, 2001                                           [Page 100] 

JAVA LDAP API                                            November 2000 

   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, 
                  String filter) 
    
   public LDAPUrl(String host, 
                  int port, 
                  String dn, 
                  String[] attrNames, 
                  int scope, 
                  String filter, 
                  boolean secure) 
    
   Constructs a full-blown LDAP URL to specify an LDAP search operation. 
    
   Parameters are: 
    
      url            An explicit URL string, e.g. 
                      "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn
                      ,sn?sub?(objectclass=inetOrgPerson)". 
       
      host           Host name of LDAP server, or null for "nearest 
                      X.500/LDAP". 
       
      port           Port number for LDAP server (use 
                      LDAPConnection.DEFAULT_PORT for default port). 
       
      dn             Distinguished name of object to fetch. 
       
      attrNames      Names of attributes to retrieve. null for all 
                      attributes. 
       
      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 [3]. 
    
      secure         True to create an LDAP URL of the "ldaps" type. 

Expires May, 2001                                           [Page 101] 

JAVA LDAP API                                            November 2000 

4.40.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 [8] for details on URL encoding/decoding. 
    
   Parameters are: 
    
      URLEncoded     String to decode. 

4.40.3 encode 
    
   public static String encode(String toEncode) 
    
   Encodes an arbitrary string. Any illegal characters are encoded as 
   %HH.  However, this method does NOT encode " " into "+". 
    
   Parameters are: 
    
      toEncode       String to encode. 

4.40.4 getAttributeArray 
    
   public String[] getAttributeArray() 
    
   Returns an array of attribute names specified in the URL. 

4.40.5 getAttributes 
    
   public Enumeration getAttributes() 
    
   Returns an Enumerator for the attribute names specified in the URL. 

4.40.6 getDN 
    
   public String getDN() 
    
   Returns the distinguished name encapsulated in the URL. 

4.40.7 getExtensions 
    
   public String[] getExtensions () 

Expires May, 2001                                           [Page 102] 

JAVA LDAP API                                            November 2000 

   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. 

4.40.8 getFilter 
    
   public String getFilter() 
    
   Returns the search filter [6], or the default filter - 
   (objectclass=*) - if none was specified. 

4.40.9 getHost 
    
   public String getHost() 
    
   Returns the host name of the LDAP server to connect to. 

4.40.10 getPort 
    
   public int getPort() 
    
   Returns the port number of the LDAP server to connect to. 

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

4.40.12 getUrl 
    
   public String getUrl() 
    
   Returns a valid string representation of this LDAP URL. 

4.40.13 isSecure 
    
   public boolean isSecure() 
    
   Returns true if the URL is of the type ldaps (LDAP over SSL, a 
   predecessor to startTLS). 

Expires May, 2001                                           [Page 103] 

JAVA LDAP API                                            November 2000 

4.41 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(); 
      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. 

5. 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. 
   An interface to using SASL for configurable authentication and 
   session protection is provided, but implementations are outside the 
   scope of this document. 

6. 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 Merrell of Novell. 
  
Expires May, 2001                                           [Page 104] 

JAVA LDAP API                                            November 2000 

     
7. Bibliography 
    
   [1]  The Directory: Selected Attribute Syntaxes.  CCITT, 
        Recommendation X.520. 
    
   [2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 
        Access Protocol: Attribute Syntax Definitions", 
        RFC 2252, December 1997 
    
   [3]  T. Howes, "A String Representation of LDAP Search Filters," RFC 
        2254, December 1997. 
    
   [4]  S. Kille, " UTF-8 String Representation of Distinguished Names," 
        RFC 2253, December 1997. 
    
   [5]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 
        Protocol (v3)", RFC 2251, December 1997. 
    
   [6]  T. Howes, M. Smith, "An LDAP URL Format", RFC 2255, December 
        1997. 
    
   [7]  T. Howes, M. Smith, "The LDAP Application Program Interface", 
        Internet Draft draft-ietf-ldapext-ldap-c-api-04.txt, 1999. 
    
   [8] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource 
        Locators (URL)", RFC 1738, December 1994. 
    
   [9] H. Alvestrans, "Tags for the Identification of Languages", RFC 
        1766, March 1995. 
    
   [10] T. Dierks, C. Allen, "The TLS Protocol", RFC 2246, January 1999. 

8. Authors' Addresses 
    
   Rob Weltman 
   +1 650 461 1708 
   [email-masked] 
    
   Christine Tomlinson 
   Innosoft International, Inc. 
   8911 Capital of Texas Highway 
   Suite 4140 
   Austin, TX  US  78759 
   +1 512 231 1600 
   [email-masked] 
    
   Miodrag Kekic 
   Netscape Communications Corp. 
   501 E. Middlefield Rd. 
  
Expires May, 2001                                           [Page 105] 

JAVA LDAP API                                            November 2000 

   Mountain View, CA 94043 
   USA 
   +1 650 937-5663 
   [email-masked] 
    
   Steven Sonntag 
   Novell, Inc. 
   1800 South Novell Place 
   Provo, UT 84606 
   USA 
   +1 801 861 7097 
   [email-masked] 
    
   Jim Sermersheim 
   Novell, Inc. 
   1800 South Novell Place 
   Provo, UT 84606 
   USA 
   +1 801 861 3088 
   [email-masked] 
    
   Mark Smith 
   Netscape Communications Corp. 
   501 E. Middlefield Rd. 
   Mountain View, CA 94043 
   USA 
   +1 650 937-3477 
   [email-masked] 
    
   Tim Howes 
   Loudcloud, Inc. 
   599 N. Mathilda Ave. 
   Sunnyvale, CA 94086 
   USA 
   +1 650 321-4565 x111 
   [email-masked] 

Expires May, 2001                                           [Page 106] 

JAVA LDAP API                                            November 2000 

9. Appendix A - Sample java LDAP programs 
    
9.1 Java LDAP programs using synchronous methods 
    
   import netscape.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 ); 
                /* authenticate to the directory as nobody */ 
               /* This is not really necessary if explicit 
                  authentication is not desired, because there is 
                  already anonymous authentication at connect time */ 
               ld.bind( "", "" ); 
    
               /* search for all entries with surname of Jensen */ 
               String MY_FILTER = "sn=Jensen"; 
               String MY_SEARCHBASE = "o=Ace Industry, c=US"; 
    
               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(); 
  
Expires May, 2001                                           [Page 107] 

JAVA LDAP API                                            November 2000 

                   Enumeration enumAttrs = findAttrs.getAttributes(); 
                   System.out.println( "Attributes: " ); 
                   /* Loop on attributes */ 
                   while ( enumAttrs.hasMoreElements() ) { 
                       LDAPAttribute anAttr = 
                           (LDAPAttribute)enumAttrs.nextElement(); 
                       String attrName = anAttr.getName(); 
                       System.out.println( "" + attrName ); 
                       /* Loop on values for this attribute */ 
                       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 May, 2001                                           [Page 108] 

JAVA LDAP API                                            November 2000 

   import netscape.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 ); 
    
               /* authenticate to the directory as Bab Jensen */ 
               String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US"; 
               String MY_PASSWORD = "MysteryLady"; 
               ld.bind( MY_NAME, MY_PASSWORD ); 
    
               /* Prepare to change my email address */ 
               LDAPAttribute attrEmail = 
                       new LDAPAttribute( "mail", "[email-masked]" ); 
               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 May, 2001                                           [Page 109] 

JAVA LDAP API                                            November 2000 

   import netscape.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 May, 2001                                           [Page 110] 

JAVA LDAP API                                            November 2000 

               ); 
    
           } 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 May, 2001                                           [Page 111] 

JAVA LDAP API                                            November 2000 

9.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.getErrorMessage(), 
                   response.getMatchedDN()); 
               } 
    
               /* search for all entries with surname of Jensen */ 
               String MY_FILTER = "sn=Jensen"; 
               String MY_SEARCHBASE = "o=Ace Industry, c=US"; 
    
               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).getUrls(); 
                       // Do something with the referrals... 
  
Expires May, 2001                                           [Page 112] 

JAVA LDAP API                                            November 2000 

                   } 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.getErrorMessage(), 
                                                  res.getMatchedDN() ); 
                       } 
                   } 
               } 
           } catch ( LDAPException e ) { 
               System.err.println( e.toString() ); 
           } 
           /* Done, so disconnect */ 
           if ( ld.isConnected() ) { 
               ld.disconnect(); 
           } 
       } 
   } 

Expires May, 2001                                           [Page 113] 

JAVA LDAP API                                            November 2000 

   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 [3]; 
               String[] hosts = { "foo1", "foo2", "foo3" }; 
               int[] ports = { 389, 389, 2018 } 
               String[] bases = 
                   { "o=Airius.com", "o=Acme.com", "dc=Acme,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 May, 2001                                           [Page 114] 

JAVA LDAP API                                            November 2000 

   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 = 
                   { "o=Airius.com", "o=Acme.com", "dc=Acme,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 May, 2001                                           [Page 115] 

JAVA LDAP API                                            November 2000 

   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 ); 
    
               /* authenticate to the directory as Bab Jensen */ 
               String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US"; 
               String MY_PASSWORD = "MysteryLady"; 
               ld.bind( MY_NAME, MY_PASSWORD ); 
    
               /* Prepare to change my email address */ 
               LDAPAttribute attrEmail = 
                       new LDAPAttribute( "mail", "[email-masked]" ); 
               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 May, 2001                                           [Page 116] 

JAVA LDAP API                                            November 2000 

10. Appendix B - Changes from ldap-java-api-11.txt 

   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. 

Expires May, 2001                                           [Page 117] 

JAVA LDAP API                                            November 2000 

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

Expires May, 2001                                           [Page 118] 

JAVA LDAP API                                            November 2000 

   LDAPResponseListener 
    
        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 [5]. 

11. Appendix C - 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 [10]).  
    
   LDAPConstraints 
    
        Default for setHopLimit is 10, not 5. 

   LDAPUrl 
    
        Added getScope and getExtensions. 

Expires May, 2001                                           [Page 119] 

JAVA LDAP API                                            November 2000 

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

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

12. Appendix D - 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 

Expires May, 2001                                           [Page 120] 

JAVA LDAP API                                            November 2000 

        Added LDAPDITContentRuleSchema, LDAPDITStructureRuleSchema, 
        LDAPMatchingRuleUseSchema, LDAPNameFormSchema, LDAPSyntaxSchema. 

13. Appendix E - 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. 

14. Appendix F - 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(). 

15. Appendix G - 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 

Expires May, 2001                                           [Page 121] 

JAVA LDAP API                                            November 2000 

        Added getInputStream()getOutputStream(), setInputStream() 
        (4.6.36), and setOutputStream(). They are used when establishing 
        a security layer with SASL, and may also be used to interpose a 
        proxy. 

   LDAPDN 
    
        Added equals(). 

   LDAPException 
    
        Added additional error codes defined in [7]. 

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

16. Appendix H - Changes from ldap-java-api-05.txt 

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

   LDAPConstraints 

Expires May, 2001                                           [Page 122] 

JAVA LDAP API                                            November 2000 

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

   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. 

17. Appendix I - 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). 

18. Appendix J - Changes from ldap-java-api-03.txt 

   LDAPBind 
    
        New interface, to support sophisticated reauthentication 
        mechanisms. 

Expires May, 2001                                           [Page 123] 

JAVA LDAP API                                            November 2000 

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

19. Appendix K - Changes from ldap-java-api-02.txt 

   LDAPSearchConstraints 

Expires May, 2001                                           [Page 124] 

JAVA LDAP API                                            November 2000 

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

   LDAPRebind 
    
        Renamed to LDAPReauthentication. Added a definition of its 
        single method. 
    
   LDAPRebindProc 
    
        Renamed to LDAPCredentials. 

20. Appendix L - 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 

Expires May, 2001                                           [Page 125] 

JAVA LDAP API                                            November 2000 

        Added signatures that pass LDAPConstraints to the following 
        methods: 
                add() 
                compare() 
                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 May, 2001                                           [Page 126]