Network Working Group Rob Weltman INTERNET-DRAFT Netscape Communications Corp. Intended Category: Standards Track Christine Tomlinson Sun Microsystems, Inc. Steven Sonntag Novell, Inc. July 2002 The Java LDAP Application Program Interface draft-ietf-ldapext-ldap-java-api-18.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document defines a Java [JAVA] language application program interface to the Lightweight Directory Access Protocol (LDAP) [LDAPv3], in the form of a class library. Conventions Used in this Document The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as defined in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. Expires January 2003 [Page 1] JAVA LDAP API July 2002 1. Overview............................................................9 1.1 The LDAP model.....................................................9 1.2 Package name......................................................10 1.3 The LDAP classes..................................................10 1.4 The LDAP asynchronous methods.....................................11 1.5 Interfaces........................................................11 1.6 Classes...........................................................12 1.7 Exceptions........................................................15 1.8 LDAP API use......................................................15 2. The Java LDAP classes..............................................17 2.1 public class LDAPAttribute........................................17 2.1.1 Constructors....................................................17 2.1.2 addValue........................................................18 2.1.3 compareTo.......................................................18 2.1.4 getBaseName.....................................................18 2.1.5 getByteValues...................................................19 2.1.6 getByteValueArray...............................................19 2.1.7 getLangSubtype..................................................19 2.1.8 getName.........................................................19 2.1.9 getStringValueArray.............................................19 2.1.10 getStringValues................................................20 2.1.11 getSubtypes....................................................20 2.1.12 hasSubtype.....................................................20 2.1.13 hasSubtypes....................................................20 2.1.14 removeValue....................................................21 2.1.15 size...........................................................21 2.2 public class LDAPAttributeSchema..................................21 2.2.1 Constructors....................................................21 2.2.2 getEqualityMatchingRule.........................................23 2.2.3 getOrderingMatchingRule.........................................23 2.2.4 getSubstringMatchingRule........................................23 2.2.5 getSuperior.....................................................23 2.2.6 getSyntaxString.................................................23 2.2.7 getUsage........................................................23 2.2.8 isCollective....................................................24 2.2.9 isSingleValued..................................................24 2.2.10 isUserModifiable...............................................24 2.2.11 Constants of LDAPAttributeSchema...............................24 2.3 public class LDAPAttributeSet.....................................25 2.3.1 Constructors....................................................25 2.3.2 clone...........................................................25 2.3.3 getAttribute....................................................25 2.3.4 getSubset.......................................................26 2.4 public interface LDAPAuthHandler..................................27 2.4.1 getAuthProvider.................................................27 2.5 public class LDAPAuthProvider.....................................27 2.5.1 Constructors....................................................28 2.5.2 getDN...........................................................28 2.5.3 getPassword.....................................................28 2.6 public interface LDAPBindHandler..................................28 2.6.1 bind............................................................28 2.7 public class LDAPCompareAttrNames.................................29 Expires January 2003 [Page 2] JAVA LDAP API July 2002 2.7.1 Constructors....................................................29 2.7.2 compare.........................................................30 2.7.3 equals..........................................................30 2.7.4 getLocale.......................................................31 2.7.5 setLocale.......................................................31 2.8 public class LDAPConnection.......................................31 2.8.1 Constructors....................................................31 2.8.2 abandon.........................................................32 2.8.3 add.............................................................33 2.8.4 addUnsolicitedNotificationListener..............................33 2.8.5 bind............................................................34 2.8.6 clone...........................................................36 2.8.7 compare.........................................................37 2.8.8 connect.........................................................38 2.8.9 delete..........................................................39 2.8.10 disconnect.....................................................39 2.8.11 extendedOperation..............................................40 2.8.12 fetchSchema....................................................41 2.8.13 finalize.......................................................41 2.8.14 getAuthenticationDN............................................41 2.8.15 getAuthenticationMethod........................................41 2.8.16 getConstraints.................................................42 2.8.17 getHost........................................................42 2.8.18 getPort........................................................42 2.8.19 getProperty....................................................42 2.8.20 getProtocolVersion.............................................43 2.8.21 getResponseControls............................................43 2.8.22 getSaslBindCallbackHandler.....................................43 2.8.23 getSaslBindProperties..........................................44 2.8.24 getSchemaDN....................................................44 2.8.25 getSearchConstraints...........................................44 2.8.26 getSocketFactory...............................................45 2.8.27 isBound........................................................45 2.8.28 isConnected....................................................45 2.8.29 isTLS..........................................................45 2.8.30 modify.........................................................45 2.8.31 read...........................................................47 2.8.32 removeUnsolicitedNotificationListener..........................48 2.8.33 rename.........................................................48 2.8.34 search.........................................................50 2.8.35 setConstraints.................................................52 2.8.36 setSocketFactory...............................................52 2.8.37 startTLS.......................................................53 2.8.38 stopTLS........................................................53 2.8.39 Constants of LDAPConnection....................................54 2.9 public class LDAPConstraints......................................54 2.9.1 Constructors....................................................54 2.9.2 getControls.....................................................55 2.9.3 getHopLimit.....................................................55 2.9.4 getProperty.....................................................55 2.9.5 getReferralFollowing............................................56 2.9.6 getTimeLimit....................................................56 Expires January 2003 [Page 3] JAVA LDAP API July 2002 2.9.7 setControls.....................................................56 2.9.8 setHopLimit.....................................................56 2.9.9 setProperty.....................................................56 2.9.10 setReferralFollowing...........................................57 2.9.11 setReferralHandler.............................................57 2.9.12 setTimeLimit...................................................57 2.10 public class LDAPControl.........................................58 2.10.1 Constructors...................................................58 2.10.2 clone..........................................................58 2.10.3 getID..........................................................58 2.10.4 getValue.......................................................58 2.10.5 isCritical.....................................................59 2.10.6 register.......................................................59 2.10.7 setValue.......................................................59 2.11 public class LDAPDITContentRuleSchema............................59 2.11.1 Constructors...................................................59 2.11.2 getAuxiliaryClasses............................................61 2.11.3 getOptionalAttributes..........................................61 2.11.4 getPrecludedAttributes.........................................61 2.11.5 getRequiredAttributes..........................................61 2.12 public class LDAPDITStructureRuleSchema..........................61 2.12.1 Constructors...................................................61 2.12.2 getNameForm....................................................62 2.12.3 getRuleID......................................................62 2.12.4 getSuperiors...................................................63 2.13 public class LDAPDN..............................................63 2.13.1 equals.........................................................63 2.13.2 escapeRDN......................................................63 2.13.3 explodeDN......................................................63 2.13.4 explodeRDN.....................................................64 2.13.5 isValid........................................................64 2.13.6 normalize......................................................64 2.13.7 unescapeRDN....................................................65 2.14 public class LDAPEntry...........................................65 2.14.1 Constructors...................................................65 2.14.2 compareTo......................................................66 2.14.3 getAttribute...................................................66 2.14.4 getAttributeSet................................................66 2.14.5 getDN..........................................................67 2.15 public class LDAPException.......................................67 2.15.1 Constructors...................................................67 2.15.2 getCause.......................................................68 2.15.3 getLDAPErrorMessage............................................68 2.15.4 getResultCode..................................................68 2.15.5 getMatchedDN...................................................69 2.15.6 resultCodeToString.............................................69 2.15.7 toString.......................................................70 2.15.8 Result codes...................................................70 2.16 public class LDAPExtendedOperation...............................71 2.16.1 Constructors...................................................71 2.16.2 getID..........................................................71 2.16.3 getValue.......................................................72 Expires January 2003 [Page 4] JAVA LDAP API July 2002 2.16.4 setValue.......................................................72 2.17 public class LDAPExtendedResponse................................72 2.17.1 getID..........................................................72 2.17.2 getValue.......................................................72 2.17.3 register.......................................................72 2.18 public class LDAPLocalException..................................73 2.18.1 Constructors...................................................73 2.19 public class LDAPMatchingRuleSchema..............................74 2.19.1 Constructors...................................................74 2.19.2 getAttributes..................................................75 2.19.3 getSyntaxString................................................75 2.20 public class LDAPMatchingRuleUseSchema...........................75 2.20.1 Constructors...................................................75 2.20.2 getAttributes..................................................76 2.21 public class LDAPMessage.........................................76 2.21.1 getControls....................................................76 2.21.2 getMessageID...................................................76 2.21.3 getType........................................................77 2.22 public interface LDAPMessageQueue................................77 2.22.1 getMessageIDs..................................................77 2.22.2 getResponse....................................................77 2.22.3 isResponseReceived.............................................78 2.22.4 merge..........................................................78 2.23 public class LDAPModification....................................79 2.23.1 Constructors...................................................79 2.23.2 getAttribute...................................................79 2.23.3 getOp..........................................................80 2.23.4 Constants of LDAPModification..................................80 2.24 public class LDAPNameFormSchema..................................80 2.24.1 Constructors...................................................80 2.24.2 getObjectClass.................................................81 2.24.3 getOptionalNamingAttributes....................................81 2.24.4 getRequiredNamingAttributes....................................81 2.25 public class LDAPObjectClassSchema...............................82 2.25.1 Constructors...................................................82 2.25.2 getOptionalAttributes..........................................83 2.25.3 getRequiredAttributes..........................................83 2.25.4 getSuperiors...................................................83 2.25.5 getType........................................................83 2.25.6 Constants of LDAPObjectClassSchema.............................83 2.26 public class LDAPReferralException...............................83 2.26.1 Constructors...................................................84 2.26.2 getFailedReferral..............................................84 2.26.3 getReferrals...................................................85 2.26.4 setFailedReferral..............................................85 2.27 public interface LDAPReferralHandler.............................85 2.28 public class LDAPResponse........................................85 2.28.1 getErrorMessage................................................85 2.28.2 getMatchedDN...................................................85 2.28.3 getReferrals...................................................85 2.28.4 getResultCode..................................................86 2.29 public class LDAPResponseQueue...................................86 Expires January 2003 [Page 5] JAVA LDAP API July 2002 2.29.1 getMessageIDs..................................................86 2.29.2 getResponse....................................................86 2.29.3 isResponseReceived.............................................87 2.29.4 merge..........................................................87 2.30 public class LDAPSchema..........................................87 2.30.1 Constructors...................................................87 2.30.2 getAttributeNames..............................................88 2.30.3 getAttributeSchema.............................................88 2.30.4 getAttributeSchemas............................................88 2.30.5 getDITContentRuleNames.........................................88 2.30.6 getDITContentRuleSchema........................................88 2.30.7 getDITContentRuleSchemas.......................................88 2.30.8 getDITStructureRuleNames.......................................89 2.30.9 getDITStructureRuleSchema......................................89 2.30.10 getDITStructureRuleSchemas....................................89 2.30.11 getMatchingRuleNames..........................................89 2.30.12 getMatchingRuleSchema.........................................89 2.30.13 getMatchingRuleSchemas........................................90 2.30.14 getMatchingRuleUseNames.......................................90 2.30.15 getMatchingRuleUseSchema......................................90 2.30.16 getMatchingRuleUseSchemas.....................................90 2.30.17 getNameFormNames..............................................90 2.30.18 getNameFormSchema.............................................90 2.30.19 getNameFormSchemas............................................91 2.30.20 getObjectClassNames...........................................91 2.30.21 getObjectClassSchema..........................................91 2.30.22 getObjectClassSchemas.........................................91 2.30.23 getSyntaxSchema...............................................91 2.30.24 getSyntaxSchemas..............................................91 2.31 public abstract class LDAPSchemaElement..........................92 2.31.1 getDescription.................................................92 2.31.2 getNames.......................................................92 2.31.3 getID..........................................................92 2.31.4 getQualifier...................................................92 2.31.5 getQualifierNames..............................................93 2.31.6 isObsolete.....................................................93 2.31.7 setQualifier...................................................93 2.31.8 toString.......................................................93 2.32 public class LDAPSearchConstraints...............................93 2.32.1 Constructors...................................................93 2.32.2 getBatchSize...................................................95 2.32.3 getDereference.................................................95 2.32.4 getMaxResults..................................................95 2.32.5 getServerTimeLimit.............................................95 2.32.6 setBatchSize...................................................96 2.32.7 setDereference.................................................96 2.32.8 setMaxResults..................................................96 2.32.9 setServerTimeLimit.............................................96 2.32.10 Constants of LDAPSearchConstraints............................96 2.33 public class LDAPSearchQueue.....................................97 2.33.1 getMessageIDs..................................................97 2.33.2 getResponse....................................................97 Expires January 2003 [Page 6] JAVA LDAP API July 2002 2.33.3 isComplete.....................................................98 2.33.4 isResponseReceived.............................................98 2.33.5 merge..........................................................98 2.34 public class LDAPSearchResult....................................99 2.34.1 getEntry.......................................................99 2.35 public class LDAPSearchResultReference...........................99 2.35.1 getReferrals...................................................99 2.36 public class LDAPSearchResults...................................99 2.36.1 getCount.......................................................99 2.36.2 getResponseControls............................................99 2.36.3 hasMore.......................................................100 2.36.4 next..........................................................100 2.37 public interface LDAPSocketFactory..............................100 2.37.1 createSocket..................................................100 2.38 public class LDAPSyntaxSchema...................................100 2.38.1 Constructors..................................................101 2.39 public interface LDAPTLSSocketFactory extends LDAPSocketFactory.101 2.39.1 createSocket..................................................101 2.40 public interface LDAPUnsolicitedNotificationListener............101 2.40.1 messageReceived...............................................102 2.41 public class LDAPUrl............................................102 2.41.1 Constructors..................................................102 2.41.2 decode........................................................103 2.41.3 encode........................................................103 2.41.4 getAttributeArray.............................................104 2.41.5 getAttributes.................................................104 2.41.6 getDN.........................................................104 2.41.7 getExtensions.................................................104 2.41.8 getFilter.....................................................104 2.41.9 getHost.......................................................104 2.41.10 getPort......................................................105 2.41.11 getScope.....................................................105 2.41.12 toString.....................................................105 3. Implementation considerations.....................................105 3.1 Controls.........................................................105 3.2 Referral handling and exceptions.................................106 3.3 Message IDs......................................................107 3.4 Notice of disconnection..........................................108 3.5 Level of compatibility...........................................108 3.6 Dependencies.....................................................108 3.7 Invalid responses................................................108 4. Security considerations...........................................108 5. Acknowledgements..................................................109 6. Bibliography......................................................109 6.1 Normative References.............................................109 6.2 Informative References...........................................110 7. Authors' addresses................................................110 8. Appendix A - Sample Java LDAP programs............................112 8.1 Java LDAP programs using synchronous methods.....................112 8.2 Java LDAP programs using asynchronous methods....................118 9. Appendix B - Revision history.....................................123 9.1 Changes from ldap-java-api-17.txt................................123 Expires January 2003 [Page 7] JAVA LDAP API July 2002 9.2 Changes from ldap-java-api-16.txt................................124 9.3 Changes from ldap-java-api-15.txt................................124 9.4 Changes from ldap-java-api-14.txt................................128 9.5 Changes from ldap-java-api-13.txt................................129 9.6 Changes from ldap-java-api-12.txt................................131 9.7 Changes from ldap-java-api-11.txt................................132 9.8 Changes from ldap-java-api-10.txt................................135 9.9 Changes from ldap-java-api-09.txt................................135 9.10 Changes from ldap-java-api-08.txt...............................136 9.11 Changes from ldap-java-api-07.txt...............................137 9.12 Changes from ldap-java-api-06.txt...............................137 9.13 Changes from ldap-java-api-05.txt...............................138 9.14 Changes from ldap-java-api-04.txt...............................139 9.15 Changes from ldap-java-api-03.txt...............................139 9.16 Changes from ldap-java-api-02.txt...............................140 9.17 Changes from ldap-java-api-01.txt...............................140 Expires January 2003 [Page 8] JAVA LDAP API July 2002 1. Overview The LDAP [LDAPv3] class library is designed to provide powerful, yet simple, access to LDAP directory services. It defines both asynchronous and synchronous interfaces to LDAP to suit a wide variety of applications. This document gives a brief overview of the LDAP model, then an overview of the constituents of the class library. The public class methods are described in detail, followed by an appendix that provides some example code demonstrating the use of the classes, and an appendix listing changes from earlier drafts. 1.1 The LDAP model LDAP is the Lightweight Directory Access Protocol, described in [LDAPv3]. It defines a lightweight access mechanism in which clients send requests to and receive responses from LDAP servers. The LDAP information model comes from X.500 [X500] and is based on the entry, which contains information about some object (e.g., a person). Entries are composed of attributes, which have a type and one or more values. Each attribute has a syntax that determines what kinds of values are allowed in the attribute (e.g., ASCII characters, a jpeg photograph, etc.) and how directory operations act upon these values. Entries may be organized in a tree structure, usually based on political, geographical, and organizational boundaries. Other structures are possible, including a flat namespace. Each entry is uniquely named relative to its sibling entries by its relative distinguished name (RDN) consisting of one or more distinguished attribute values from the entry. At most one value from each attribute may be used in the RDN. For example, the entry for the person Babs Jensen might be named with the "Barbara Jensen" value from the cn attribute. A globally unique name for an entry, called a distinguished name or DN, is constructed by concatenating the sequence of RDNs from the entry up to the root of the tree. For example, if Babs worked for the Example company, the DN of her entry might be "cn=Barbara Jensen,dc=example,dc=com". The DN format used by LDAP is defined in [DN]. Operations are provided to authenticate, search for and retrieve information, modify information, and add and delete entries from the tree. The protocol is also extensible, allowing operations to be extended by "controls" and new "extended" operations to be defined. Expires January 2003 [Page 9] JAVA LDAP API July 2002 An LDAP server may return referrals or search references 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 server may return a referral. If a search request spans multiple servers, it may return one or more search references). The LDAP class library presents a unified interface for the application to process search references and referrals, and generically refers to either in the remainder of this document as simply referrals or referral following. The API gives the programmer two options to handle referrals: the application can receive the referrals and explicitly issue new requests to the referred-to servers, or the application can let the library automatically follow the referrals. In the latter case referrals are followed by default with anonymous credentials using the protocol version and socket factory or TLS [TLS][LDAPTLS] of the original connection. If default behavior is not desired, the application can instruct the library to follow referrals with an authenticated connection by providing a reauthentication object to provide credentials for a simple bind. For greater flexibility, the application can provide an object that creates and manages the new authenticated connection for the API to use when following the referral. Before the client encodes and sends a string value to a server, the string values are converted from the Java 16-bit Unicode format to UTF-8 format, which many LDAPv3 protocol elements and value encodings use. The integrity of double-byte and other non-ASCII character sets is fully preserved. If in the future there are characters added to Unicode which cannot be represented with Java 16- bit Unicode strings, implementations of the Java LDAP API SHOULD adopt whatever conventions are introduced into the Java language to accommodate the characters. The next sections give an overview of how the class library is used and detailed descriptions of the LDAP class methods that implement all of these functions. 1.2 Package name The classes of the LDAP class library have the package name org.ietf.ldap. 1.3 The LDAP classes The central LDAP class is LDAPConnection. It provides methods to establish an authenticated or anonymous connection to an LDAP server, as well as methods to search for, modify, compare, and delete entries in the directory, and establish integrity and confidentiality protective services. The LDAPConnection class also provides access to settings that are specific to the LDAP session (such as limits on the number of results Expires January 2003 [Page 10] JAVA LDAP API July 2002 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. 1.4 The LDAP asynchronous methods The LDAP protocol provides synchronous as well as asynchronous directory access methods. All asynchronous methods return queue objects (either LDAPResponseQueue or LDAPSearchQueue) and also take a queue object as input. The queue is a message queue associated with the request, and it is the responsibility of the client to read messages out of the queue and process them. Messages retrieved from an LDAPResponseQueue are result objects derived from LDAPResponse. Messages retrieved from an LDAPSearchQueue are either search results, search result references, or result objects derived from LDAPResponse. An asynchronous search is conducted by an LDAPConnection object and returns an LDAPSearchQueue object. Search results are obtained from that object via the getResponse method. A search result is typically an LDAPSearchResult object, which has a getEntry method. The LDAPEntry returned by getEntry contains the DN and attributes of a single search result. None of the ancillary asynchronous classes are intended to be instantiated by a client, so they lack public constructors. 1.5 Interfaces LDAPAuthHandler A programmer desiring to supply credentials to the default reauthentication behavior when automatically following referrals MUST implement this interface. If LDAPAuthHandler or LDAPBindHandler are not used, automatically followed referrals and search references will use anonymous authentication. Referrals of any type other than LDAP URLs [LDAPURL] MAY be chased on automatic referral following. Expires January 2003 [Page 11] JAVA LDAP API July 2002 LDAPBindHandler This interface allows a programmer to override the default authentication and reauthentication behavior when automatically following referrals and search references. It is used to specify the authentication mechanism used on automatic referral following. LDAPMessageQueue Common interface for LDAPResponseQueue and LDAPSearchQueue. Represents a queue of incoming asynchronous messages from the server. LDAPReferralHandler Interface that is a shared ancestor to LDAPBindHandler and LDAPAuthHandler. LDAPSocketFactory Programmers needing to provide or use specialized socket connections can provide an object constructor to implement them using this interface. LDAPTLSSocketFactory An extension of LDAPSocketFactory that supports socket connections with Transport Layer Security (TLS). LDAPUnsolicitedNotificationListener Allows a client to be notified when unsolicited messages arrive from a server. Unsolicited messages have a message ID of 0. An implementation of the Java LDAP API SHOULD NOT generate messages with an ID of 0. 1.6 Classes LDAPAttribute Represents the name and values of one attribute of a directory entry. LDAPAttributeSchema Represents a definition of an attribute in a Directory Server. LDAPAttributeSet A collection of LDAPAttributes. Expires January 2003 [Page 12] JAVA LDAP API July 2002 LDAPAuthProvider An implementation of LDAPAuthHandler MUST be able to provide an LDAPAuthProvider at the time of a referral. The class encapsulates reauthentication credentials. LDAPCompareAttrNames An implementation of Comparator, 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 on the directory. LDAPControl Encapsulates additional parameters for an LDAP operation, sent to or received from a server. LDAPDITContentRuleSchema Represents a DIT content rule in a directory schema. LDAPDITStructureRuleSchema Represents a DIT structure rule in a directory schema. LDAPDN A utility class to facilitate composition and decomposition of distinguished names (DNs). LDAPEntry Represents a single entry in a directory. LDAPExtendedOperation Encapsulates the OID and data associated with the sending or receiving of an extended operation. LDAPExtendedResponse The response returned by an LDAP server on an extended operation request. It extends LDAPResponse. Expires January 2003 [Page 13] JAVA LDAP API July 2002 LDAPMatchingRuleSchema Represents the schematic definition of a matching rule in a Directory Server. LDAPMatchingRuleUseSchema Represents a 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. LDAPNameFormSchema Represents a name form in a directory schema. LDAPObjectClassSchema Represents the schematic definition of an object class in a Directory Server. LDAPResponse Represents a message received from an LDAP server in response to an asynchronous request. It extends LDAPMessage. LDAPExtendedResponse extends LDAPResponse and is returned also on a synchronous extended request. LDAPResponseQueue Mechanism for processing asynchronous messages received from a server. LDAPSchema Represents the schema controlling one or more entries held by a Directory Server. LDAPSchemaElement Base class for representing LDAP schema elements. LDAPSyntaxSchema Represents a syntax definition in a directory schema. LDAPSearchConstraints Defines the options controlling search operations. Expires January 2003 [Page 14] JAVA LDAP API July 2002 LDAPSearchQueue Mechanism for queuing asynchronous search results received from a server. LDAPSearchResult A single search result that is in response to an asynchronous search operation. It extends LDAPMessage. LDAPSearchResultReference A continuation reference from an asynchronous search operation. It extends LDAPMessage. LDAPSearchResults The enumerable results of a search operation. LDAPUrl Represents an LDAP Url [LDAPURL]. 1.7 Exceptions LDAPException General exception, which includes an error message and an LDAP API local error code or server result code. LDAPLocalException An exception generated by the API implementation, not received from the server. LDAPReferralException Derived from LDAPException and contains a list of URLs corresponding to a single referral or search continuation response received on an LDAP operation. 1.8 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. Expires January 2003 [Page 15] JAVA LDAP API July 2002 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 LDAPSearchQueue, 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 queue parameter (either LDAPResponseQueue or LDAPSearchQueue) and return a queue object which is used to enumerate the responses from the server. A loop is typically used to read from the queue object, which blocks until there is a response available, until the operation has completed. An LDAPResponseQueue may be shared between operations, for multiplexing the results. In this case, the object returned on one operation is passed in to one or more other operations, rather than passing in null. For the asynchronous methods, exceptions are raised only for connection errors. LDAP result messages are converted into LDAPResponse objects which are to be checked by the client for errors and referrals, whereas the synchronous methods throw an LDAPException on result codes other than 0, 5, and 6. To facilitate user feedback during synchronous searches, intermediate search results can be obtained before the entire search operation is completed by specifying the number of entries to return at a time. Errors result in the throwing of an LDAPException, with a specific result code and context-specific textual information, if available. Methods that return arrays MUST return an empty array if no values are present to return, unless otherwise specified. 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 Expires January 2003 [Page 16] JAVA LDAP API July 2002 is thread-safe. Other classes and methods MAY be thread-safe and the implementor MUST indicate which classes and methods are thread-safe. The following sections describe the LDAP classes in more detail. 2. The Java LDAP classes 2.1 public class LDAPAttribute implements Cloneable, Serializable, Comparable The LDAPAttribute class represents the name and values of an attribute. It is used to specify an attribute to be added to, deleted from, or modified in a Directory entry. It is also returned on a search of a Directory. 2.1.1 Constructors public LDAPAttribute(LDAPAttribute attr) Constructs an attribute with copies of all values of the input attribute. public LDAPAttribute(String attrName) Constructs an attribute with no values. public LDAPAttribute(String attrName, byte[] attrBytes) Constructs an attribute with a byte-formatted value. public LDAPAttribute(String attrName, String attrString) Constructs an attribute that has a single string value. public LDAPAttribute(String attrName, String[] attrStrings) Constructs an attribute that has an array of string values. Parameters are: Expires January 2003 [Page 17] JAVA LDAP API July 2002 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. IllegalArgumentException is thrown if any of the attribute values is null. 2.1.2 addValue public void addValue(String attrString) Adds a string value to the attribute. public void addValue(byte[] attrBytes) Adds a byte[]-formatted value to the attribute. Parameters are: attrString Value of the attribute as a String. attrBytes Value of the attribute as raw bytes. Adding a value which is already present has no effect. 2.1.3 compareTo public int compareTo(Object obj) Compares this object with the specified object for order. Ordering is determined by comparing attribute names (see getName()) using the compareTo() method of the String class. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. Parameters are: obj The object to be compared to this object. 2.1.4 getBaseName public String getBaseName() Expires January 2003 [Page 18] JAVA LDAP API July 2002 public static String getBaseName(String attrName) Returns the base name. For example, if the attribute name is cn;lang- ja;phonetic, this method returns cn. attrName Name of the attribute to extract the base name from. 2.1.5 getByteValues public Enumeration getByteValues() Returns an enumerator for the values of the attribute in byte[] format. 2.1.6 getByteValueArray public byte[][] getByteValueArray() Returns the values of the attribute as an array of byte[]. 2.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. 2.1.8 getName public String getName() Returns the name of the attribute. 2.1.9 getStringValueArray public String[] getStringValueArray() Returns the values of the attribute as an array of Strings. This method should only be called if the attribute values are known to be strings with values restricted to UTF-8. The returned Strings have undefined values if the attribute contains values not restricted to UTF-8. Expires January 2003 [Page 19] JAVA LDAP API July 2002 2.1.10 getStringValues public Enumeration getStringValues() Returns an enumerator for the string values of an attribute. This method should only be called if the attribute values are known to be strings with values restricted to UTF-8. The returned Strings have undefined values if the attribute contains values not restricted to UTF-8. 2.1.11 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. 2.1.12 hasSubtype public boolean hasSubtype(String subtype) Reports if the attribute name contains the specified subtype. For example, if you check for the subtype lang-en and the attribute name is cn;lang-en, this method returns true. Parameters are: subtype The single subtype to check for. 2.1.13 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 January 2003 [Page 20] JAVA LDAP API July 2002 subtypes An array of subtypes to check for. 2.1.14 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. Removing a value which is not present in the attribute has no effect. 2.1.15 size public int size() Returns the number of values of the attribute. 2.2 public class LDAPAttributeSchema extends LDAPSchemaElement The LDAPAttributeSchema class represents the definition of an attribute. It is used to query attribute syntax, and to add or delete an attribute definition in a Directory. See [ATTR] for a description of attribute representation in LDAP. 2.2.1 Constructors public LDAPAttributeSchema(String[] names, String oid, String description, String syntaxString, boolean single, String superior, boolean obsolete, String equality, String ordering, String substring, boolean collective, Expires January 2003 [Page 21] JAVA LDAP API July 2002 boolean userMod, int usage) Constructs an attribute definition for adding to or deleting from a Directory. [LDAPv3] defines which parameters are optional (may be null). public LDAPAttributeSchema(String raw) Constructs an attribute definition from an encoding using the AttributeTypeDescription syntax [ATTR]. Parameters are: names Name(s) of the attribute. oid Object Identifier of the attribute - in dotted- decimal format. description Optional description of the attribute. syntaxString Object Identifier of the syntax of the attribute - in dotted-decimal format. single true if the attribute is to be single-valued. superior Optional name of the attribute type which this attribute type derives from; null if there is no superior attribute type. obsolete true if this attribute is obsolete. equality Object Identifier of the equality matching rule for the attribute - in dotted-decimal format; MAY be null. ordering Object Identifier of the ordering matching rule for the attribute - in dotted-decimal format; MAY be null. substring Object Identifier of the substring matching rule for the attribute - in dotted-decimal format; MAY be null. collective true if this is a collective attribute. userMod true if the attribute is modifiable by users. usage One of the following: Expires January 2003 [Page 22] JAVA LDAP API July 2002 USER_APPLICATIONS DIRECTORY_OPERATION DISTRIBUTED_OPERATION DSA_OPERATION raw An attribute definition encoded using the AttributeTypeDescription syntax [ATTR]. 2.2.2 getEqualityMatchingRule public String getEqualityMatchingRule () Returns the Object Identifier of the equality matching rule in effect for this attribute, or null if there is none. 2.2.3 getOrderingMatchingRule public String getOrderingMatchingRule () Returns the Object Identifier of the ordering matching rule in effect for this attribute, or null if there is none. 2.2.4 getSubstringMatchingRule public String getSubstringMatchingRule () Returns the Object Identifier of the substring matching rule in effect for this attribute, or null if there is none. 2.2.5 getSuperior public String getSuperior() Returns the name of the attribute type which this attribute derives from, or null if there is no superior attribute. 2.2.6 getSyntaxString public String getSyntaxString() Returns the Object Identifier of the syntax of the attribute in dotted-decimal format. 2.2.7 getUsage Expires January 2003 [Page 23] JAVA LDAP API July 2002 public int getUsage () Returns one of the following: USER_APPLICATIONS DIRECTORY_OPERATION DISTRIBUTED_OPERATION DSA_OPERATION 2.2.8 isCollective public boolean isCollective () Returns true if the attribute is collective. 2.2.9 isSingleValued public boolean isSingleValued() Returns true if the attribute is single-valued. 2.2.10 isUserModifiable public boolean isUserModifiable () Returns true if the attribute is modifiable by users. 2.2.11 Constants of LDAPAttributeSchema The constants correspond to those defined in RFC 2252 [ATTR]: userApplications, directoryOperation, distributedOperation, and dSAOperation. USER_APPLICATIONS (0) An ordinary user attribute DIRECTORY_OPERATION (1) An operational attribute used for a directory operation or which holds a directory specific value DISTRIBUTED_OPERATION (2) An operational attribute used to hold server (DSA) information that is shared among servers holding replicas of the entry DSA_OPERATION (3) An operational attribute used to hold server (DSA) information that is local to a server Expires January 2003 [Page 24] JAVA LDAP API July 2002 2.3 public class LDAPAttributeSet implements Cloneable, Serializable, Set 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. If add() or addAll() is called and one or more of the objects to be added is not an LDAPAttribute, ClassCastException is thrown (as discussed in the documentation for java.util.Collection). remove() is called with the LDAPAttribute object to remove, rather than the name of the attribute to remove. 2.3.1 Constructors public LDAPAttributeSet() Constructs a new set of attributes. This set is initially empty. 2.3.2 clone public Object clone() Returns a deep copy of this attribute set. 2.3.3 getAttribute public LDAPAttribute getAttribute(String attrName) Returns the attribute matching the specified attrName. For example, getAttribute("cn") returns only the "cn" attribute getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute. In both cases, null is returned if there is no exact match to the specified attrName. public LDAPAttribute getAttribute(String attrName, String lang) Returns a single best-match attribute, or none if no match is available in the set. 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 Expires January 2003 [Page 25] JAVA LDAP API July 2002 among localizations, only the base attribute may be stored, whereas for others there may be varying degrees of specialization. getAttribute(attrName, lang) returns the subtype that matches attrName and that best matches lang. If there are subtypes other than "lang" subtypes included in attrName, e.g. "cn;binary", only attributes with all of those subtypes are returned. If lang is null or empty, the method behaves as getAttribute(attrName). If there are no matching attributes, null is returned. If the results are ambiguous, the exception UnsupportedOperationException is thrown. Example: Assume the entry contains only the following attributes: cn;lang-en cn;lang-ja-JP-kanji sn getAttribute( "cn" ) returns null. getAttribute( "sn" ) returns the "sn" attribute. getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute. getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute. getAttribute( "cn", "lang-ja" ) returns null. getAttribute( "sn", "lang-en" ) returns the "sn" attribute. Parameters are: attrName The name of an attribute to retrieve, with or without subtype specification(s). "cn", "cn;phonetic", and cn;binary" are valid attribute names. lang A language specification as in [LANG], with optional subtypes appended using "-" as separator. "lang-en", "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are valid language specification. 2.3.4 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: Expires January 2003 [Page 26] JAVA LDAP API July 2002 cn cn;lang-ja sn;lang-ja;phonetic sn;lang-us Calling the getSubset method and passing lang-ja as the argument, the method returns an attribute set containing the following attributes: cn;lang-ja sn;lang-ja;phonetic Parameters are: subtype - Semi-colon delimited list of subtypes to include. For example: "lang-ja" // Only Japanese language // subtypes "binary" // Only binary subtypes "binary;lang-ja" // Only Japanese language // subtypes which also are binary 2.4 public interface LDAPAuthHandler extends LDAPReferralHandler Used to provide credentials for reauthentication on processing a referral. 2.4.1 getAuthProvider public LDAPAuthProvider getAuthProvider(String host, int port) Returns an object which can provide credentials for authenticating to a server at the provided host name and port number. Parameters are: host Contains a host identifier representing the IP address of a host running an LDAP server. See 2.8.8 for a discussion of valid identifiers. port Contains the TCP port number to connect to. 2.5 public class LDAPAuthProvider Represents information used to authenticate the client in cases where the client follows referrals automatically. Expires January 2003 [Page 27] JAVA LDAP API July 2002 2.5.1 Constructors public LDAPAuthProvider( String dn, byte[] password ) Constructs information that is used by the client for authentication when following referrals automatically. Parameters are: dn Distinguished name to use in authenticating to the server. password The UTF-8 or binary representation of the password to use in authenticating to the server, represented as a byte array. 2.5.2 getDN public String getDN() Returns the distinguished name to be used for reauthentication on automatic referral following. 2.5.3 getPassword public byte[] getPassword() Returns the password to be used for reauthentication on automatic referral following. 2.6 public interface LDAPBindHandler extends LDAPReferralHandler Used to do explicit bind processing on a referral. A client may specify an instance of this class to be used on a single operation (through an LDAPConstraints object) or for all operations (through the LDAPConstraints object associated with the connection). 2.6.1 bind public LDAPConnection bind(String[] ldapurl, LDAPConnection conn) throws LDAPReferralException Expires January 2003 [Page 28] JAVA LDAP API July 2002 This method is called by LDAPConnection when a referral or search continuation is received, and is responsible for binding to one of the hosts in the list specified by the ldapurl parameter (which corresponds exactly to the list of hosts returned in a single referral or search continuation response). An implementation may access the host, port, credentials, and other information in the original LDAPConnection object to decide on an appropriate authentication mechanism, and/or may interact with a user or external module. The object implementing LDAPBindHandler creates a new LDAPConnection object to perform its connect and bind calls. It returns the new connection when both the connect and bind operations succeed on one host from the list. The LDAPConnection object referral following code uses the new LDAPConnection object when it resends the search request, updated with the new search base and possibly search filter. An LDAPReferralException is thrown on failure. Parameters are: ldapurl List of LDAP server URLs. There is no order implied by the list. conn An established connection to an LDAP server. 2.7 public class LDAPCompareAttrNames implements Comparator An object of this class defines ordering when sorting search results. When using this Comparator, LDAPEntry objects are sorted by the values of the attribute name(s) passed in the constructor, in ascending or descending order. The object is typically supplied to an implementation of the collection interfaces such as java.util.TreeSet which performs the sort. 2.7.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) Expires January 2003 [Page 29] JAVA LDAP API July 2002 Constructs an object that will sort by one or more attributes, in the order provided, in ascending order. public LDAPCompareAttrNames(String[] attrNames, boolean[] ascendingFlags) throws LDAPException Constructs an object that will sort by one or more attributes, in the order provided, in either ascending or descending order for each attribute. Parameters are: attrName Name of an attribute to sort by. attrNames Array of names of attributes to sort by. 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 equal to the length of attrNames. 2.7.2 compare public int compare(Object o1, Object o2) Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. Throws ClassCastException if o1 or o2 is not an LDAPEntry. Parameters are: o1 Target entry for comparison. o2 Entry to be compared to. 2.7.3 equals public boolean equals(Object obj) Indicates whether some other object is "equal to" this Comparator. Parameters are: Expires January 2003 [Page 30] JAVA LDAP API July 2002 obj The reference object with which to compare. 2.7.4 getLocale public Locale getLocale() Returns the Locale to be used for sorting, if a Locale has been specified. If null, a basic String.compareTo() is used for collation. If non-null, a Locale-specific collation is used. 2.7.5 setLocale public void setLocale(Locale locale) Sets the Locale to be used for sorting. Parameters are: locale The Locale to be used for sorting. 2.8 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. 2.8.1 Constructors public LDAPConnection() Constructs a new LDAPConnection object, which represents a connection to an LDAP server. Calling the constructor does not actually establish the connection. The connect or bind methods are used to connect to the LDAP server. public LDAPConnection(LDAPSocketFactory factory) Constructs a new LDAPConnection object, which will use the supplied class factory to construct a socket connection during Expires January 2003 [Page 31] JAVA LDAP API July 2002 LDAPConnection.connect(). If a security manager exists and the caller does not have permission to set a factory, SecurityException is thrown. Parameters are: factory An object capable of producing a Socket. 2.8.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(LDAPMessageQueue queue) throws LDAPException public void abandon(LDAPMessageQueue queue, 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 queue. The application is responsible for not calling this method more than once with a particular id or LDAPSearchResults. An API implementation MUST ignore abandon requests for an id or LDAPSearchResults which it does not recognize. It SHOULD NOT send an additional abandon request if it can determine that one has already been sent for an id or LDAPSearchResults. Parameters are: results An object returned from a search. id The ID of the asynchronous operation to abandon. The ID may be obtained from the response queue for the operation. Expires January 2003 [Page 32] JAVA LDAP API July 2002 queue Handler returned from an asynchronous request. All outstanding operations that are managed by the queue are abandoned. cons Constraints specific to the operation. 2.8.3 add public void add(LDAPEntry entry) throws LDAPException public void add(LDAPEntry entry, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue add(LDAPEntry entry, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue add(LDAPEntry entry, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Adds an entry to the directory. The application is responsible for specifying attribute values which are valid according to the syntax defined for the attributes. It is also responsible for including all attributes which are required for the entry. Parameters are: entry LDAPEntry object specifying the distinguished name and attributes of the new entry. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. 2.8.4 addUnsolicitedNotificationListener public void addUnsolicitedNotificationListener( LDAPUnsolicitedNotificationListener listener) Registers an object to be notified on arrival of an unsolicited message from a server. Expires January 2003 [Page 33] JAVA LDAP API July 2002 Parameters are: listener An object to be notified on arrival of an unsolicited message from a server. 2.8.5 bind public void bind(int version, String dn, byte[] passwd) throws LDAPException public void bind(int version, String dn, byte[] passwd, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue bind(int version, String dn, byte[] passwd, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue bind(int version, String dn, byte[] passwd, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Authenticates to the LDAP server (that the object is currently connected to) using the specified name and password, with the specified LDAP protocol version. This API is specifically designed for use with LDAPv3. Unless the API provides specific support (as defined in other documents) for other versions of LDAP, version 3 should be used. If the server does not support the requested protocol version, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded. Parameters are: version LDAP protocol version requested: currently 3. Expires January 2003 [Page 34] JAVA LDAP API July 2002 dn If non-null and non-empty, specifies that the connection and all operations through it MUST be authenticated with dn as the distinguished name. passwd The UTF-8 or binary representation of the password to use in authenticating to the server, represented as a byte array. If non-null and non- empty, specifies that the connection and all operations through it MUST be authenticated with dn as the distinguished name and passwd as password. If dn and/or password is null or empty, the connection is anonymous on completion of the simple bind request. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. public void bind(String dn, String authzId, Map props, javax.security.auth.callback.CallbackHandler cbh) throws LDAPException public void bind(String dn, String authzId, Map props, javax.security.auth.callback.CallbackHandler cbh, LDAPConstraints cons) throws LDAPException public void bind(String dn, String authzId, String[] mechanisms, Map props, javax.security.auth.callback.CallbackHandler cbh) throws LDAPException public void bind(String dn, String authzId, String[] mechanisms, Map props, javax.security.auth.callback.CallbackHandler cbh, LDAPConstraints cons) throws LDAPException Expires January 2003 [Page 35] JAVA LDAP API July 2002 Authenticates to the LDAP server (that the object is currently connected to) using the specified name and one of a specified set of mechanisms. If none of the requested SASL [SASL][AUTH][JAVASASL] mechanisms is available, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded. A SASL bind call may involve multiple protocol requests. An attempt to invoke an operation other than bind between bind requests in a multi-stage bind results in an LDAPException with the result code SASL_BIND_IN_PROGRESS. Parameters are: dn The distinguished name to use as the bind name. It may be null or empty. This value is not used as either a SASL authentication nor authorization identity. The application provides these identities through the callback handler. authzId If not null and not empty, an LDAP authzID [AUTH] to be passed to the SASL layer. If null or empty, the authzId will be treated as an empty string and processed as per RFC 2222 [SASL]. 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 SASL client implementation to obtain additional information required, such as additional credentials. cons Constraints specific to the operation. 2.8.6 clone public Object clone() Returns a copy of the object with a private context, but sharing the network connection if there is one. The network connection remains open until all clones have disconnected or gone out of scope. Any connection opened after cloning is private to the object making the connection. The clone can freely modify options and search constraints, and issue requests, without affecting the source object or other clones. If the clone disconnects or reconnects, it is completely dissociated from the source object and other clones. Reauthenticating in a clone, however, is a global operation which will affect the source object Expires January 2003 [Page 36] JAVA LDAP API July 2002 and all associated clones, because it applies to the single shared physical connection. Any request by an associated object after one has reauthenticated will carry the new identity. Methods that are global in nature and which affect the source object are: addUnsolicitedNotificationListener bind connect disconnect finalize removeUnsolicitedNotificationListener startTLS The following methods return data that is from the source object and is the same for all clones of LDAPConnection: getAuthenticationDN getAuthenticationMethod getHost getPort getProtocolVersion getSaslBindCallBackHandler getSaslBindProperties getSocketFactory isBound isConnected isTLS The following methods manipulate or retrieve data that is unique to each clone of LDAPConnection: getConstraints getResponseControls getSearchConstraints setConstraints 2.8.7 compare public boolean compare(String dn, LDAPAttribute attr) throws LDAPException public boolean compare(String dn, LDAPAttribute attr, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue compare(String dn, LDAPAttribute attr, Expires January 2003 [Page 37] JAVA LDAP API July 2002 LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue compare(String dn, LDAPAttribute attr, LDAPResponseQueue queue, 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. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. 2.8.8 connect public void connect(String host, int port) throws LDAPException Connects to the specified host and port. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. At this point there is no authentication, and any operations will be conducted as an anonymous client. Parameters are: host Contains a host identifier consisting of a hostname, an IPv4 dotted string, or an IPv6 reference [IPv6] representing the IP address of a host running an LDAP server to connect to. Alternatively, it may contain a list of host identifiers, space-delimited. Each host identifier may include a trailing colon and port Expires January 2003 [Page 38] JAVA LDAP API July 2002 number. IPv6 identifiers with a port number are represented with square brackets around the IP address part as per [IPv6URL]. In the case where more than one host identifier is specified, each host identifier in turn will be contacted until a connection can be established. Examples: "directory.example.com" "192.0.2.0" "[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:4389" "directory.example.com:1050 people.catalog.com 192.0.2.0" port Port number for LDAP server (use LDAPConnection.DEFAULT_PORT for default port). "port" is ignored for any host identifier which includes a colon and port number. 2.8.9 delete public void delete(String dn) throws LDAPException public void delete(String dn, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue delete(String dn, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue delete(String dn, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Deletes the entry for the specified DN from the directory. Parameters are: dn Distinguished name of the entry to delete. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. 2.8.10 disconnect public void disconnect() throws LDAPException Expires January 2003 [Page 39] JAVA LDAP API July 2002 public void disconnect(LDAPConstraints cons) throws LDAPException Disassociates the LDAPConnection object from clones and any physical connection to an LDAP server. If the object is the last clone sharing a physical connection, the method closes the connection with the LDAP server. The API implementation sends an Unbind request to the server with any controls specified by the LDAPConstraints object before closing the connection. Before the object can perform LDAP operations again, it MUST reconnect to the server by calling either connect or bind (bind will attempt to reconnect). Parameters are: cons Constraints to be sent with the unbind request. 2.8.11 extendedOperation public LDAPExtendedResponse extendedOperation( LDAPExtendedOperation op ) throws LDAPException public LDAPExtendedResponse extendedOperation( LDAPExtendedOperation op, LDAPConstraints cons ) throws LDAPException public LDAPResponseQueue extendedOperation( LDAPExtendedOperation op, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue extendedOperation( LDAPExtendedOperation op, LDAPConstraints cons, LDAPResponseQueue queue) throws LDAPException Provides a means to access extended, non-mandatory operations offered by a particular LDAP version 3 compliant server. Returns an operation-specific object, containing an OID and an Octet String or BER-encoded value(s). Parameters are: op Object which contains an object identifier of the extended operation, which SHOULD be one recognized by the particular server this client Expires January 2003 [Page 40] JAVA LDAP API July 2002 is connected to, and operation-specific sequence of Octet String or BER-encoded value(s). cons Constraints specific to the operation. 2.8.12 fetchSchema public LDAPSchema fetchSchema(String schemaDN) throws LDAPException Retrieves the schema associated with a particular schema DN in the Directory server. The schema DN for a particular entry is obtained by calling the getSchemaDN method of LDAPConnection. An LDAPException is thrown if the schema cannot be retrieved. Parameters are: schemaDN The schema DN used to fetch the schema. 2.8.13 finalize protected void finalize() throws LDAPException Closes the connection if open and releases any other resources held by the object. 2.8.14 getAuthenticationDN public String getAuthenticationDN() Returns the distinguished name (DN) used as the bind name during the last successful bind operation. null is returned if no authentication has been performed or if the bind resulted in an anonymous connection. 2.8.15 getAuthenticationMethod public String getAuthenticationMethod() Returns the method used to authenticate the connection. The return value is one of the following: "none" The current authentication state has not been established by use of the bind operation. This is the initial state upon connect() as well as if the last bind failed or if the last successful bind was anonymous. Expires January 2003 [Page 41] JAVA LDAP API July 2002 "simple" Simple bind has completed successfully (anonymous, unauthenticated, or authenticated) "sasl" The current authentication state was established by the successful completion of a SASL bind 2.8.16 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). If no constraints have been assigned with setConstraints, a copy of the default constraints is returned. 2.8.17 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. If no connection attempt has been made, null is returned. 2.8.18 getPort public int getPort() Returns the port number of the LDAP server to which the object is or was last connected. If no connection attempt has been made, LDAPConnection.DEFAULT_PORT is returned. 2.8.19 getProperty public Object getProperty(String name) Gets a property of a connection object. The properties are defined by the API implementation and not modifiable by a client of the API. Parameters are: name Name of the property to be returned. The following read-only properties are available for any given connection: Expires January 2003 [Page 42] JAVA LDAP API July 2002 LDAP_PROPERTY_SDK ("version.sdk") The version of this SDK, as a String data type. LDAP_PROPERTY_PROTOCOL ("version.protocol") The highest supported version of the LDAP protocol, as an Integer data type. LDAP_PROPERTY_SECURITY ("security.types") A comma-separated list of the types of authentication supported, as a String. See 2.8.15. Other properties may be available in particular implementations of the class. A deep copy of the property is provided where applicable; a client does not need to clone the object received. null is returned if the requested property is not available. 2.8.20 getProtocolVersion public int getProtocolVersion () Returns the protocol version that the connection is bound to (which currently is 3). If the connection is not bound, it returns 3. 2.8.21 getResponseControls public LDAPControl[] getResponseControls() Returns the latest Server Controls returned by a Directory Server with a response to an LDAP request from the current thread. For asynchronous requests, the response controls are available in LDAPMessage instead. 2.8.22 getSaslBindCallbackHandler public javax.security.auth.callback.CallbackHandler getSaslBindCallbackHandler() Expires January 2003 [Page 43] JAVA LDAP API July 2002 Returns the callback handler, if any, specified on binding with a SASL mechanism. 2.8.23 getSaslBindProperties public Map getSaslBindProperties() Returns the properties, if any, specified on binding with a SASL mechanism. 2.8.24 getSchemaDN public String getSchemaDN() throws LDAPException Retrieves the DN for the schema at the root DSE of the Directory Server. Throws LDAPException if the schema DN cannot be retrieved, or if the subschemaSubentry attribute associated with the root DSE contains multiple values. public String getSchemaDN(String dn) throws LDAPException Retrieves the DN of the schema associated with a particular entry in the directory. Throws LDAPException if the schema DN cannot be retrieved, or if a null or empty value is passed as dn and the subschemaSubentry attribute associated with the root DSE contains multiple values. Parameters are: dn Distinguished name of the entry for which the schema DN is to be retrieved. 2.8.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(). If no constraints have been assigned with setConstraints, a copy of the default constraints is returned. Expires January 2003 [Page 44] JAVA LDAP API July 2002 2.8.26 getSocketFactory public LDAPSocketFactory getSocketFactory() Returns the LDAPSocketFactory used to establish a connection to a server. 2.8.27 isBound public boolean isBound() Indicates whether the object has authenticated to the connected LDAP server (other than anonymously with simple bind). It returns false initially, false upon a bind request, and true after successful completion of the last outstanding non-anonymous simple bind. 2.8.28 isConnected public boolean isConnected() Indicates if the connection represented by this object is open at this time. 2.8.29 isTLS public boolean isTLS () Indicates the session is currently protected by TLS. The method provides no indication of the level of protection provided. 2.8.30 modify public void modify(String dn, LDAPModification mod) throws LDAPException public void modify(String dn, LDAPModification mod, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue modify(String dn, LDAPModification mod, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue modify(String dn, LDAPModification mod, Expires January 2003 [Page 45] JAVA LDAP API July 2002 LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Makes a single change to an existing entry in the directory (for example, changes the value of an attribute, adds a new attribute value, or removes an existing attribute value). The LDAPModification object specifies both the change to be made and the LDAPAttribute value to be changed. The application is responsible for specifying attribute values which are valid according to the syntax defined for the attributes. public void modify(String dn, LDAPModification[] mods) throws LDAPException public void modify(String dn, LDAPModification[] mods, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue modify(String dn, LDAPModification[] mods, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue modify(String dn, LDAPModification[] mods, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Makes a set of changes to an existing entry in the directory (for example, changes attribute values, adds new attribute values, or removes existing attribute values). The application is responsible for specifying attribute values which are valid according to the syntax defined for the attributes. Parameters are: dn Distinguished name of the entry to modify. mod A single change to be made to the entry. mods A set of changes to be made to the entry. Expires January 2003 [Page 46] JAVA LDAP API July 2002 queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. 2.8.31 read public LDAPEntry read(String dn) throws LDAPException Reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry. public LDAPEntry read(String dn, LDAPSearchConstraints cons) throws LDAPException Reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry. public LDAPEntry read(String dn, String[] attrs) throws LDAPException public LDAPEntry read(String dn, String[] attrs, LDAPSearchConstraints cons) throws LDAPException Reads the entry for the specified distinguished name (DN) and retrieves only the specified attributes from the entry. public static LDAPEntry read(LDAPUrl toGet) throws LDAPException public static LDAPEntry read(LDAPUrl toGet, LDAPSearchConstraints cons) throws LDAPException Reads the entry specified by the LDAP URL. When this method is called, a new connection is created automatically, using the host and port specified in the URL. After finding the entry, the method closes the connection (in other words, it disconnects from the LDAP server). If the URL specifies a scope other than base, IllegalArgumentException is thrown. Any critical extensions specified Expires January 2003 [Page 47] JAVA LDAP API July 2002 in the URL must be processed or else an LDAPException is thrown with the result code UNSUPPORTED_OPERATION. The method returns the entry specified by the base DN. Parameters are: dn Distinguished name of the entry to retrieve. cons Constraints specific to the operation. attrs Names of attributes to retrieve. toGet LDAP URL specifying the entry to read. If the server does not return exactly one entry, an LDAPException is thrown with a result code of AMBIGIOUS_RESPONSE. Note: read is simply a helper method and uses the ldap search operation to achieve the results. As such, there is no asynchronous interface. 2.8.32 removeUnsolicitedNotificationListener public void removeUnsolicitedNotificationListener( LDAPUnsolicitedNotificationListener listener) Deregisters an object so that it will no longer be notified on arrival of an unsolicited message from a server. If the object is null or was not previously registered for unsolicited notifications, the method does nothing. Parameters are: listener An object to no longer be notified on arrival of an unsolicited message from a server. 2.8.33 rename public void rename(String dn, String newRdn, boolean deleteOldRdn) throws LDAPException public void rename(String dn, String newRdn, boolean deleteOldRdn, LDAPConstraints cons) Expires January 2003 [Page 48] JAVA LDAP API July 2002 throws LDAPException public LDAPResponseQueue rename(String dn, String newRdn, boolean deleteOldRdn, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue rename(String dn, String newRdn, boolean deleteOldRdn, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Renames an existing entry in the directory. public void rename(String dn, String newRdn, String newParentdn, boolean deleteOldRdn) throws LDAPException public void rename(String dn, String newRdn, String newParentdn, boolean deleteOldRdn, LDAPConstraints cons) throws LDAPException public LDAPResponseQueue rename(String dn, String newRdn, String newParentdn, boolean deleteOldRdn, LDAPResponseQueue queue) throws LDAPException public LDAPResponseQueue rename(String dn, String newRdn, String newParentdn, boolean deleteOldRdn, LDAPResponseQueue queue, LDAPConstraints cons) throws LDAPException Renames an existing entry or subtree in the directory, possibly repositioning it in the directory tree. Parameters are: dn Current distinguished name of the entry. Expires January 2003 [Page 49] JAVA LDAP API July 2002 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. If newParentdn is null, the request is treated as if the signature without newParentdn is called. deleteOldRdn If true, the old name is not retained as an attribute value. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the operation. 2.8.34 search public LDAPSearchResults search(String base, int scope, String filter, String[] attrs, boolean typesOnly) throws LDAPException public LDAPSearchQueue search(String base, int scope, String filter, String[] attrs, boolean typesOnly, LDAPSearchQueue queue) 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 LDAPSearchQueue search(String base, int scope, String filter, String[] attrs, boolean typesOnly, Expires January 2003 [Page 50] JAVA LDAP API July 2002 LDAPSearchQueue queue, 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 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 Expires January 2003 [Page 51] JAVA LDAP API July 2002 SCOPE_ONE Search only entries directly 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 [FILTER]. The value null can be passed to indicate that the filter "(objectclass=*)" which matches all entries is to be used. attrs Names of attributes to retrieve. typesOnly If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found. toGet LDAP URL specifying the entry to read. queue Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally. cons Constraints specific to the search. Note: RFC 2251 [LDAPv3] indicates that extendedResponses on search requests may be defined in future versions of the LDAP protocol. There is no support for extendedResponses on search requests in this version of the Java LDAP API. 2.8.35 setConstraints public void setConstraints(LDAPConstraints cons) Sets the constraints that apply to all operations performed through this connection (unless a different set of constraints is specified when calling an operation method). An LDAPSearchConstraints object which is passed to this method will override all constraints, while an LDAPConstraints object will only affect the base constraints. Parameters are: cons Non-null constraints object. 2.8.36 setSocketFactory public static void setSocketFactory(LDAPSocketFactory factory) Expires January 2003 [Page 52] JAVA LDAP API July 2002 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. If a security manager exists and the caller does not have permission to set a factory, SecurityException is thrown. To use the setSocketFactory method, the caller needs the following permission: java.lang.RuntimePermission("setFactory"); Parameters are: factory A factory object which can construct socket connections for an LDAPConnection. If null, the default factory of the API implementation is selected. 2.8.37 startTLS public void startTLS() throws LDAPException Begin using the Transport Layer Security (TLS) protocol for session privacy [TLS][LDAPTLS]. 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 returned by the server. If there are outstanding LDAP operations on the connection, an LDAPException is thrown. 2.8.38 stopTLS public void stopTLS () throws LDAPException Stop using the Transport Layer Security (TLS) protocol for session privacy [LDAPTLS]. If the server does not support the termination of a TLS session, an LDAPException is thrown with the error code returned by the server. If there are outstanding LDAP operations on the connection, an LDAPException is thrown. Expires January 2003 [Page 53] JAVA LDAP API July 2002 2.8.39 Constants of LDAPConnection ALL_USER_ATTRS ("*") Used with search in an attribute list to indicate that all attributes (other than operational attributes) are to be returned. NO_ATTRS ("1.1") Used with search instead of an attribute list to indicate that no attributes are to be returned. DEFAULT_PORT (389) Used on connect to indicate the default LDAP port number. SCOPE_BASE (0) Used with search to indicate that only the entry corresponding to the base DN is to be returned. SCOPE_ONE (1) Used with search to indicate that only immediate subordinates of the entry corresponding to the base DN, and not the entry corresponding to the base DN, are to be returned. SCOPE_SUB (2) Used with search to indicate that the entry corresponding to the base DN as well as all direct and indirect subordinate entries are to be returned. 2.9 public class LDAPConstraints implements Cloneable, Serializable A set of options to control any operation. There is always an LDAPConstraints associated with an LDAPConnection object; its values can be changed with LDAPConnection.setConstraints, or overridden by passing an LDAPConstraints object to an operation. 2.9.1 Constructors public LDAPConstraints() Constructs an LDAPConstraints object that specifies the default set of constraints. public LDAPConstraints(int msLimit, boolean doReferrals, LDAPReferralHandler handler, int hop_limit) Constructs a new LDAPConstraints object and allows specifying the operational constraints in that object. Expires January 2003 [Page 54] JAVA LDAP API July 2002 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. handler 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 LDAPBindHandler or the LDAPAuthHandler interface. It is ignored for asynchronous operations. hop_limit Maximum number of referrals to follow in a sequence when attempting to resolve a request, when doing automatic referral following. It is ignored for asynchronous operations. 2.9.2 getControls public LDAPControl[] getControls() Returns controls to be sent to the server. 2.9.3 getHopLimit public int getHopLimit() Returns the maximum number of hops to follow during automatic referral following. 2.9.4 getProperty public Object getProperty(String name) Gets a property of a constraints object which has been assigned with setProperty. null is returned if the property is not defined. Parameters are: Expires January 2003 [Page 55] JAVA LDAP API July 2002 name Name of the property to be returned. 2.9.5 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. 2.9.6 getTimeLimit public int getTimeLimit() Returns the maximum number of milliseconds the client waits for any operation under these constraints. If 0, there is no maximum time limit on waiting for the operation results. The actual granularity of the timeout depends on the implementation. 2.9.7 setControls public void setControls( LDAPControl control ) public void setControls( LDAPControl[] controls ) Sets controls to be sent to the server. Parameters are: control A single control to be sent to the server. controls An array of controls to be sent to the server. 2.9.8 setHopLimit public void setHopLimit(int hop_limit) Sets the maximum number of hops to follow in sequence during automatic referral following. The default is 10. 0 means no limit. Parameters are: hop_limit Maximum number of chained referrals to follow automatically. 2.9.9 setProperty Expires January 2003 [Page 56] JAVA LDAP API July 2002 public void setProperty(String name, Object value) Sets a property of the constraints 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 and proprietary extensions to operation modifiers. Throws IllegalArgumentException if the property name is not defined in the API. Parameters are: name Name of the property to set. value Value to assign to the property. 2.9.10 setReferralFollowing public void setReferralFollowing(boolean doReferrals) Specifies whether nor not referrals are followed automatically, or if referrals throw an LDAPReferralException. The default is false. Parameters are: doReferrals True to follow referrals automatically. 2.9.11 setReferralHandler public void setReferralHandler (LDAPReferralHandler handler) Specifies the object that will process authentication requests. The default is null. Parameters are: handler An object that implements LDAPBindHandler or LDAPAuthHandler. 2.9.12 setTimeLimit public void setTimeLimit(int msLimit) Sets the maximum number of milliseconds to wait for any operation under these constraints. If 0, there is no maximum time limit on waiting for the operation results. The actual granularity of the time limit depends on the implementation. Parameters are: Expires January 2003 [Page 57] JAVA LDAP API July 2002 msLimit Maximum milliseconds to wait. 2.10 public class LDAPControl implements Serializable, Cloneable An LDAPControl encapsulates optional additional parameters or constraints to be applied to LDAP operations. When included with LDAPConstraints or LDAPSearchConstraints on an LDAPConnection or on a specific operation request, it is sent to the server along with operation requests. 2.10.1 Constructors public LDAPControl(String oid, boolean critical, byte[] value) Parameters are: oid The type of the Control, as an OID. critical If true, the LDAP operation will fail with UNAVAILABLE_CRITICAL_EXTENSION if the server does not support this Control. value Control-specific data. The API implementation does not interpret or convert the value. 2.10.2 clone public Object clone() Returns a deep copy of the object. 2.10.3 getID public String getID() Returns the object identifier of the control. 2.10.4 getValue public byte[] getValue() Returns the control-specific data of the object. Expires January 2003 [Page 58] JAVA LDAP API July 2002 2.10.5 isCritical public boolean isCritical() Returns true if the control must be supported for an associated operation to be executed. 2.10.6 register public static void register(String oid, Class controlClass) Registers a class to be instantiated on receipt of a control with the given oid. Any previous registration for the oid is overridden. The controlClass MUST be an extension of LDAPControl. Parameters are: oid The Object Identifier of the Control. controlClass A class which can instantiate an LDAPControl. 2.10.7 setValue protected void setValue(byte[] value) Sets the control-specific data of the object. This method is for use by extensions of LDAPControl. Parameters are: value The value to be assigned to the Control. 2.11 public class LDAPDITContentRuleSchema extends LDAPSchemaElement The LDAPDITContentRuleSchema class represents the definition of a DIT Content Rule. It is used to discover or modify additional auxiliary classes, mandatory and optional attributes, and restricted attributes in effect for an object class. See [ATTR] for a description of DIT content rule representation in LDAP. 2.11.1 Constructors public LDAPDITContentRuleSchema(String[] names, String oid, String description, boolean obsolete, String[] auxiliary, Expires January 2003 [Page 59] JAVA LDAP API July 2002 String[] required, String[] optional, String[] precluded) Constructs a DIT content rule for adding to or deleting from the schema. [LDAPv3] defines which parameters are optional (may be null). public LDAPDITContentRuleSchema(String raw) Constructs a DIT content rule from an encoding using the ditContentRules syntax [ATTR]. Parameters are: names Name(s) of the content rule. oid Object Identifier of the content rule - in dotted-decimal format. description Optional description of the content rule. obsolete true if the content rule is obsolete. auxiliary A list of auxiliary object classes allowed for an entry to which this content rule applies. These may either be specified by name or numeric oid. required A list of user attribute types that an entry to which this content rule applies must contain in addition to its normal set of mandatory attributes. These may either be specified by name or numeric oid. optional A list of user attribute types that an entry to which this content rule applies may contain in addition to its normal set of optional attributes. These may either be specified by name or numeric oid. precluded A list, consisting of a subset of the optional user attribute types of the structural and auxiliary object classes which are precluded from an entry to which this content rule applies. These may either be specified by name or numeric oid. raw A DIT content rule encoded using the ditContentRules syntax [ATTR]. Expires January 2003 [Page 60] JAVA LDAP API July 2002 2.11.2 getAuxiliaryClasses public String[] getAuxiliaryClasses() Returns the list of allowed auxiliary classes. 2.11.3 getOptionalAttributes public String[] getOptionalAttributes() Returns the list of additional optional attributes for an entry controlled by this content rule. 2.11.4 getPrecludedAttributes public String[] getPrecludedAttributes() Returns the list of precluded attributes for an entry controlled by this content rule. 2.11.5 getRequiredAttributes public String[] getRequiredAttributes() Returns the list of additional required attributes for an entry controlled by this content rule. 2.12 public class LDAPDITStructureRuleSchema extends LDAPSchemaElement The LDAPDITStructureRuleSchema class represents the definition of a DIT Structure Rule. It is used to discover or modify which object classes a particular object class may be subordinate to in the DIT. See [ATTR] for a description of DIT structure rule representation in LDAP. 2.12.1 Constructors public LDAPDITStructureRuleSchema(String[] names, int ruleID, String description, boolean obsolete, String nameForm, String[] superiorIDs) Constructs a DIT structure rule for adding to or deleting from the schema. [LDAPv3] defines which parameters are optional (may be null). Expires January 2003 [Page 61] JAVA LDAP API July 2002 public LDAPDITStructureRuleSchema(String raw) Constructs a DIT structure rule from an encoding using the dITStructureRules syntax [ATTR]. Parameters are: names Name(s) of the structure rule. ruleID Unique identifier of the structure rule. NOTE: this is an integer, not a dotted-decimal identifier. Structure rules aren't identified by OID. description Optional description of the structure rule. obsolete true if the structure rule is obsolete. nameForm Either the object identifier in dotted-decimal form or the name of a name form. This is used to indirectly refer to the object class that this structure rule applies to. superiorIDs List of superior structure rules - specified by their integer ID. The object class specified by this structure rule (via the nameForm parameter) may only be subordinate in the DIT to object classes of those represented by the structure rules here; MAY be null. raw A DIT structure rule encoded using the dITStructureRules syntax [ATTR]. 2.12.2 getNameForm public String getNameForm() Returns the NameForm that this structure rule controls. You can get the actual object class that this structure rule controls by calling getNameForm(ditStructRule.getNameForm()).getObjectClass(). 2.12.3 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. Expires January 2003 [Page 62] JAVA LDAP API July 2002 2.12.4 getSuperiors public String[] getSuperiors() Returns a list of all structure rules that are superior to this structure rule. To resolve to an object class, you need to first resolve the superior id to another structure rule, then call getNameForm().getObjectClass() on that structure rule. 2.13 public class LDAPDN A utility class used to manipulate a distinguished name (DN). 2.13.1 equals public static boolean equals(String dn1, String dn2) Compares the two strings per the distinguishedNameMatch matching rule [ATTR]. An API implementation MUST use caseIgnoreMatch equality matching for the attributes listed in section 2 of [ATTR]. IllegalArgumentException is thrown if one or both DNs are invalid. UnsupportedOperationException is thrown if the API implementation is not able to determine if the DNs match or not. Parameters are: dn1 String form of first DN to compare. dn2 String form of second DN to compare. 2.13.2 escapeRDN public static String escapeRDN(String rdn) Returns the RDN after escaping the characters requiring escaping [DN]. For example, for the rdn "cn=Example, Inc", "cn=Example\, Inc" is returned. Parameters are: rdn The RDN to escape. 2.13.3 explodeDN public static String[] explodeDN(String dn, boolean noTypes) Returns the individual components of a distinguished name (DN). Expires January 2003 [Page 63] JAVA LDAP API July 2002 Parameters are: dn Distinguished name, e.g. "cn=Babs Jensen,ou=Accounting,dc=example,dc=com" noTypes If true, returns only the values of the components, and not the names, e.g. "Babs Jensen", "Accounting", "Example", "com" - instead of "cn=Babs Jensen","ou=Accounting","dc=Example", and "dc=com". 2.13.4 explodeRDN public static String[] explodeRDN(String rdn, boolean noTypes) Returns the individual components of a relative distinguished name (RDN). Parameters are: rdn Relative distinguished name, i.e. the left-most component of a distinguished name. noTypes If true, returns only the values of the components, and not the names. 2.13.5 isValid public static boolean isValid(String dn) Returns true if the string conforms to distinguished name syntax (section 3 of [DN]. It MAY return true also if the string conforms to section 4 of [DN]. Parameters are: dn String to evaluate for distinguished name syntax. 2.13.6 normalize public static String normalize(String dn) Returns the DN normalized by removal of non-significant space characters as per RFC 2253, section 4 [DN]. Parameters are: dn The DN to normalize. Expires January 2003 [Page 64] JAVA LDAP API July 2002 2.13.7 unescapeRDN public static String unescapeRDN(String rdn) Returns the RDN after unescaping the characters requiring escaping [DN]. For example, for the rdn "cn=Example\, Inc", "cn=Example, Inc" is returned. IllegalArgumentException is thrown if the RDN cannot be parsed. Parameters are: rdn The RDN to unescape. 2.14 public class LDAPEntry implements Serializable, Comparable An LDAPEntry represents a single entry in a directory, consisting of a distinguished name (DN) and zero or more attributes. An instance of LDAPEntry is created in order to add an entry to a Directory, and instances are returned on a search by either enumerating an LDAPSearchResults, or calling LDAPSearchResult.getEntry. 2.14.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 name will cause adding of the entry to a directory to fail. Expires January 2003 [Page 65] JAVA LDAP API July 2002 attrs The initial set of attributes assigned to the entry. 2.14.2 compareTo public int compareTo(Object obj) Compares this object with the specified object for order. Ordering is determined by comparing normalized DN values (see LDAPEntry.getDN() and LDAPDN.normalize()) using the compareTo() method of the String class. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. Parameters are: obj The object to be compared to this object. 2.14.3 getAttribute public LDAPAttribute getAttribute(String attrName) Returns a copy of the attribute matching the specified attrName. Parameters are: attrName The name of the attribute. See 2.3.3 for the syntax and semantics relevant to this parameter. 2.14.4 getAttributeSet public LDAPAttributeSet getAttributeSet() Returns a copy of the attribute set of the entry. Copies of 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 copies 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 Expires January 2003 [Page 66] JAVA LDAP API July 2002 returned may be empty if there are no matching attributes in the entry. Parameters are: subtype One or more subtype specification(s), separated with semicolons. "lang-ja" and "lang-en;phonetic" are valid subtype specifications. 2.14.5 getDN public String getDN() Returns the distinguished name of the entry. 2.15 public class LDAPException extends Exception Thrown to indicate that an error has occurred. An LDAPException can result from physical problems (such as network errors) as well as problems with LDAP operations (for example, if the LDAP add operation fails because an entry already exists with the DN of the entry to be added) or local errors in the API implementation. Most errors that occur throw this type of exception. The getLDAPResultCode() method returns the specific result code. 2.15.1 Constructors public LDAPException() Constructs a default exception with no specific error information. public LDAPException(String message, int resultCode, String serverMessage) Constructs an exception with a result code, specified string as additional information, and optionally a message from the server. public LDAPException(String message, int resultCode, String serverMessage, Throwable rootException) Expires January 2003 [Page 67] JAVA LDAP API July 2002 Constructs an exception with a result code, a specified string, an optional message from the server, and an embedded root exception as additional information. public LDAPException(String message, int resultCode, String serverMessage, String matchedDN) Constructs an exception with a result code, a specified string as additional information, an optional message from the server, 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 serverMessage Error message specifying additional information from the server. matchedDN The DN of the most immediate ancestor of a specified search DN which could be found by the server on a search operation rootException An exception which caused the failure, if any 2.15.2 getCause public Throwable getCause() Returns the lower level Exception which caused the failure, if any. For example, an IOException with additional information MAY be returned on a CONNECT_ERROR failure. 2.15.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. 2.15.4 getResultCode public int getResultCode() Expires January 2003 [Page 68] JAVA LDAP API July 2002 Returns the result code from the exception. The codes are defined as public final static int members of this class. If the exception is a result of error information returned from a directory operation, the code will be one of those defined in [LDAPv3]. Otherwise, a local error code is returned (see "Result codes" below). 2.15.5 getMatchedDN public String getMatchedDN() Returns the matchedDN value provided by the server in the response which generated this exception (it may be empty). If the exception is not due to a server response, null is returned. 2.15.6 resultCodeToString public String resultCodeToString() Returns a String representing the result code in the default Locale. public static String resultCodeToString( int code ) Returns a String representing the specified result code in the default Locale, or null if there is no such code known to the API. public String resultCodeToString( Locale locale ) Returns a String representing the result code in the specified Locale, or null if a String representation is not available for the requested Locale. public static String resultCodeToString( int code, Locale locale ) Returns a String representing the specified result code in the specified Locale, or null if there is no such code or if a String representation is not available for the requested Locale. Parameters are: code One of the result codes listed in "Result codes" below. locale A Locale in which to render the String. Expires January 2003 [Page 69] JAVA LDAP API July 2002 2.15.7 toString public String toString() Overrides the default toString implementation. It expands all the nested exceptions. 2.15.8 Result codes See [LDAPv3] for a discussion of the meanings and values of the codes. The corresponding ASN.1 name from [LDAPv3] is provided in parentheses. ADMIN_LIMIT_EXCEEDED (adminLimitExceeded) AFFECTS_MULTIPLE_DSAS (affectsMultipleDSAs) ALIAS_DEREFERENCING_PROBLEM (aliasDereferencingProblem) ALIAS_PROBLEM (aliasProblem) ATTRIBUTE_OR_VALUE_EXISTS (attributeOrValueExists) AUTH_METHOD_NOT_SUPPORTED (authMethodNotSupported) BUSY (busy) COMPARE_FALSE (compareFalse) COMPARE_TRUE (compareTrue) CONFIDENTIALITY_REQUIRED (confidentialityRequired) CONSTRAINT_VIOLATION (constraintViolation) ENTRY_ALREADY_EXISTS (entryAlreadyExists) INAPPROPRIATE_AUTHENTICATION (inappropriateAuthentication) INAPPROPRIATE_MATCHING (inappropriateMatching) INSUFFICIENT_ACCESS_RIGHTS (insufficientAccessRights) INVALID_ATTRIBUTE_SYNTAX (invalidAttributeSyntax) INVALID_CREDENTIALS (invalidCredentials) INVALID_DN_SYNTAX (invalidDNSyntax) IS_LEAF (isLeaf) LOOP_DETECT (loopDetect) NAMING_VIOLATION (namingViolation) NO_SUCH_ATTRIBUTE (noSuchAttribute) NO_SUCH_OBJECT (noSuchObject) NOT_ALLOWED_ON_NONLEAF (notAllowedOnNonLeaf) NOT_ALLOWED_ON_RDN (notAllowedOnRDN) OBJECT_CLASS_MODS_PROHIBITED (objectClassModsProhibited) OBJECT_CLASS_VIOLATION (objectClassViolation) OPERATIONS_ERROR (operationsError) OTHER (other) PROTOCOL_ERROR (protocolError) REFERRAL (referral) SASL_BIND_IN_PROGRESS (saslBindInProgress) SIZE_LIMIT_EXCEEDED (sizeLimitExceeded) STRONG_AUTH_REQUIRED (strongAuthRequired) SUCCESS (success) TIME_LIMIT_EXCEEDED (timeLimitExceeded) UNAVAILABLE (unavailable) UNAVAILABLE_CRITICAL_EXTENSION (unavailableCriticalExtension) Expires January 2003 [Page 70] JAVA LDAP API July 2002 UNDEFINED_ATTRIBUTE_TYPE (undefinedAttributeType) UNWILLING_TO_PERFORM (unwillingToPerform) Local errors, resulting from actions other than an operation on a server, are among the following: AMBIGUOUS_RESPONSE (0x65) AUTH_UNKNOWN (0x56) CLIENT_LOOP (0x60) CONNECT_ERROR (0x5b) CONTROL_NOT_FOUND (0x5d) DECODING_ERROR (0x54) ENCODING_ERROR (0x53) FILTER_ERROR (0x57) INVALID_RESPONSE (0x64) LOCAL_ERROR (0x52) LDAP_NOT_SUPPORTED (0x5c) LDAP_TIMEOUT (0x55) MORE_RESULTS_TO_RETURN (0x5f) NO_MEMORY (0x5a) NO_RESULTS_RETURNED (0x5e) REFERRAL_LIMIT_EXCEEDED (0x61) SERVER_DOWN (0x51) USER_CANCELLED (0x58) TLS_NOT_SUPPORTED (0x70) 2.16 public class LDAPExtendedOperation implements Cloneable, Serializable An LDAPExtendedOperation encapsulates an OID which uniquely identifies a particular extended operation, known to a particular server, and the data associated with the operation. 2.16.1 Constructors public LDAPExtendedOperation(String oid, byte[] value) Constructs a new object with the specified object ID and data. Parameters are: oid The object identifier of the operation. value The operation-specific data of the operation. 2.16.2 getID public String getID() Expires January 2003 [Page 71] JAVA LDAP API July 2002 Returns the object identifier of the operation. 2.16.3 getValue public byte[] getValue() Returns the operation-specific data (not a copy, a reference). 2.16.4 setValue protected void setValue(byte[] value) Sets the operation-specific data of the object. This method is for use by extensions of LDAPExtendedOperation. Parameters are: value The value to be assigned to the object (as a reference) 2.17 public class LDAPExtendedResponse extends LDAPResponse An LDAPExtendedResponse object encapsulates a server response to an extended operation request. 2.17.1 getID public String getID() Returns the OID of the response. 2.17.2 getValue public byte[] getValue() Returns the raw bytes of the value part of the response. 2.17.3 register public static void register(String oid, Class extendedResponseClass) Registers a class to be instantiated on receipt of an extended response with the given oid. Any previous registration for the oid is Expires January 2003 [Page 72] JAVA LDAP API July 2002 overridden. The extendedResponseClass object MUST be an extension of LDAPExtendedResponse. Parameters are: oid The Object Identifier of the extended response extendedResponseClass A class which can instantiate an LDAPExtendedResponse. The class must implement the following constructor signature: public (String oid, byte[] value) oid The Object Identifier of the extended response value Response-specific data; the API implementation does not interpret or convert the value 2.18 public class LDAPLocalException extends LDAPException Thrown to indicate that a local error has occurred in the API implementation, for example a physical problem such as a network error. 2.18.1 Constructors public LDAPLocalException() Constructs a default exception with no specific error information. public LDAPLocalException(String message, int resultCode) Constructs an exception with a result code and a string as additional information. public LDAPException(String message, int resultCode, Throwable rootException) Constructs an exception with a result code, a specified string, and an embedded root exception as additional information. Expires January 2003 [Page 73] JAVA LDAP API July 2002 Parameters are: message The additional error information resultCode The result code returned rootException An exception which caused the failure, if any 2.19 public class LDAPMatchingRuleSchema extends LDAPSchemaElement The LDAPMatchingRuleSchema class represents the definition of a matching rule. It is used to query matching rule syntax, and to add or delete a matching rule definition in a Directory. See [ATTR] for a description of matching rule representation in LDAP. 2.19.1 Constructors public LDAPMatchingRuleSchema(String[] names, String oid, String description, String[] attributes, boolean obsolete, String syntaxString) Constructs a matching rule definition for adding to or deleting from a Directory. [LDAPv3] defines which parameters are optional (may be null). public LDAPMatchingRuleSchema(String rawMatchingRule, String rawMatchingRuleUse) Constructs a matching rule definition from values encoded using the matchingRule syntax and the matchingRuleUse syntax [ATTR] for the same rule. Parameters are: name Name of the attribute. oid Object Identifier of the attribute - in dotted-decimal format. description Optional description of the attribute. attributes OIDs of attributes to which the rule applies. The parameter MAY be null. Expires January 2003 [Page 74] JAVA LDAP API July 2002 obsolete true if this matching rule is obsolete. syntaxString Object Identifier of the syntax that this matching rule is valid for - in dotted-decimal format. rawMatchingRule A matching rule definition encoded using the matchingRule syntax [ATTR]. rawMatchingRuleUse A matching rule use definition encoded using the matchingRuleUse syntax [ATTR]. The parameter MAY be null. 2.19.2 getAttributes public String[] getAttributes() Returns the OIDs of the attributes to which this rule applies. 2.19.3 getSyntaxString public String getSyntaxString() Returns the OID of the syntax that this matching rule is valid for. 2.20 public class LDAPMatchingRuleUseSchema extends LDAPSchemaElement The LDAPMatchingRuleUseSchema class represents the definition of a matching rule use. It is used to discover or modify which attributes are suitable for use with an extensible matching rule. It contains the name and object identifier of a matching rule, and a list of attributes that it applies to. See [ATTR] for a description of matching rule use representation in LDAP. 2.20.1 Constructors public LDAPMatchingRuleUseSchema(String[] names, String oid, String description, boolean obsolete, String[] attributes) Constructs a matching rule use definition for adding to or deleting from the schema. [LDAPv3] defines which parameters are optional (may be null). Expires January 2003 [Page 75] JAVA LDAP API July 2002 public LDAPMatchingRuleUseSchema(String raw) Constructs a matching rule use definition from an encoding using the matchingRuleUse syntax [ATTR]. Parameters are: names Name(s) of the matching rule. oid Object Identifier of the matching rule - in dotted-decimal format. description Optional description of the matching rule use. obsolete true if the matching rule use is obsolete. attributes List of attributes that this matching rule applies to. These values may be either the names or numeric oids of the attributes raw A matching rule use definition using the matchingRuleUse syntax [ATTR]. 2.20.2 getAttributes public String[] getAttributes() Returns an array of all the attributes that this matching rule applies to. 2.21 public class LDAPMessage implements Serializable Base class for asynchronous LDAP request and response messages and for LDAPExtendedResponse. 2.21.1 getControls public LDAPControl[] getControls() Returns any controls in the message. 2.21.2 getMessageID public int getMessageID() Returns the message ID. Message IDs are defined in section 4.1.1.1 of [LDAPv3]. Expires January 2003 [Page 76] JAVA LDAP API July 2002 2.21.3 getType public int getType() Returns the LDAP operation type of the message. The type is one of the following: BIND_REQUEST (0x0) BIND_RESPONSE (0x1) UNBIND_REQUEST (0x2) SEARCH_REQUEST (0x3) SEARCH_RESPONSE (0x4) SEARCH_RESULT (0x5) MODIFY_REQUEST (0x6) MODIFY_RESPONSE (0x7) ADD_REQUEST (0x8) ADD_RESPONSE (0x9) DEL_REQUEST (0xa) DEL_RESPONSE (0xb) MODIFY_RDN_REQUEST (0xc) MODIFY_RDN_RESPONSE (0xd) COMPARE_REQUEST (0xe) COMPARE_RESPONSE (0xf) ABANDON_REQUEST (0x10) SEARCH_RESULT_REFERENCE (0x13) EXTENDED_REQUEST (0x17) EXTENDED_RESPONSE (0x18) 2.22 public interface LDAPMessageQueue Represents the message queue associated with a particular asynchronous LDAP operation or operations. 2.22.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. Message IDs are defined in section 4.1.1.1 of [LDAPv3]. 2.22.2 getResponse public LDAPMessage getResponse()throws LDAPException Expires January 2003 [Page 77] JAVA LDAP API July 2002 Blocks until a response is available, or until all operations associated with the object have completed or been canceled, and returns the response. public LDAPMessage getResponse(int msgid)throws LDAPException Blocks until a response is available for a particular message ID, or until all operations associated with the message ID have completed or been canceled, and returns the response. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. 2.22.3 isResponseReceived public boolean isResponseReceived() Reports true if any response has been received from the server and not yet retrieved with getResponse. If getResponse has been used to retrieve all messages received to this point, then isResponseReceived returns false. public boolean isResponseReceived(int msgid) Reports true if a response has been received from the server for a particular message ID but not retrieved with getResponse. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. 2.22.4 merge public void merge(LDAPMessageQueue queue2) Merges two queues. Moves/appends the content from another queue to this one. After the operation, queue2.getMessageIDs() returns an empty array and its outstanding responses have been removed (and appended to this queue). Expires January 2003 [Page 78] JAVA LDAP API July 2002 2.23 public class LDAPModification implements Serializable A single change specification for an LDAPAttribute. 2.23.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, creating the attribute if necessary. DELETE The value should be removed from the attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion. REPLACE The value should replace all existing values of the attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist. attr The attribute (possibly with values) to be modified. 2.23.2 getAttribute public LDAPAttribute getAttribute() Returns the attribute (possibly with values) to be modified. Expires January 2003 [Page 79] JAVA LDAP API July 2002 2.23.3 getOp public int getOp() Returns the type of modification specified by this object. 2.23.4 Constants of LDAPModification ADD (0) The value should be added to the attribute, creating the attribute if necessary. DELETE (1) The value should be removed from the attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion. REPLACE (2) The value should replace all existing values of the attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist. 2.24 public class LDAPNameFormSchema extends LDAPSchemaElement The LDAPNameFormSchema class represents the definition of a Name Form. It is used to discover or modify the allowed naming attributes for a particular object class. See [ATTR] for a description of name form representation in LDAP. 2.24.1 Constructors public LDAPNameFormSchema(String[] names, String oid, String description, boolean obsolete, String objectClass, String[] required, String[] optional) Constructs a name form for adding to or deleting from the schema. [LDAPv3] defines which parameters are optional (may be null). public LDAPNameFormSchema(String raw) Constructs a DIT content rule from an encoding using the nameForms syntax [ATTR]. Expires January 2003 [Page 80] JAVA LDAP API July 2002 Parameters are: names Name(s) of the name form. oid Object Identifier of the name form - in dotted-decimal format. description Optional description of the name form. obsolete true if the name form is obsolete. 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. raw A name form definition encoded using the nameForms syntax [ATTR]. 2.24.2 getObjectClass public String getObjectClass() Returns the name of the object class that this name form applies to. 2.24.3 getOptionalNamingAttributes public String[] getOptionalNamingAttributes() Returns the list of optional naming attributes for an entry controlled by this content rule. 2.24.4 getRequiredNamingAttributes public String[]getRequiredNamingAttributes() Returns the list of required naming attributes for an entry controlled by this name form. Expires January 2003 [Page 81] JAVA LDAP API July 2002 2.25 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 [ATTR] for a description of object class representation in LDAP. 2.25.1 Constructors public LDAPObjectClassSchema(String[] names, String oid, String[] superiors, String description, String[] required, String[] optional, int type, boolean obsolete) Constructs an object class definition for adding to or deleting from a Directory. [LDAPv3] defines which parameters are optional (may be null). public LDAPObjectClassSchema(String raw) Constructs an object class definition from an encoding using the ObjectClassDescription syntax [ATTR]. Parameters are: names Name(s) of the object class. oid Object Identifier of the object class - in dotted-decimal format. description Optional description of the object class. superiors The object classes this one derives from. required A list of attributes required for an entry with this object class. optional A list of attributes acceptable but not required for an entry with this object class. type One of ABSTRACT, AUXILIARY, or STRUCTURAL. These are constants defined in LDAPObjectClassSchema. obsolete true if this object class is obsolete. Expires January 2003 [Page 82] JAVA LDAP API July 2002 raw An object class definition encoded using the ObjectClassDescription syntax [ATTR]. 2.25.2 getOptionalAttributes public String[] getOptionalAttributes() Returns a list of attributes acceptable but not required of an entry with this object class. 2.25.3 getRequiredAttributes public String[] getRequiredAttributes() Returns a list of attributes required of an entry with this object class. 2.25.4 getSuperiors public String[] getSuperiors() Returns the object classes which this one derives from. 2.25.5 getType public int getType() Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are constants defined in LDAPObjectClassSchema. 2.25.6 Constants of LDAPObjectClassSchema ABSTRACT (0) identifies an abstract schema class STRUCTURAL (1) identifies a structural schema class AUXILIARY (2) identifies an auxiliary schema class 2.26 public class LDAPReferralException extends LDAPException This exception, derived from LDAPException, is thrown when a server returns a referral or search reference on a synchronous request and automatic referral following has not been enabled. Expires January 2003 [Page 83] JAVA LDAP API July 2002 2.26.1 Constructors public LDAPReferralException() Constructs a default exception with no specific error information. public LDAPReferralException(String message) Constructs a default exception with a specified string as additional information. This form is used for lower-level errors. public LDAPReferralException(String message, Throwable rootException) Constructs a default exception with a specified string as additional information and an exception that indicates a failure to follow a referral. This exception applies only to synchronous operations and is thrown only on receipt of a referral or search reference when the referral or search reference was not followed. public LDAPReferralException(String message, int resultCode, String serverMessage) public LDAPReferralException(String message, int resultCode, String serverMessage, Throwable rootException) Parameters are: message The additional error information. resultCode The result code returned serverMessage Error message specifying additional information from the server. rootException An exception which caused referral following to fail 2.26.2 getFailedReferral public String getFailedReferral() Gets the referral URL that could not be followed. If multiple URLs are in the list, and none could be followed, the method returns one of them. Expires January 2003 [Page 84] JAVA LDAP API July 2002 2.26.3 getReferrals public String[] getReferrals() Gets the list of referral URLs (URLs to other servers) returned by the LDAP server. If the scope field of a referral of type SearchResultReference must be modified in order to follow the referral, the API implementation MUST modify the scope field of the URL before returning the URL to the application. The referral list MAY include URLs of a type other than ones for an LDAP server (i.e. a referral URL other than ldap://something). 2.26.4 setFailedReferral public void setFailedReferral(String url) Sets a referral URL that could not be followed. 2.27 public interface LDAPReferralHandler Shared ancestor to the two types of referral objects - LDAPBindHandler and LDAPAuthHandler. 2.28 public class LDAPResponse extends LDAPMessage Represents the response to a particular asynchronous LDAP operation. 2.28.1 getErrorMessage public String getErrorMessage() Returns any error message in the response. 2.28.2 getMatchedDN public String getMatchedDN() Returns the partially matched DN field, if any, in a server response. 2.28.3 getReferrals Expires January 2003 [Page 85] JAVA LDAP API July 2002 public String[] getReferrals() Returns list of all referral URLs, if any, in a server response. 2.28.4 getResultCode public int getResultCode() Returns the result code in a server response, as defined in [LDAPv3]. 2.29 public class LDAPResponseQueue implements LDAPMessageQueue Represents the message queue associated with a particular asynchronous LDAP operation or operations. 2.29.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. Message IDs are defined in section 4.1.1.1 of [LDAPv3]. 2.29.2 getResponse public LDAPMessage getResponse()throws LDAPException Blocks until a response is available, or until all operations associated with the object have completed or been canceled, and returns the response. public LDAPMessage getResponse(int msgid)throws LDAPException Blocks until a response is available for a particular message ID, or until all operations associated with the message ID have completed or been canceled, and returns the response. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. Expires January 2003 [Page 86] JAVA LDAP API July 2002 2.29.3 isResponseReceived public boolean isResponseReceived() Reports true if any response has been received from the server and not yet retrieved with getResponse. If getResponse has been used to retrieve all messages received to this point, then isResponseReceived returns false. public boolean isResponseReceived(int msgid) Reports true if a response has been received from the server for a particular message ID. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. 2.29.4 merge public void merge(LDAPMessageQueue queue2) Merges two response queues. Moves/appends the content from another queue to this one. 2.30 public class LDAPSchema extends LDAPEntry implements Serializable The LDAPSchema class provides methods to parse schema attributes. Schema may be retrieved from a Directory server with the fetchSchema method of LDAPConnection or by creating an LDAPEntry containing schema attributes. 2.30.1 Constructors public LDAPSchema(LDAPEntry entry) Constructs an LDAPSchema object from attributes of an LDAPEntry. The object is empty if the entry parameter contains no schema attributes. Parameters are: entry An LDAPEntry containing schema information. Expires January 2003 [Page 87] JAVA LDAP API July 2002 2.30.2 getAttributeNames public Enumeration getAttributeNames() Returns an enumeration of attribute names. 2.30.3 getAttributeSchema public LDAPAttributeSchema getAttributeSchema( String name ) Returns a particular attribute definition, or null if not found. Parameters are: name Name or OID of the attribute for which a definition is to be returned. 2.30.4 getAttributeSchemas public Enumeration getAttributeSchemas() Returns an enumeration of attribute definitions. 2.30.5 getDITContentRuleNames public Enumeration getDITContentRuleNames () Returns an enumeration of content rule names. 2.30.6 getDITContentRuleSchema public LDAPDITContentRuleSchema getDITContentRuleSchema(String name ) Returns a particular content rule definition, or null if not found. Parameters are: name Name or OID of the content rule for which a definition is to be returned. 2.30.7 getDITContentRuleSchemas public Enumeration getDITContentRuleSchemas() Returns an enumeration of LDAPDITContentRuleSchema objects. Expires January 2003 [Page 88] JAVA LDAP API July 2002 2.30.8 getDITStructureRuleNames public Enumeration getDITStructureRuleNames () Returns an enumeration of structure rule names. 2.30.9 getDITStructureRuleSchema public LDAPDITStructureRuleSchema getDITStructureRuleSchema( String name ) public LDAPDITStructureRuleSchema getDITStructureRuleSchema( int id ) Returns a particular structure rule definition, or null if not found. Parameters are: name Name or OID of the structure rule for which a definition is to be returned. id Identifier of the structure rule for which a definition is to be returned. 2.30.10 getDITStructureRuleSchemas public Enumeration getDITStructureRuleSchemas() Returns an enumeration of LDAPDITStructureRuleSchema objects. 2.30.11 getMatchingRuleNames public Enumeration getMatchingRuleNames() Returns an enumeration of matching rule names. 2.30.12 getMatchingRuleSchema public LDAPMatchingRuleSchema getMatchingRuleSchema( String name ) Returns a particular matching rule definition, or null if not found. Parameters are: name Name or OID of the matching rule for which a definition is to be returned. Expires January 2003 [Page 89] JAVA LDAP API July 2002 2.30.13 getMatchingRuleSchemas public Enumeration getMatchingRuleSchemas() Returns an enumeration of matching rule definitions. 2.30.14 getMatchingRuleUseNames public Enumeration getMatchingRuleUseNames() Returns an enumeration of matching rule use names. 2.30.15 getMatchingRuleUseSchema public LDAPMatchingRuleUseSchema getMatchingRuleUseSchema( String name ) Returns a particular matching rule use definition, or null if not found. Parameters are: name Name or OID of the matching rule use for which a definition is to be returned. 2.30.16 getMatchingRuleUseSchemas public Enumeration getMatchingRuleUseSchemas() Returns an enumeration of LDAPMatchingRuleUseSchema objects. 2.30.17 getNameFormNames public Enumeration getNameFormNames () Returns an enumeration of name form names. 2.30.18 getNameFormSchema public LDAPNameFormSchema getNameFormSchema( String name ) Returns a particular name form definition, or null if not found. Parameters are: Expires January 2003 [Page 90] JAVA LDAP API July 2002 name Name or OID of the name form for which a definition is to be returned. 2.30.19 getNameFormSchemas public Enumeration getNameFormSchemas() Returns an enumeration of LDAPNameFormSchema objects. 2.30.20 getObjectClassNames public Enumeration getObjectClassNames() Returns an enumeration of object class names. 2.30.21 getObjectClassSchema public LDAPObjectClassSchema getObjectClassSchema( String name ) Returns a particular object class definition, or null if not found. Parameters are: name Name or OID of the object class for which a definition is to be returned. 2.30.22 getObjectClassSchemas public Enumeration getObjectClassSchemas() Returns an enumeration of object class definitions. 2.30.23 getSyntaxSchema public LDAPSyntaxSchema getSyntaxSchema( String oid ) Returns a particular syntax definition, or null if not found. Parameters are: oid Object identifier of the syntax for which a definition is to be returned. 2.30.24 getSyntaxSchemas public Enumeration getSyntaxSchemas() Expires January 2003 [Page 91] JAVA LDAP API July 2002 Returns an enumeration of LDAPSyntaxSchema objects. 2.31 public abstract class LDAPSchemaElement extends LDAPAttribute The LDAPSchemaElement class is the base class for representing schema elements in LDAP. All classes representing schema elements are read-only and thus do not support the addValue and removeValue methods from LDAPAttribute. This class overrides those methods and throws UnsupportedOperationException if addValue or removeValue is invoked. 2.31.1 getDescription public String getDescription() Returns the description of the element. With respect to the protocol- level schema element syntax definition of [ATTR], the value is that of the DESC qualifier. 2.31.2 getNames public String[] getNames() Returns the name(s) of the element. 2.31.3 getID public String getID() Returns the Object Identifier of the element. 2.31.4 getQualifier public String[] getQualifier(String name) Returns an array of all values of a qualifier of the element which is not defined in [ATTR]. This method may be used to access the values of vendor-specific qualifiers (which begin with "X-" [ATTR]). Parameters are: name The name of the qualifier, case-sensitive. Expires January 2003 [Page 92] JAVA LDAP API July 2002 2.31.5 getQualifierNames public Enumeration getQualifierNames() Returns an enumeration of all qualifiers of the element which are not defined in [ATTR]. 2.31.6 isObsolete public boolean isObsolete() Returns true if the element has the OBSOLETE qualifier in its LDAP definition [ATTR]. 2.31.7 setQualifier public void setQualifier(String name, String[] values) Sets the values of a specified optional or experimental qualifier of the element. This method may be used to set the values of vendor- specific qualifiers (which begin with "X-" [ATTR]). Parameters are: name The name of the qualifier, case-sensitive. values The values to set for the qualifier. 2.31.8 toString public String toString() Returns a String in a format suitable for directly adding to a Directory (defined in [ATTR], as a value of the particular schema element attribute. See the format definition for each derived class. 2.32 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.setConstraints, or overridden by passing an LDAPSearchConstraints object to the search operation. 2.32.1 Constructors Expires January 2003 [Page 93] JAVA LDAP API July 2002 public LDAPSearchConstraints() Constructs an LDAPSearchConstraints object that specifies the default set of search constraints. public LDAPSearchConstraints(LDAPConstraints cons) Constructs an LDAPSearchConstraints object initialized with values from an existing constraints object (LDAPConstraints or LDAPSearchConstraints). public LDAPSearchConstraints(int msLimit, int serverTimeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPReferralHandler handler, int hop_limit) Constructs a new LDAPSearchConstraints object and allows specifying the operational constraints in that object. Parameters are: cons Constraints object to use as template. msLimit Maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit). This is an interface-imposed limit. serverTimeLimit Maximum time in seconds that the server should spend returning results. This is a server-imposed limit. The default of 0 means no time limit. dereference Specifies when aliases should be dereferenced. MUST be either DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS (DEREF_NEVER by default). maxResults Maximum number of search results to return (1000 by default). doReferrals Specify true to follow referrals automatically, or false to throw an LDAPReferralException error if the server sends back a referral (false by default). It is ignored for asynchronous operations. Expires January 2003 [Page 94] JAVA LDAP API July 2002 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. handler 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 LDAPBindHandler or the LDAPAuthHandler 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. 2.32.2 getBatchSize public int getBatchSize() Returns the number of results to block on during enumeration of search results. This SHOULD be 0 if intermediate results are not needed, and 1 if results are to be processed as they come in. 2.32.3 getDereference public int getDereference() Specifies when aliases should be dereferenced. Returns one of DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS. 2.32.4 getMaxResults public int getMaxResults() Returns the maximum number of search results to be returned; 0 means no limit. 2.32.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 Expires January 2003 [Page 95] JAVA LDAP API July 2002 2.32.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. 2.32.7 setDereference public void setDereference(int dereference) Sets a preference indicating whether or not aliases should be dereferenced, and if so, when. Parameters are: dereference Either DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS. 2.32.8 setMaxResults public void setMaxResults(int maxResults) Sets the maximum number of search results to be returned; 0 means no limit. The default is 1000. Parameters are: maxResults Maximum number of search results to return. 2.32.9 setServerTimeLimit public void setServerTimeLimit(int seconds) Sets the maximum number of seconds that the server is to wait when returning search results. The parameter is only recognized on search operations. 2.32.10 Constants of LDAPSearchConstraints Expires January 2003 [Page 96] JAVA LDAP API July 2002 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). 2.33 public class LDAPSearchQueue implements LDAPMessageQueue, Serializable An LDAPSearchQueue manages search results and references returned on one or more asynchronous search requests. 2.33.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. Message IDs are defined in section 4.1.1.1 of [LDAPv3]. 2.33.2 getResponse public LDAPMessage getResponse() throws LDAPException Blocks until a response is available, or until all operations associated with the object have completed or been canceled, and returns the response. public LDAPMessage getResponse(int msgid) throws LDAPException Blocks until a response is available for a particular message ID, or until all operations associated with the message ID have completed or been canceled, and returns the response. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. Expires January 2003 [Page 97] JAVA LDAP API July 2002 2.33.3 isComplete public boolean isComplete(int msgid) Reports true if all results for a particular message ID have been received by the API implementation (i.e. a searchResultDone response has been received by the API implementation). There may still be messages queued in the object for retrieval by the application. If there is no outstanding operation for the message ID (or if it is zero or a negative number), IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for completion. 2.33.4 isResponseReceived public boolean isResponseReceived() Reports true if any response has been received from the server and not yet retrieved with getResponse. If getResponse has been used to retrieve all messages received to this point, then isResponseReceived returns false. public boolean isResponseReceived(int msgid) Reports true if a response has been received from the server for a particular message ID. If the message ID is zero or a negative number, IllegalArgumentException is thrown. Parameters are: msgid A particular message to query for responses available. 2.33.5 merge public void merge(LDAPSearchQueue queue2) Merges two search queues. Moves/appends the content from another search queue to this one. Expires January 2003 [Page 98] JAVA LDAP API July 2002 2.34 public class LDAPSearchResult extends LDAPMessage An LDAPSearchResult object encapsulates a single asynchronous search result. 2.34.1 getEntry public LDAPEntry getEntry() Returns the entry of a server search response. 2.35 public class LDAPSearchResultReference extends LDAPMessage An LDAPSearchResultReference object encapsulates a continuation reference from an asynchronous search operation. 2.35.1 getReferrals public String[] getReferrals() Returns the list of any continuation reference URLs in the object. 2.36 public class LDAPSearchResults implements Serializable An LDAPSearchResults object is returned from a synchronous search operation. It provides access to all results received during the operation (entries and exceptions). 2.36.1 getCount public int getCount() Returns a count of the entries and exceptions in the object. If the search was submitted with a batch size greater than 0, this reports the number of results received so far but not enumerated with next(). 2.36.2 getResponseControls public LDAPControl[] getResponseControls() Returns the latest Server Controls returned by a Directory Server in the context of this search request. Expires January 2003 [Page 99] JAVA LDAP API July 2002 2.36.3 hasMore public boolean hasMore() Reports if there are more search results. If true, there are more search results. 2.36.4 next public LDAPEntry next() throws LDAPException Returns the next search result 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. 2.37 public interface LDAPSocketFactory Used to construct a socket connection for use in an LDAPConnection. 2.37.1 createSocket public Socket createSocket(String host, int port) throws IOException, UnknownHostException Returns a socket connected using the provided host name and port number. Parameters are: host Contains a host identifier representing the IP address of a host running an LDAP server to connect to. See 2.8.8 for a discussion of valid identifiers. port Contains the TCP port number to connect to or contact. The default LDAP port is 389. 2.38 public class LDAPSyntaxSchema extends LDAPSchemaElement The LDAPSyntaxSchema class represents the definition of a syntax. It is used to discover the known set of syntaxes in effect for the subschema. See [ATTR] for a description of syntax representation in LDAP. Note that though this extends LDAPSchemaElement, it does not use the name or obsolete members, subsequently calls to getName always return Expires January 2003 [Page 100] JAVA LDAP API July 2002 null and isObsolete always returns false. There is also no matching getSyntaxNames method in LDAPSchema. Note also that adding and removing syntaxes is not typically a supported feature of LDAP servers. 2.38.1 Constructors public LDAPSyntaxSchema(String oid, String description) Constructs a syntax for adding to or deleting from the schema. public LDAPSyntaxSchema(String raw) Constructs a syntax from an encoding using the ldapSyntaxes syntax [ATTR]. Parameters are: oid Object Identifier of the syntax - in dotted- decimal format. description Optional description of the syntax. raw A definition of a syntax encoded using the ldapSyntaxes syntax [ATTR]. 2.39 public interface LDAPTLSSocketFactory extends LDAPSocketFactory Used to construct a socket connection for use in an LDAPConnection. An implementation of this interface provides a TLSSocket connected to a secure server. 2.39.1 createSocket public Socket createSocket(Socket socket) throws IOException, UnknownHostException Converts the connected socket to a TLS socket. Parameters are: socket An active non-TLS socket. 2.40 public interface LDAPUnsolicitedNotificationListener Expires January 2003 [Page 101] JAVA LDAP API July 2002 An object that implements this interface can be notified when unsolicited messages arrive from the server. A client registers the object with LDAPConnection.addUnsolicitedNotificationListener. 2.40.1 messageReceived public void messageReceived(LDAPExtendedResponse msg) The method is called when an unsolicited message arrives from a server, if the object has registered with LDAPConnection.addUnsolicitedNotificationListener. Parameters are: msg An unsolicited message received from the server. 2.41 public class LDAPUrl implements Cloneable, Serializable Encapsulates parameters of an LDAP Url query, as defined in [LDAPURL]. An LDAPUrl object can be passed to LDAPConnection.search to retrieve search results. 2.41.1 Constructors public LDAPUrl(String url) throws MalformedURLException Constructs a URL object with the specified string as URL. public LDAPUrl(String host, int port, String dn) Constructs a URL object with the specified host, port, and DN. This form is used to create URL references to a particular object in the directory. public LDAPUrl(String host, int port, String dn, String[] attrNames, int scope, String filter, String[] extensions) Constructs an LDAP URL with all fields explicitly assigned, to specify an LDAP search operation. Expires January 2003 [Page 102] JAVA LDAP API July 2002 Parameters are: url An LDAP URL string, e.g. "ldap://ldap.example.com:80/dc=example,dc=com?cn, sn?sub?(objectclass=inetOrgPerson)". host Host identifier of LDAP server, or null for "localhost". See 2.8.8 for a discussion of valid identifiers. port Port number for LDAP server (use LDAPConnection.DEFAULT_PORT for default port). dn Distinguished name of the base object of the search. attrNames Names or OIDs of attributes to retrieve. Passing a null array signifies that all user attributes are to be retrieved. Passing a value of "*" as an element of the array signifies that all user attributes are to be retrieved. scope Depth of search (in DN namespace). Use one of SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPConnection. filter Search filter specifying the search criteria, as defined in [FILTER]. extensions LDAP URL extensions specified; may be null or empty. Each extension is a type=value expression. The =value part MAY be omitted. The expression MAY be prefixed with '!' if it is mandatory for evaluation of the URL. 2.41.2 decode public static String decode(String URLEncoded) throws MalformedURLException Decodes a URL-encoded string. Any occurrences of %HH are decoded to the hex value represented. However, this method does NOT decode "+" into " ". See [URL] for details on URL encoding/decoding. Parameters are: URLEncoded String to decode. 2.41.3 encode Expires January 2003 [Page 103] JAVA LDAP API July 2002 public static String encode(String toEncode) Encodes the specified string. Any illegal characters are encoded as %HH. Parameters are: toEncode String to encode. 2.41.4 getAttributeArray public String[] getAttributeArray() Returns an array of attribute names specified in the URL. 2.41.5 getAttributes public Enumeration getAttributes() Returns an enumerator for the attribute names specified in the URL. The enumerator is empty if the URL contains no attribute names. 2.41.6 getDN public String getDN() Returns the distinguished name encapsulated in the URL, or null if none is specified. 2.41.7 getExtensions public String[] getExtensions () Returns any LDAP URL extensions specified, or null if none are specified. Each extension is a type=value expression. The =value part MAY be omitted. The expression MAY be prefixed with '!' if it is mandatory for evaluation of the URL. 2.41.8 getFilter public String getFilter() Returns the search filter [LDAPURL], or null if none was specified. 2.41.9 getHost Expires January 2003 [Page 104] JAVA LDAP API July 2002 public String getHost() Returns the host name of the LDAP server to connect to. 2.41.10 getPort public int getPort() Returns the port number of the LDAP server to connect to. 2.41.11 getScope public int getScope() Returns the depth of search (in DN namespace) - one of SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPConnection. 2.41.12 toString public String toString() Returns a valid string representation of this LDAP URL. 3. Implementation considerations 3.1 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 represented by 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.setControls( 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.setControls( controls ); ld.setConstraints( cons ); Expires January 2003 [Page 105] JAVA LDAP API July 2002 Server controls returned to a client as part of the response to a synchronous operation can be obtained with LDAPConnection.getResponseControls() or LDAPSearchResults.getResponseControls(). Controls returned on an asynchronous operation are available with LDAPMessage.getControls(). 3.2 Referral handling and exceptions Asynchronous requests No automatic referral following is supported for asynchronous requests. No LDAPExceptions are thrown for asynchronous requests except in the case of local errors. The Throwable causing the local error can be retrieved with LDAPConnection.getCause(). When a referral is received, the application receives an LDAPResponse object with a result code of REFERRAL. If a continuation reference is received the application receives an LDAPSearchResultReference object. Synchronous requests Referral-following behavior depends on two things: if automatic referral following is enabled, and when enabled if an LDAPReferralHandler is provided by the application. - Behavior if automatic referral following is "false" (not enabled): An LDAPException is thrown for any non-zero result code. An LDAPException is thrown for local failures. An LDAPReferralException is thrown if the result code is REFERRAL. It contains the referral URL strings. This ends the request, i.e., there are no more results to retrieve. An LDAPReferralException is thrown for each SearchResultReference received during a search request. It contains the referral URL strings. This is not an error, there may be more data to retrieve. - Behavior if automatic referral following is "true" and either no LDAPReferralHandler is registered in LDAPConstraints, or an LDAPAuthHandler object is registered in LDAPConstraints: Exception handling is the same whether or not an LDAPAuthHandler object is registered, but authentication to the server is not the same. The registration of an LDAPAuthHandler object allows Expires January 2003 [Page 106] JAVA LDAP API July 2002 connections to be authenticated. No handler registered results in an anonymous (unauthenticated) connection. LDAPExceptions are thrown if errors occur during the normal processing of the command, i.e. NO_SUCH_OBJECT, NO_SUCH_ATTRIBUTE, etc. An LDAPReferralException is thrown only if the API implementation could not connect and bind to any referral URL in the list of URLs included in an individual REFERRAL result or LDAPSearchResultReference. When problems occur during the establishment of an authenticated connection by the API implementation during automatic referral following, the LDAPReferralException will contain the last tried URL String of the server the API attempted to connect/bind to (the referral can be retrieved with getFailedReferral()), and the Throwable that caused the Exception (which can be retrieved with getCause()).Some possible failures are IOException on the connection, MalformedURLException on the referral string, or authentication failures on the bind. Upon receipt of an LDAPReferralException, the application knows that the API implementation was not able to connect to any of the servers in the referral list (which can be retrieved with getReferrals()) and was not able to follow the referral. The error indicated by getCause() occurred on the referral indicated with getFailedReferral(). In the case of search, any results starting at the indicated base of the referred to server are missing from the search results. - behavior if automatic referral following is "true", and an LDAPBindHandler object is registered in LDAPConstraints: LDAPExceptions are thrown if errors occur during the normal processing of the command, i.e. NO_SUCH_OBJECT, NO_SUCH_ATTRIBUTE, etc. An LDAPReferralException is thrown only if the LDAPBindHandler object throws an exception. Upon receipt of an LDAPReferralException, the application knows that the LDAPBindHandler object was not able or not willing to connect to any of the servers in the referral list and so was not able to follow the referral. The list of referrals that failed is available with getReferrals() and the last failed referral with getFailedReferral(). The exception thrown by the LDAPBindHandler object is available with getCause(). 3.3 Message IDs Expires January 2003 [Page 107] JAVA LDAP API July 2002 An implementation of the Java LDAP API SHOULD NOT generate messages with an ID of 0. 3.4 Notice of disconnection If a notice of disconnection is received by a connection object, the object MUST close the connection without accepting or sending additional messages. Any clones of the object are disconnected as a consequence of closing the connection. 3.5 Level of compatibility Implementations of the API are to be binary compatible. Any implementation MUST behave as defined above with any application written to the API specification. 3.6 Dependencies The Java LDAP API is dependent on the following: - JDK 1.2 or higher - JAAS 1.0 or higher (for the interfaces in the javax.security.auth.callback package) 3.7 Invalid responses If a message is received by an API implementation from the server and the message cannot be interpreted as an LDAP PDU, an LDAPException MUST be thrown with a result code of INVALID_RESPONSE. 4. Security considerations LDAP supports security through protocol-level authentication, using clear-text passwords or other more secure mechanisms. It also supports running over TLS, which provides strong security at the transport layer. If a TLS session is terminated by the server but the client TLS provider and LDAP API implementation continue to use the socket rather than closing it, the application is notified through an LDAPException on the first operation request subsequent to termination of the TLS session. An interface to using SASL for configurable authentication and session protection is provided, but implementations are outside the scope of this document. Implementations of this API MUST ensure that Expires January 2003 [Page 108] JAVA LDAP API July 2002 a SASL provider is configured to comply with the minimal security guidelines of RFC 2829 [AUTH]. Implementations of this API SHOULD be cautious when handling authentication credentials. In particular, keeping long-lived copies of credentials without the application's knowledge is discouraged. Implementations of this API MUST discard information about the server obtained prior to negotiation of security protections provided by SASL and/or TLS [AUTH]. 5. Acknowledgements The proposed API builds on earlier work done in collaboration with Thomas Kwan and Stephan Gudmundson, then of NCware Technologies Corp. It also includes suggestions by Steven Merrill of Novell, Inc, and benefited from extensive review and comments by Kurt Zeilenga of OpenLDAP, Rosanna Lee of Sun Microsystems, Mark Smith of Netscape Communications Corp., and Jim Sermersheim of Novell, Inc. Parts of the overview of the LDAP model are taken from draft-ietf-ldapext- ldap-c-api. 6. Bibliography 6.1 Normative References [ATTR] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol: Attribute Syntax Definitions", RFC 2252, December 1997 [AUTH] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000 [DN] S. Kille, " UTF-8 String Representation of Distinguished Names," RFC 2253, December 1997. [FILTER] T. Howes, "A String Representation of LDAP Search Filters," RFC 2254, December 1997. [IPv6] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", RFC 2373, July 1998 [IPv6URL] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6 Addresses in URL's", RFC 2732, December 1999 [LDAPLANG] M. Wahl, T. Howes, " Use of Language Codes in LDAP", RFC 2596, May 1999 Expires January 2003 [Page 109] JAVA LDAP API July 2002 [LDAPTLS] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [LDAPURL] T. Howes, M. Smith, "An LDAP URL Format", RFC 2255, December 1997. [LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [SASL] J. Myers, "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [TLS] T. Dierks, C. Allen, "The TLS Protocol", RFC 2246, January 1999. [URL] T. Berners-Lee, R. Fielding, L. Masinter, " Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 6.2 Informative References [JAVA] B. Joy, G. Steele, J. Gosling, G. Bracha, "The Java Language Specification", Second Edition, Addison-Wesley, June 2000 [JAVASASL] "Java SASL Specification", Java Community Process, JSR28 [KEYWORDS] "Key words for use in RFCs to Indicate Requirement Levels", Bradner, S., RFC 2119, March 1997 [LANG] H. Alvestrans, "Tags for the Identification of Languages", RFC 3066, January 2001. [X500] The Directory: Overview of Concepts, Models, and Services. CCITT, Recommendation X.500, 2nd edition, 1993 7. Authors' addresses Rob Weltman Netscape Communications Corp. 466 Ellis Street Mountain View, CA 94043 USA +1 650 937-3194 rweltman@netscape.com Christine Tomlinson Sun Microsystems, Inc. 8911 Capital of Texas Highway Suite 4140 Austin, TX US 78759 Expires January 2003 [Page 110] JAVA LDAP API July 2002 +1 512 231 1600 christine.tomlinson@sun.com Steven Sonntag Novell, Inc. 1800 South Novell Place Provo, UT 84606 USA +1 801 861 7097 vtag@novell.com Expires January 2003 [Page 111] JAVA LDAP API July 2002 8. Appendix A - Sample Java LDAP programs 8.1 Java LDAP programs using synchronous methods import org.ietf.ldap.*; import java.util.*; public class SearchJensen { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* Authentication not required for an anonymous connection */ /* search for all entries with surname of Jensen */ String MY_FILTER = "(sn=Jensen)"; String MY_SEARCHBASE = "dc=example,dc=com"; LDAPSearchConstraints cons = ld.getSearchConstraints(); /* Setting the batchSize to one will cause the result enumeration below to block on one result at a time, allowing us to update a list or do other things as results come in. */ /* We could set it to 0 if we just wanted to get all results and were willing to block until then */ cons.setBatchSize( 1 ); LDAPSearchResults res = ld.search( MY_SEARCHBASE, ld.SCOPE_ONE, MY_FILTER, null, false, cons ); /* Loop on results until finished */ while ( res.hasMore() ) { /* Next directory entry */ LDAPEntry findEntry = res.next (); System.out.println( findEntry.getDN() ); /* Get the attributes of the entry */ LDAPAttributeSet findAttrs = findEntry.getAttributeSet(); Iterator enumAttrs = findAttrs.iterator(); System.out.println( "Attributes: " ); /* Loop on attributes */ while ( enumAttrs.hasNext() ) { LDAPAttribute anAttr = Expires January 2003 [Page 112] JAVA LDAP API July 2002 (LDAPAttribute)enumAttrs.next(); String attrName = anAttr.getName(); System.out.println( " " + attrName ); /* Loop on values for this attribute. Note: we are assuming all values are UTF-8 strings */ Enumeration enumVals = anAttr.getStringValues(); while ( enumVals.hasMoreElements() ) { String aVal = (String)enumVals.nextElement(); System.out.println( " " + aVal ); } } } /* Done, so disconnect */ ld.disconnect(); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } } } Expires January 2003 [Page 113] JAVA LDAP API July 2002 import org.ietf.ldap.*; import java.io.*; import java.util.*; import javax.security.auth.callback.*; public class ModifyEmail { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); String MY_NAME = "uid=bjensen,ou=people,dc=example,dc=com"; /* Callback handler to supply credentials for SASL */ CallbackHandler cbh = new CallbackHandler() { public void handle( Callback[] callbacks ) throws IOException, UnsupportedCallbackException { for ( int i = 0; i < callbacks.length; i++ ) { if ( callbacks[i] instanceof NameCallback ){ ((NameCallback)callbacks[i]).setName( "bjensen" ); } else if ( callbacks[i] instanceof PasswordCallback ) { ((PasswordCallback)callbacks[i]).setPassword( "MysteryLady".toCharArray() ); } else { throw new UnsupportedCallbackException ( callbacks[i], "Unrecognized Callback" ); } } } }; /* SASL bind */ ld.bind( "cn=Barbara Jensen,dc=example,dc=com", "bjensen", null, cbh ); /* Prepare to change my email address */ LDAPAttribute attrEmail = new LDAPAttribute( "mail", "babs@example.com" ); LDAPModification mod = new LDAPModification( LDAPModification.REPLACE, attrEmail ); /* Now modify the entry in the directory */ ld.modify( MY_NAME, mod ); System.out.println( "Entry modified" ); Expires January 2003 [Page 114] JAVA LDAP API July 2002 /* Done, so disconnect */ ld.disconnect(); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } } } Expires January 2003 [Page 115] JAVA LDAP API July 2002 import org.ietf.ldap.*; import java.util.*; public class ShowSchema { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* Fetch the schema */ LDAPSchema schema = ld.fetchSchema( ld.getSchemaDN() ); /* What is the definition of "userPassword"? */ LDAPAttributeSchema a = schema.getAttributeSchema( "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.getObjectClassSchema( "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( " " + required.nextElement() ); } System.out.println( "Optional attributes for person:" ); while( optional.hasMoreElements() ) { System.out.println( " " + optional.nextElement() ); } Expires January 2003 [Page 116] JAVA LDAP API July 2002 } /* Done, so disconnect */ ld.disconnect(); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } } 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 January 2003 [Page 117] JAVA LDAP API July 2002 8.2 Java LDAP programs using asynchronous methods import org.ietf.ldap.*; import java.util.*; import java.io.UnsupportedEncodingException; 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; byte[] MY_PASSWORD = null; try { MY_PASSWORD = "password".getBytes( "UTF8" ); } catch (UnsupportedEncodingException ex ) { } ld.connect( MY_HOST, MY_PORT ); /* Asynchronous authentication */ LDAPResponseQueue r = ld.bind( 3, "uid=admin,ou=people,dc=example,dc=com", MY_PASSWORD, (LDAPResponseQueue)null ); /* Do something else, just to show that we're not blocked yet */ System.out.println( "Started authenticating" ); /* Wait until it completes */ LDAPResponse response = (LDAPResponse)r.getResponse(); int resultCode = response.getResultCode(); if (resultCode != LDAPException.SUCCESS) { throw new LDAPException ( "error result", resultCode, response.getMatchedDN() ); } /* search for all entries with surname of Jensen */ String MY_FILTER = "(sn=Jensen)"; String MY_SEARCHBASE = "dc=example,dc=com"; LDAPSearchQueue l = ld.search( MY_SEARCHBASE, ld.SCOPE_ONE, MY_FILTER, null, false, (LDAPSearchQueue)null ); /* Loop on results until finished */ LDAPMessage msg; Expires January 2003 [Page 118] JAVA LDAP API July 2002 while( (msg = l.getResponse()) != null ) { if ( msg instanceof LDAPSearchResultReference ) { String[] urls = ((LDAPSearchResultReference)msg).getReferrals(); // Do something with the referrals... } 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.resultCodeToString(status); throw new LDAPException(err, status, res.getMatchedDN()); } } } /* Done, so disconnect */ ld.disconnect(); } catch ( LDAPException e ) { System.err.println( e.toString() ); } } } Expires January 2003 [Page 119] JAVA LDAP API July 2002 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 = { "dc=example,dc=com", "o=example.com", "dc=example2,dc=com" }; /* search for all entries with surname of Jensen */ String MY_FILTER = "(sn=Jensen)"; for( int i = 0; i < ld.length; i++ ) { ld[i] = new LDAPConnection(); /* Connect to server */ ld[i].connect( hosts[i], ports[i] ); } /* Get a response queue for one search */ LDAPSearchQueue l = ld[0].search( bases[0], ld.SCOPE_SUB, MY_FILTER, null, false, (LDAPSearchQueue)null ); /* Share the queue */ for( int 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 January 2003 [Page 120] JAVA LDAP API July 2002 import org.ietf.ldap.*; import java.util.*; /* This example multiplexes the input from three searches in different subtrees of the same server */ public class MultiplexTrees { public static void main( String[] args ) { try { LDAPConnection ld = new LDAPConnection (); /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); String MY_FILTER = "(sn=Jensen)"; String[] bases = { "dc=example,dc=com", "o=example.com", "dc=example2,dc=com" }; /* Get a response queue for one search */ LDAPSearchQueue l = ld.search( bases[0], ld.SCOPE_SUB, MY_FILTER, null, false, (LDAPSearchQueue)null ); /* Share the queue */ for( int 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 January 2003 [Page 121] JAVA LDAP API July 2002 import org.ietf.ldap.*; import java.util.*; public class ModifyEmail { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection( new myTLSFactory() ); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* Use TLS to authenticate and secure the connection */ ld.startTLS(); /* Use SASL external on completed TLS client auth */ ld.bind( null, null, new String[] { "external" }, null, null ); /* Prepare to change my email address */ LDAPAttribute attrEmail = new LDAPAttribute( "mail", "babs@example.com" ); LDAPModification mod = new LDAPModification( LDAPModification.REPLACE, attrEmail ); /* Now modify the entry in the directory */ LDAPResponseQueue r = ld.modify( MY_NAME, mod, null ); /* Do something else, just to show that we're not blocked yet */ System.out.println( "Started authenticating" ); /* Wait until it completes */ LDAPResponse response = (LDAPResponse)r.getResponse(); int resultCode = response.getResultCode(); if (resultCode != LDAPException.SUCCESS) { throw new LDAPException ( "error result", resultCode, response.getMatchedDN() ); } System.out.println( "Entry modified" ); /* Done, so disconnect */ ld.disconnect(); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } } } Expires January 2003 [Page 122] JAVA LDAP API July 2002 9. Appendix B - Revision history 9.1 Changes from ldap-java-api-17.txt LDAPAttribute Throws IllegalArgumentException for null as value parameter in constructors. Implements Comparable, with the method compareTo(). LDAPConnection getProperty() returns null for property not found rather than throwing LDAPException. Added fetchSchema() and getSchemaDN(). Removed getInputStream(), getOutputStream(), setInputStream(), setOutputStream(). LDAPConstraints Removed text saying that non-LDAP URLs are ignored. setProperty() throws IllegalArgumentException for an unsupported property. LDAPEntry Implements Comparable, with the method compareTo(). Clarified that getAttributeSet() and getAttribute() return copies rather than references. LDAPExtendedOperation Implements Cloneable. LDAPExtendedResponse Added register(). LDAPLocalException New class for local errors. Expires January 2003 [Page 123] JAVA LDAP API July 2002 LDAPSchema It now extends LDAPEntry. Constructor takes an LDAPEntry as parameter. Removed fetchSchema(), add(), modify(), remove(), and saveSchema().Methods in LDAPConnection provide this functionality. LDAPSchemaElement Extends LDAPAttribute. Added clarification that the class is read only. LDAPTLSSocketFactory New interface to indicate ability to create a TLS socket. Other Java 2 is now a requirement (not JDK 1.1.8 or Java 2). Editorial changes 9.2 Changes from ldap-java-api-16.txt LDAPException Added serverMessage as parameter in constructors. Other Corrected typographical errors and errors in examples of appendix A. 9.3 Changes from ldap-java-api-15.txt LDAPAttribute Implements Cloneable. LDAPAttributeSchema Constructor takes "String[] names" instead of "String name" and "String[] aliases". Expires January 2003 [Page 124] JAVA LDAP API July 2002 LDAPAttributeSet Implements Cloneable and java.util.Set. Removed the methods made redundant by implementing Set: add(LDAPAttribute attr), elementAt(), getAttributes(), remove(String name), removeElementAt(), and size(). LDAPConnection Removed all bind() signatures which take String instead of byte[] for password. Replaced Hashtable as parameter with Map in bind() and getSaslBindProperties. The LDAP_PROPERTY_SDK is of type String rather than Float. LDAP_PROPERTY_PROTOCOL is of type Integer. setInputStream and setOutputStream throw LDAPException. Removed setProperty. Added stopTLS. LDAPCompareAttrNames Implements java.util.Comparator instead of LDAPEntryComparator. LDAPConstraints Implements Cloneable. getServerControls renamed to getControls. setServerControls renamed to setControls. Added getProperty and setProperty. getClientControls and setClientControls removed. LDAPControl Removed all references to "client controls". LDAPEntryComparator Expires January 2003 [Page 125] JAVA LDAP API July 2002 Removed; LDAPCompareAttrNames implements java.util.Comparator instead. LDAPException Renamed errorCodeToString() to resultCodeToString(). Renamed getLDAPResultCode () to getResultCode (). LDAPListener Renamed to LDAPMessageQueue. LDAPMatchingRuleSchema Combined the two constructors with explicit field parameters. LDAPModificationSet Removed (replaced with LDAPModification[] as parameter where referenced). LDAPResponseListener Renamed to LDAPResponseQueue. LDAPRebind Renamed to LDAPAuthHandler. LDAPRebindAuth Renamed to LDAPAuthProvider. LDAPSchema Renamed getAttribute() to getAttributeSchema(),getAttributes() to getAttributeSchemas(), getObjectClass() to getObjectClassSchema(), getSyntax() to getSyntaxSchema(), getSyntaxes() to getSyntaxSchemas(), getDITContentRule () to getDITContentRuleSchema(), getDITContentRules() to getDITContentRuleSchemas(), getDITStructureRule() to getDITStructureRuleSchema(), getDITStructureRules() to Expires January 2003 [Page 126] JAVA LDAP API July 2002 getDITStructureRuleSchemas(),getMatchingRule() to getMatchingRuleSchema(), getMatchingRules() to getMatchingRuleSchemas(), getMatchingRuleUse() to getMatchingRuleUseSchema(),getMatchingRuleUses() to getMatchingRuleUseSchemas(),getNameForm() to getNameFormSchema(), getNameForms() to getNameFormSchemas(). Added add(), modify(), remove(), and saveSchema(). LDAPSchemaElement Renamed getValue() to toString(). Changed getName() to getNames(), removed getAliases(). Removed add(), modify(), and remove(). LDAPSearchConstraints Added constructor that takes LDAPConstraints as parameter. LDAPSearchListener Renamed to LDAPSearchQueue. LDAPSearchResults Does not implement Enumeration. Removed nextElement(). Renamed hasMoreElements() to hasMore(). Removed sort() (sorting can now be done with classes/interfaces of the Collections framework now that LDAPAttributeSet implements Set). LDAPSocketFactory Renamed makeSocket() to createSocket(). LDAPUrl Implements Cloneable. Renamed getUrl() to toString(). Expires January 2003 [Page 127] JAVA LDAP API July 2002 Added extensions to the constructor that takes all fields explicitly. All schema elements Constructors take a parameter "String[] names" instead of "String name" and "String[] aliases". Implementation Considerations Removed the specification of package name for controls. The package name may be specified in a follow-on document describing various controls. Moved the package name up to section 1. Added Dependencies. Serializability Made the following classes Serializable: LDAPAttribute LDAPAttributeSet LDAPConstraints LDAPControl LDAPEntry LDAPExtendedOperation LDAPMessage LDAPModification LDAPSchema LDAPSchemaElement LDAPSearchListener LDAPSearchResults LDAPUrl 9.4 Changes from ldap-java-api-14.txt LDAPAttributeSchema Changed isModifiable() to isUserModifiable() LDAPConnection Added bind() signatures that take byte[] as password parameter, removed bind() signatures which do not take a version parameter Expires January 2003 [Page 128] JAVA LDAP API July 2002 Use Hashtable, not Properties, in all SASL bind signatures Removed setSearchConstraints() rename() takes newParentdn before deleteOldRdn (one of the eight signatures had the order reversed) LDAPException Defined how the toString method overrides the default toString behavior LDAPMatchingRuleSchema Changed return of getSyntaxString from String[] to String LDAPUrl Removed constructor signature which takes "secure" as a parameter Removed isSecure() getFilter() returns null instead of "(objectclass=*)" if no filter was specified Examples Use SASL to bind in synchronous ModifyEmail example and TLS in asynchronous ModifyEmail example (instead of simple bind) General Put methods of LDAPAttributeSchema in alphabetical order Clarifications and editorial changes 9.5 Changes from ldap-java-api-13.txt Notice of disconnection, Invalid responses, Level of compatibility New section Expires January 2003 [Page 129] JAVA LDAP API July 2002 Result codes Added INVALID_RESPONSE, AMBIGUOUS_RESPONSE Removed PARAM_ERROR LDAPConnection Removed getAuthenticationPassword() Added bind() signatures that take a byte array for password bind() signatures for SASL take an authzId parameter disconnect() may take an LDAPConstraints parameter read() throws LDAPException with AMBIGUOUS_RESPONSE if there is more than one result LDAPConstraints Removed getReferralHandler LDAPRebindAuth Added a signature of the constructor which takes byte[] as parameter getPassword() returns byte[] instead of String LDAPReferralException Clarified that getReferrals() must return LDAP URL strings with the scope rewritten if necessary (for SearchResultReferences on search continuation). LDAPDN Added normalize() and isValid(). LDAPUnsolicitedNotificationListener The argument to messageReceived() is LDAPExtendedResponse and not LDAPMessage. Security Considerations Added implementation guidelines Expires January 2003 [Page 130] JAVA LDAP API July 2002 General All classes and methods in alphabetical order Many clarifications and editorial changes 9.6 Changes from ldap-java-api-12.txt Abstract Removed references to RFC 1823 and to an earlier draft on an asynchronous interface. LDAPConnection Under clone(), added a listing of which methods affect an individual clone and which ones affect all related clones. LDAPException Can take Throwable as root exception argument in an additional constructor signature. Added getCause() to return the root exception. Removed reference to LDAP_PARTIAL_RESULTS among result codes. LDAPBind bind() throws LDAPReferralException instead of LDAPException. LDAPReferralException Can take Throwable as root exception argument instead of LDAPException. getFailureException() was removed and replaced by getCause() in LDAPException. Added getFailedReferral() and setFailedReferral(). LDAPControl Removed newInstance(). An implementation of the API can instantiate a control using the LDAPControl constructor. Removed a sentence saying that LDAPv2 doesn't support controls. Referral handling Expires January 2003 [Page 131] JAVA LDAP API July 2002 Added section outlining the handling of exceptions on referrals. References Added references to RFCs 2222 and 2830. Host names May be IPv6 references as well as hostnames or IPv4 addresses. LDAPMessage Restored the values of the message types to correspond to the message type values in ldap-java-api-11.txt. LDAPEntry getAttribute returns a single attribute. Unsolicited notifications in LDAPConnection Removed getUnsolicitedNotifications and setUnsolicitedNotifications. Added addUnsolicitedNotificationListener and removeUnsolicitedNotificationListener. Added interface LDAPUnsolicitedNotificationListener. 9.7 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. Expires January 2003 [Page 132] JAVA LDAP API July 2002 Added isTLS. Added getProtocolVersion. Added signatures of abandon which take LDAPConstraints as argument. extendedOperation returns LDAPExtendedResponse, not LDAPExtendedOperation. Added signatures of SASL bind that take LDAPConstraints as argument. Added getSaslBindProperties. Added getSaslBindCallbackHandler. Added getUnsolicitedNotifications and setUnsolicitedNotifications. The default protocol version to bind with is LDAPv3, not LDAPv2. Constants: LDAP_DEREF_NEVER, etc changed to DEREF_NEVER, etc. Values of DEREF_SEARCHING and DEREF_FINDING corrected to those of RFC 2251. The values are now defined in LDAPSearchConstraints instead of in LDAPConnection. LDAPControl Added setValue. LDAPExtendedOperation Added setValue. LDAPSearchResultReference Changed getURLs to getReferrals, which returns String[]. LDAPUrl Added method isSecure. Added constructors that take a boolean for isSecure. LDAPReferralException Expires January 2003 [Page 133] JAVA LDAP API July 2002 Added getReferralFailureException. Changed getURLs to getReferrals, which returns String[]. LDAPConstraints Takes a new interface LDAPReferralHandler as parameter, instead of LDAPBind and LDAPRebind. Changed getReferrals to getReferralFollowing. Changed setReferrals to setReferralFollowing. LDAPReferralHandler New common ancestor to LDAPBind and LDAPRebind. LDAPListener New common ancestor to LDAPSearchListener and LDAPResponseListener. LDAPSearchListener Implements LDAPListener. Added signature of isResponseReceived and of getResponse that takes a message ID as parameter. Added isComplete. LDAPResponseListener 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 Expires January 2003 [Page 134] JAVA LDAP API July 2002 Defined the values of symbolic result codes generated by the interface. Added a constructor that takes matchedDN as parameter. LDAPMessage Redefined the values of the message types to correspond to the message type values in [LDAPv3]. 9.8 Changes from ldap-java-api-10.txt Overview of the LDAP model Allowed for character set conversion from/to T.61 (in addition to UTF-8). LDAPConnection Added startTLS. Added STRING_FORMAT option to setOption. Added numerical values to options in setOption and search. Changed REFERRALS_AUTHENTICATION to REFERRALS_REBIND_PROC. Clarified that getAuthenticationPassword returns null if no simple bind has been performed. Added asynchronous methods (from [TLS]). LDAPConstraints Default for setHopLimit is 10, not 5. LDAPUrl Added getScope and getExtensions. Schema classes Added parameters to constructors (aliases, obsolete, collective). Various classes Removed all "synchronized" qualifier on methods. Added a statement that implementations should ensure thread-safety. 9.9 Changes from ldap-java-api-09.txt Overview of LDAP API use Expires January 2003 [Page 135] JAVA LDAP API July 2002 Clarifications were added on the behavior of the SDK for null values of LDAPConstraints and for a DN. LDAPAttributeSet Return type of getAttribute is LDAPAttribute, not LDAPAttribute[]. LDAPV2 Added convenience method of add that does not take LDAPConstraints, added read method that does take LDAPSearchConstraints. Error Codes Changed to Result Codes. Added TLS_NOT_SUPPORTED. LDAPSearchResults Clarified in declaration that it implements Enumeration. LDAPV3 Added constants NO_ATTRS and ALL_USER_ATTRS. Schema classes Added LDAPDITContentRuleSchema, LDAPDITStructureRuleSchema, LDAPMatchingRuleUseSchema, LDAPNameFormSchema, LDAPSyntaxSchema. 9.10 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. Expires January 2003 [Page 136] JAVA LDAP API July 2002 LDAPv2 Removed static methods search(LDAPUrl url). The methods are still present in LDAPConnection. 9.11 Changes from ldap-java-api-07.txt LDAPAttributeSchema Removed getAliases() because it is already defined in the superior class LDAPSchemaElement. Removed getSyntax() which returned an integer. LDAPConnection Added getAuthenticationMethod(). LDAPSchemaElement Changed getOID() to getID(). 9.12 Changes from ldap-java-api-06.txt LDAPAttributeSchema Added a constructor that takes the attribute syntax as a String, an optional superior attribute type, and an optional list of aliases. Removed previous constructor. Added getSuperior()and getSyntaxString(). LDAPConnection Added getInputStream()getOutputStream(), setInputStream() (1.1.1), 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 [URL]. Expires January 2003 [Page 137] JAVA LDAP API July 2002 LDAPMatchingRuleSchema Added a constructor that takes the attribute syntax as a String and an optional list of aliases. Removed previous constructor. LDAPObjectClassSchema Added a constructor that takes an array of superior object class names, a type (ABSTRACT, AUXILIARY, or STRUCTURAL), and an optional list of aliases. Removed previous constructor. Added getSuperiors()and getType(). Removed getSuperior(). LDAPSchemaElement Added overloaded methods of add, remove, and modify which take a DN as parameter, for specifying where in the DIT to determine the subschemaSubentry for the modification. Added getAliases(), getQualifier(), getQualiferNames(), isObsolete(), and setQualifier(). 9.13 Changes from ldap-java-api-05.txt LDAPConnection Distinguished between getConstraints() and getSearchConstraints(), and between setConstraints() and setSearchConstraints(). LDAPConstraints LDAPBind and LDAPRebind should not be specified in the same constructor. Added setClientControls(). LDAPSearchConstraints LDAPBind and LDAPRebind should not be specified in the same constructor. LDAPControl newInstance() is now static. LDAPv3 Expires January 2003 [Page 138] JAVA LDAP API July 2002 Changed the signature of the bind() methods to match the Java SASL Internet Draft. 9.14 Changes from ldap-java-api-04.txt LDAPAttribute Added getByteValueArray() and getStringValueArray(). LDAPCompareAttrNames Added getLocale() and setLocale(). LDAPSchemaElement Added modify(). LDAPSchemaElement Added fetchSchema(LDAPConnection, String). 9.15 Changes from ldap-java-api-03.txt LDAPBind New interface, to support sophisticated reauthentication mechanisms. 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 Expires January 2003 [Page 139] JAVA LDAP API July 2002 Reverted back to original name, instead of LDAPReauthentication as it was in the previous draft. LDAPRebindProc Reverted back from LDAPCredentials. LDAPSearchConstraints Reinstated this class, to represent all constraints applicable to a search. LDAPConstraints (which it extends) only represents common constraints for all operations. LDAPSearchResults Added getResponseControls(). LDAPv2 Added abandon(). Separated interface time limit from server search time limit. Changed authenticate() to bind(). LDAPv3 Changed authenticate() to bind(). 9.16 Changes from ldap-java-api-02.txt LDAPSearchConstraints 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. 9.17 Changes from ldap-java-api-01.txt Expires January 2003 [Page 140] JAVA LDAP API July 2002 LDAPAttribute Added a copy constructor. Added support for subtypes, and for language subtypes in particular. LDAPAttributeSet LDAPAttributeSet implements Cloneable. Added getSubset() for subtype support. LDAPDN Added support for escaping and unescaping an RDN. LDAPException Added the SASL_BIND_IN_PROGRESS error code. LDAPSearchResults Added getCount(), to report the number of results returned. LDAPConnection Added a signature that passes LDAPConstraints to read(LDAPURL). LDAPv2 Added signatures that pass LDAPConstraints to the following methods: add() compare() 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 January 2003 [Page 141]