Network Working Group Rob Weltman INTERNET-DRAFT Netscape Communications Corp. Intended Category: Standards Track Christine Tomlinson Innosoft International, Inc. Mark Smith Netscape Communications Corp. Tim Howes January 3, 2000 The Java LDAP Application Program Interface draft-ietf-ldapext-ldap-java-api-09.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document defines a java language application program interface to the lightweight directory access protocol (LDAP), in the form of a class library. It complements but does not replace RFC 1823 ([7]), which describes a C language application program interface. It updates and the previous draft in correcting a few minor errors which are listed in appendix B. The companion document draft-ietf-ldapext-ldap-java-api-asynch [10] defines the mandatory to implement asynchronous layer of the API. Expires 2000 [Page 1] JAVA LDAP API January 2000 1. Overview of the LDAP model.......................................8 2. Overview of the LDAP classes.....................................9 2.1 Interfaces......................................................9 2.2 Classes........................................................10 2.3 Exceptions.....................................................12 3. Overview of LDAP API use........................................12 4. The java LDAP classes...........................................13 4.1 public class LDAPAttribute.....................................13 4.1.1 Constructors................................................13 4.1.2 addValue....................................................14 4.1.3 getByteValues...............................................14 4.1.4 getStringValues.............................................14 4.1.5 getByteValueArray...........................................15 4.1.6 getStringValueArray.........................................15 4.1.7 getLangSubtype..............................................15 4.1.8 getBaseName.................................................15 4.1.9 getName.....................................................15 4.1.10 getSubtypes...............................................15 4.1.11 hasSubtype................................................16 4.1.12 hasSubtypes...............................................16 4.1.13 removeValue...............................................16 4.1.14 size......................................................17 4.2 public class LDAPAttributeSchema...............................17 4.2.1 Constructors................................................17 4.2.2 getSyntaxString.............................................18 4.2.3 getSuperior.................................................18 4.2.4 isSingleValued..............................................18 4.3 public class LDAPAttributeSet..................................18 4.3.1 Constructors................................................18 4.3.2 add.........................................................19 4.3.3 clone.......................................................19 4.3.4 elementAt...................................................19 4.3.5 getAttribute................................................19 4.3.6 getAttributes...............................................20 4.3.7 getSubset...................................................20 4.3.8 remove......................................................21 4.3.9 removeElementAt.............................................21 4.3.10 size......................................................22 4.4 public interface LDAPBind......................................22 4.4.1 bind........................................................22 4.5 public class LDAPCompareAttrNames..............................22 4.5.1 Constructors................................................22 4.5.2 getLocale...................................................23 4.5.3 setLocale...................................................23 4.5.4 isGreater...................................................24 4.6 public class LDAPConnection....................................24 4.6.1 Constructors................................................24 4.6.2 clone.......................................................25 4.6.3 finalize....................................................25 4.6.4 getAuthenticationDN.........................................25 4.6.5 getAuthenticationMethod.....................................25 Expires July 3, 2000 [Page 2] JAVA LDAP API January 2000 4.6.6 getAuthenticationPassword...................................26 4.6.7 getHost.....................................................26 4.6.8 getInputStream..............................................26 4.6.9 getOutputStream.............................................26 4.6.10 getPort...................................................26 4.6.11 getProperty...............................................26 4.6.12 getConstraints............................................27 4.6.13 getSearchConstraints......................................27 4.6.14 getSocketFactory..........................................28 4.6.15 isBound...................................................28 4.6.16 isConnected...............................................28 4.6.17 read......................................................28 4.6.18 search....................................................29 4.6.19 setConstraints............................................29 4.6.20 setInputStream............................................30 4.6.21 setOutputStream...........................................30 4.6.22 setProperty...............................................30 4.6.23 setSearchConstraints......................................30 4.6.24 setSocketFactory..........................................30 4.7 public class LDAPConstraints...................................31 4.7.1 Constructors................................................31 4.7.2 getHopLimit.................................................32 4.7.3 getBindProc.................................................33 4.7.4 getRebindProc...............................................33 4.7.5 getReferrals................................................33 4.7.6 getTimeLimit................................................33 4.7.7 setHopLimit.................................................33 4.7.8 setBindProc.................................................33 4.7.9 setRebindProc...............................................34 4.7.10 setReferrals..............................................34 4.7.11 setTimeLimit..............................................34 4.7.12 getClientControls.........................................34 4.7.13 getServerControls.........................................35 4.7.14 setClientControls.........................................35 4.7.15 setServerControls.........................................35 4.8 public class LDAPControl.......................................35 4.8.1 Constructors................................................36 4.8.2 clone.......................................................36 4.8.3 getID.......................................................36 4.8.4 getValue....................................................36 4.8.5 isCritical..................................................36 4.8.6 newInstance.................................................36 4.8.7 register....................................................37 4.9 public class LDAPDN............................................37 4.9.1 equals......................................................37 4.9.2 escapeRDN...................................................37 4.9.3 unescapeRDN.................................................37 4.9.4 explodeDN...................................................38 4.9.5 explodeRDN..................................................38 4.10 public class LDAPEntry.........................................38 4.10.1 Constructors..............................................39 4.10.2 getAttribute..............................................39 Expires July 3, 2000 [Page 3] JAVA LDAP API January 2000 4.10.3 getAttributeSet...........................................39 4.10.4 getDN.....................................................40 4.11 public class LDAPExtendedOperation.............................40 4.11.1 Constructors..............................................40 4.11.2 getID.....................................................40 4.11.3 getValue..................................................41 4.12 public interface LDAPEntryComparator...........................41 4.12.1 isGreater.................................................41 4.13 public class LDAPException.....................................41 4.13.1 Constructors..............................................41 4.13.2 errorCodeToString.........................................42 4.13.3 getLDAPErrorMessage.......................................42 4.13.4 getLDAPResultCode.........................................43 4.13.5 getMatchedDN..............................................43 4.13.6 Error codes...............................................43 4.14 public class LDAPMatchingRuleSchema............................44 4.14.1 Constructors..............................................45 4.14.2 getAttributes.............................................46 4.15 public class LDAPModification..................................46 4.15.1 Constructors..............................................46 4.15.2 getAttribute..............................................46 4.15.3 getOp.....................................................46 4.16 public class LDAPModificationSet...............................47 4.16.1 Constructors..............................................47 4.16.2 add.......................................................47 4.16.3 elementAt.................................................47 4.16.4 remove....................................................47 4.16.5 removeElementAt...........................................48 4.16.6 size......................................................48 4.17 public class LDAPObjectClassSchema.............................48 4.17.1 Constructors..............................................48 4.17.2 getSuperiors..............................................49 4.17.3 getRequiredAttributes.....................................49 4.17.4 getOptionalAttributes.....................................49 4.17.5 getType...................................................50 4.18 public class LDAPRebindAuth....................................50 4.18.1 Constructors..............................................50 4.18.2 getDN.....................................................50 4.18.3 getPassword...............................................50 4.19 public interface LDAPRebind....................................50 4.19.1 getRebindAuthentication...................................51 4.20 public class LDAPReferralException.............................51 4.20.1 Constructors..............................................51 4.20.2 getURLs...................................................52 4.21 public class LDAPSchema........................................52 4.21.1 Constructors..............................................52 4.21.2 fetchSchema...............................................52 4.21.3 getAttribute..............................................53 4.21.4 getObjectClass............................................53 4.21.5 getMatchingRule...........................................53 4.21.6 getAttributes.............................................53 4.21.7 getObjectClasses..........................................53 Expires July 3, 2000 [Page 4] JAVA LDAP API January 2000 4.21.8 getMatchingRules..........................................54 4.21.9 getAttributeNames.........................................54 4.21.10 getObjectClassNames.......................................54 4.21.11 getMatchingRuleNames......................................54 4.22 public abstract class LDAPSchemaElement........................54 4.22.1 getAliases................................................54 4.22.2 getDescription............................................54 4.22.3 getName...................................................55 4.22.4 getID.....................................................55 4.22.5 getQualifier..............................................55 4.22.6 getQualifierNames.........................................55 4.22.7 isObsolete................................................55 4.22.8 getValue..................................................55 4.22.9 setQualifier..............................................56 4.22.10 add.......................................................56 4.22.11 remove....................................................56 4.22.12 modify....................................................57 4.23 public class LDAPSearchConstraints extends LDAPConstraints.....57 4.23.1 Constructors..............................................57 4.23.2 getBatchSize..............................................59 4.23.3 getDereference............................................59 4.23.4 getMaxResults.............................................59 4.23.5 getServerTimeLimit........................................59 4.23.6 setBatchSize..............................................59 4.23.7 setDereference............................................60 4.23.8 setMaxResults.............................................60 4.23.9 setServerTimeLimit........................................60 4.24 public class LDAPSearchResults.................................60 4.24.1 getCount..................................................60 4.24.2 getResponseControls.......................................61 4.24.3 hasMoreElements...........................................61 4.24.4 next......................................................61 4.24.5 nextElement...............................................61 4.24.6 sort......................................................61 4.25 public interface LDAPSocketFactory.............................62 4.25.1 makeSocket................................................62 4.26 public class LDAPSortKey.......................................63 4.26.1 Constructors..............................................63 4.26.2 getKey....................................................63 4.26.3 getReverse................................................64 4.26.4 getMatchRule..............................................64 4.27 public class LDAPUrl...........................................64 4.27.1 Constructors..............................................64 4.27.2 decode....................................................65 4.27.3 encode....................................................65 4.27.4 getAttributes.............................................65 4.27.5 getAttributes.............................................66 4.27.6 getDN.....................................................66 4.27.7 getFilter.................................................66 4.27.8 getHost...................................................66 4.27.9 getPort...................................................66 4.27.10 getUrl....................................................66 Expires July 3, 2000 [Page 5] JAVA LDAP API January 2000 4.28 public interface LDAPv2........................................66 4.28.1 abandon...................................................67 4.28.2 add.......................................................67 4.28.3 bind......................................................67 4.28.4 compare...................................................68 4.28.5 connect...................................................68 4.28.6 delete....................................................69 4.28.7 disconnect................................................70 4.28.8 getOption.................................................70 4.28.9 modify....................................................70 4.28.10 read......................................................71 4.28.11 rename....................................................71 4.28.12 search....................................................72 4.28.13 setOption.................................................73 4.29 public interface LDAPv3........................................77 4.29.1 bind......................................................78 4.29.2 connect...................................................79 4.29.3 extendedOperation.........................................80 4.29.4 getResponseControls.......................................80 4.29.5 rename....................................................81 4.30 Client and Server Controls.....................................81 5. Security Considerations.........................................82 6. Acknowledgements................................................82 7. Bibliography....................................................82 8. Authors' Addresses..............................................83 9. Appendix A - Sample java LDAP programs..........................85 10. Appendix B - Changes from ldap-java-api-08.txt..................89 10.1 Standards track................................................89 10.2 SASL references................................................89 10.3 LDAPv2.........................................................89 11. Appendix C - Changes from ldap-java-api-07.txt..................89 11.1 LDAPAttributeSchema............................................89 11.2 LDAPConnection.................................................89 11.3 LDAPSchemaElement..............................................89 12. Appendix D - Changes from ldap-java-api-06.txt..................90 12.1 LDAPAttributeSchema............................................90 12.2 LDAPConnection.................................................90 12.3 LDAPDN.........................................................90 12.4 LDAPException..................................................90 12.5 LDAPMatchingRuleSchema.........................................90 12.6 LDAPObjectClassSchema..........................................90 12.7 LDAPSchemaElement..............................................90 13. Appendix E - Changes from ldap-java-api-05.txt..................91 13.1 LDAPConnection.................................................91 13.2 LDAPConstraints................................................91 13.3 LDAPSearchConstraints..........................................91 13.4 LDAPControl....................................................91 13.5 LDAPv3.........................................................91 14. Appendix F - Changes from ldap-java-api-04.txt..................91 14.1 LDAPAttribute..................................................91 14.2 LDAPCompareAttrNames...........................................91 14.3 LDAPSchemaElement..............................................91 Expires July 3, 2000 [Page 6] JAVA LDAP API January 2000 14.4 LDAPSchemaElement..............................................92 15. Appendix G - Changes from ldap-java-api-03.txt..................92 15.1 LDAPBind.......................................................92 15.2 LDAPControl....................................................92 15.3 LDAPConstraints................................................92 15.4 LDAPRebind.....................................................92 15.5 LDAPRebindProc.................................................92 15.6 LDAPSearchConstraints..........................................92 15.7 LDAPSearchResults..............................................92 15.8 LDAPv2.........................................................92 15.9 LDAPv3.........................................................93 16. Appendix H - Changes from ldap-java-api-02.txt..................93 16.1 LDAPSearchConstraints..........................................93 16.2 LDAPRebind.....................................................93 16.3 LDAPRebindProc.................................................93 17. Appendix I - Changes from ldap-java-api-01.txt..................93 17.1 LDAPAttribute..................................................93 17.2 LDAPAttributeSet...............................................93 17.3 LDAPDN.........................................................93 17.4 LDAPException..................................................93 17.5 LDAPSearchResults..............................................94 17.6 LDAPConnection.................................................94 17.7 LDAPv2.........................................................94 17.8 LDAPv3.........................................................94 Expires July 3, 2000 [Page 7] JAVA LDAP API January 2000 Introduction The LDAP class library is designed to provide powerful, yet simple, access to a LDAP directory services. It defines a synchronous interface to LDAP, with support for partial results on searching, to suit a wide variety of applications. This document gives a brief overview of the LDAP model, then an overview of the constituents of the class library. The public class methods are described in detail, followed by an appendix that provides some example code demonstrating the use of the classes, and an appendix listing changes from earlier drafts. 1. Overview of the LDAP model LDAP is the lightweight directory access protocol, described in [2] and [5]. It defines a lightweight access mechanism in which clients send requests to and receive responses from LDAP servers. The LDAP information model comes from X.500 [1] and is based on the entry, which contains information about some object (e.g., a person). Entries are composed of attributes, which have a type and one or more values. Each attribute has a syntax that determines what kinds of values are allowed in the attribute (e.g., ASCII characters, a jpeg photograph, etc.) and how those values behave during directory operations (e.g., is case significant during comparisons). Entries may be organized in a tree structure, usually based on political, geographical, and organizational boundaries. Other structures are possible, including a flat namespace. Each entry is uniquely named relative to its sibling entries by its relative distinguished name (RDN) consisting of one or more distinguished attribute values from the entry. At most one value from each attribute may be used in the RDN. For example, the entry for the person Babs Jensen might be named with the "Barbara Jensen" value from the commonName attribute. A globally unique name for an entry, called a distinguished name or DN, is constructed by concatenating the sequence of RDNs from the entry up to the root of the tree. For example, if Babs worked for the University of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, o=University of Michigan, c=US". The DN format used by LDAP is defined in [4]. Operations are provided to authenticate, search for and retrieve information, modify information, and add and delete entries from the tree. An LDAP server may return referrals if it cannot completely service a request (for example if the request specifies a directory base outside of the tree managed by the server). The LDAP class library offers the programmer two options: the programmer can catch these Expires July 3, 2000 [Page 8] JAVA LDAP API January 2000 referrals as exceptions and explicitly issue new requests to the referred-to servers, or the programmer can let the library automatically follow the referrals. In the latter case, the programmer may also provide a reauthentication object, allowing automatic referrals to proceed with appropriate credentials (as opposed to anonymous authentication) for each referred to server. 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. Then, when the values are received by the server, the values are converted back to 16-bit Unicodeformat. The integrity of double-byte and other non-ASCII character sets is fully preserved. The next sections give an overview of how the class library is used and detailed descriptions of the LDAP class methods that implement all of these functions. 2. Overview of the LDAP classes The central LDAP class is LDAPConnection. It provides methods to establish an authenticated or anonymous connection to an LDAP server, as well as methods to search for, modify, compare, and delete entries in the directory. The LDAPConnection class also provides fields for storing settings that are specific to the LDAP session (such as limits on the number of results returned or timeout limits). An LDAPConnection object can be cloned, allowing objects to share a single network connection but use different settings (using LDAPConnection.setOption()). To support extensions of the LDAP protocol LDAPConnection and to add the capability to determine the LDAP protocol level supported by an LDAPConnection object, LDAPConnection implements a protocol interface, which is currently LDAPv3. A search conducted by an LDAPConnection object returns results in an LDAPSearchResults object, which can be enumerated to access the entries found. Each entry (represented by an LDAPEntry object) provides access to the attributes (represented by LDAPAttribute objects) returned for that entry. Each attribute can produce the values found as byte arrays or as Strings. 2.1 Interfaces LDAPEntryComparator An interface to support arbitrary sorting algorithms for entries returned by a search operation. The basic java LDAP classes include one implementation: Expires July 3, 2000 [Page 9] JAVA LDAP API January 2000 LDAPCompareAttrNames, to sort in ascending order based on one or more attribute names. LDAPRebind A programmer desiring reauthentication on automatically following referrals must implement this interface. Without it, automatically followed referrals will use anonymous authentication. Referrals of any type other than to an LDAP server (i.e. a referral URL other than ldap://something) are ignored on automatic referral following. LDAPBind This interface allows a programmer to override the default authentication and reauthentication (on referral following) behavior of a connection. It is typically used to control the authentication mechanism used on implicit referral handling. LDAPSocketFactory Programmers needing to provide or use specialized socket connections, including Transport Layer Security (TLS) based ones, can provide an object constructor to implement them using this interface. LDAPv2 This interface defines the functionality of the LDAP version 2 protocol. It is implemented by LDAPConnection. LDAPv3 This interface extends LDAPv2, adding the functionality of the LDAP version 3 protocol. It is implemented by LDAPConnection. 2.2 Classes LDAPAttribute Represents the name and values of one attribute of a directory entry. LDAPAttributeSchema Represents the schematic definition of a particular attribute in a particular Directory Server. LDAPAttributeSet A collection of LDAPAttributes. Expires July 3, 2000 [Page 10] JAVA LDAP API January 2000 LDAPCompareAttrNames An implementation of LDAPEntryComparator, to support sorting of search results by one or more attributes. LDAPConnection Implements LDAPv3 and is the central point for interactions with a directory. LDAPConstraints Defines options controlling all operations. LDAPControl Sets additional parameters or constraints for an LDAP operation, either on the server or on the client. LDAPDN A utility class to facilitate composition and decomposition of distinguished names (DNs). LDAPEntry Represents a single entry in a directory. LDAPExtendedOperation Encapsulates the ID and data associated with the sending or receiving of an extended operation (an LDAPv3 feature). LDAPMatchingRuleSchema Represents the schematic definition of a particular matching rule in a particular Directory Server. LDAPModification A single add/delete/replace operation to an LDAPAttribute. LDAPModificationSet A collection of LDAPModifications. LDAPObjectClassSchema Represents the schematic definition of a particular object class in a particular Directory Server. LDAPRebindAuth An implementation of LDAPRebind must be able to provide an LDAPRebindAuth at the time of a referral. The class encapsulates reauthentication credentials. Expires July 3, 2000 [Page 11] JAVA LDAP API January 2000 LDAPSchema Represents the schema of a particular Directory Server. LDAPSchemaElement Base class for representing LDAP schema elements. LDAPSearchConstraints Defines the options controlling search operations. LDAPSearchResults The enumerable results of a search operation. LDAPSortKey Specifies how search results are to be sorted. LDAPUrl Encapsulates parameters of an LDAP Url query, as defined in [6]. 2.3 Exceptions LDAPException General exception, which includes an error message and an LDAP error code. LDAPReferralException Derived from LDAPException and contains a list of LDAPUrls corresponding to referrals received on an LDAP operation. 3. Overview of LDAP API use An application generally uses the LDAP API in four steps. - Construct an LDAPConnection. Initialize an LDAP session with a directory server. The LDAPConnection.connect() call establishes a handle to the session, allowing multiple sessions to be open at once, on different instances of LDAPConnection. - Authenticate to the LDAP server with LDAPConnection.bind(). - Perform some LDAP operations and obtain some results. LDAPConnection.search() returns an LDAPSearchResults, which can be enumerated to access all entries found. LDAPConnection.read() returns a single entry. Expires July 3, 2000 [Page 12] JAVA LDAP API January 2000 - Close the connection. The LDAPConnection.disconnect() call closes the connection. All operations described in this draft are synchronous - they do not return until the operation has completed. To facilitate user feedback during 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. The companion document draft-ietf- ldapext-ldap-java-api-asynch-ext-02.txt [19] defines low-level asynchronous versions of the LDAP operation methods. Standard java Enumerations are used to parse search results. Errors result in the throwing of an LDAPException, with a specific error code and context-specific textual information available. The following sections describe the LDAP classes in more detail. 4. The java LDAP classes 4.1 public class LDAPAttribute The LDAPAttribute class represents the name and values of an attribute. It is used to specify an attribute to be added to, deleted from, or modified in a Directory entry. It is also returned on a search of a Directory. 4.1.1 Constructors public LDAPAttribute(LDAPAttribute attr) 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) Expires July 3, 2000 [Page 13] JAVA LDAP API January 2000 Constructs an attribute that has a single string value. public LDAPAttribute(String attrName, String attrStrings[]) Constructs an attribute that has an array of string values. Parameters are: attr An attribute to use as template. attrName Name of the attribute. attrBytes Value of the attribute as raw bytes. attrString Value of the attribute as a String. attrStrings Array of values as Strings. 4.1.2 addValue public synchronized void addValue(String attrString) Adds a string value to the attribute. public synchronized 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. 4.1.3 getByteValues public Enumeration getByteValues() Returns an enumerator for the values of the attribute in byte[] format. 4.1.4 getStringValues public Enumeration getStringValues() Expires July 3, 2000 [Page 14] JAVA LDAP API January 2000 Returns an enumerator for the string values of an attribute. 4.1.5 getByteValueArray public byte[][] getByteValueArray() Returns the values of the attribute as an array of byte[]. 4.1.6 getStringValueArray public String[] getStringValueArray() Returns the values of the attribute as an array of Strings. 4.1.7 getLangSubtype public String getLangSubtype() Returns the language subtype, if any. For example, if the attribute name is cn;lang-ja;phonetic, this method returns the String lang-ja. 4.1.8 getBaseName public String getBaseName() public static String getBaseName(String attrName) Returns the base name. For example, if the attribute name is cn;lang- ja;phonetic, this method returns cn. attrName Name of the attribute to extract the base name from. 4.1.9 getName public String getName() Returns the name of the attribute. 4.1.10 getSubtypes public String[] getSubtypes() public static String[] getSubtypes(String attrName) Expires July 3, 2000 [Page 15] JAVA LDAP API January 2000 Extracts the subtypes from the specified attribute name. For example, if the attribute name is cn;lang-ja;phonetic, this method returns an array containing lang-ja and phonetic. Parameters are: attrName Name of the attribute to extract the subtypes from. 4.1.11 hasSubtype public boolean hasSubtype(String subtype) Reports if the attribute name contains the specified subtype. For example, if you check for the subtype lang-en and the attribute name is cn;lang-en, this method returns true. Parameters are: subtype The single subtype to check for. 4.1.12 hasSubtypes public boolean hasSubtypes(String[] subtypes) Reports if the attribute name contains all specified subtypes. For example, if you check for the subtypes lang-en and phonetic and if the attribute name is cn;lang-en;phonetic, this method returns true. If the attribute name is cn;phonetic or cn;lang-en, this method returns false. Parameters are: subtypes An array of subtypes to check for. 4.1.13 removeValue public synchronized void removeValue(String attrString) Removes a string value from the attribute. public synchronized void removeValue(byte attrBytes[]) Removes a byte[]-formatted value from the attribute. Parameters are: attrString Value of the attribute as a String. Expires July 3, 2000 [Page 16] JAVA LDAP API January 2000 attrBytes Value of the attribute as raw bytes. 4.1.14 size public int size() Returns the number of values of the attribute. 4.2 public class LDAPAttributeSchema extends LDAPSchemaElement The LDAPAttributeSchema class represents the definition of an attribute. It is used to query attribute syntax, and to add or delete an attribute definition in a Directory. See [2] for a description of attribute representation in LDAP. 4.2.1 Constructors public LDAPAttributeSchema(String name, String oid, String description, String syntaxString, boolean single String superior, String[] aliases) Constructs an attribute definition for adding to or deleting from a Directory. public LDAPAttributeSchema(String raw) Constructs an attribute definition from the raw String value returned on a Directory query for "attributetypes". Parameters are: name Name of the attribute. oid Unique Object Identifer of the attribute - in dotted numerical format. description Optional description of the attribute. syntaxString Unique Object Identifer of the syntax of the attribute - in dotted numerical format. Expires July 3, 2000 [Page 17] JAVA LDAP API January 2000 single True if the attribute is to be single-valued. superior Optional name of the attribute type which this attribute type derives from; null if there is no superior attribute type. aliases Optional list of additional names by which the attribute may be known; null if there are no aliases. raw The raw String value returned on a Directory query for "attributetypes". 4.2.2 getSyntaxString public String getSyntaxString() Returns the Unique Object Identifer of the syntax of the attribute in dotted numerical format. 4.2.3 getSuperior public String getSuperior() Returns the name of the attribute type which this attribute derives from, or null if there is no superior attribute. 4.2.4 isSingleValued public boolean isSingleValued() Returns true if the attribute is single-valued. 4.3 public class LDAPAttributeSet implements Cloneable An LDAPAttributeSet is a collection of LDAPAttributes, as returned in an entry on a search or read operation, or used to construct an entry to be added to a directory. 4.3.1 Constructors public LDAPAttributeSet() Constructs a new set of attributes. This set is initially empty. Expires July 3, 2000 [Page 18] JAVA LDAP API January 2000 4.3.2 add public synchronized void add(LDAPAttribute attr) Adds the specified attribute to this attribute set. Parameters are: attr Attribute to add to this set. 4.3.3 clone public Object clone() Returns a deep copy of this attribute set. 4.3.4 elementAt public LDAPAttribute elementAt(int index) throws ArrayIndexOutOfBoundsException Returns the attribute at the position specified by the index. The index is 0-based. Parameters are: index Index of the attribute to get. 4.3.5 getAttribute public LDAPAttribute[] getAttribute(String attrName) Returns the attribute matching the specified attrName. For example, getAttribute("cn") returns only the "cn" attribute getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute. In both cases, null is returned if there is no exact match to the specified attrName. public LDAPAttribute[] getAttribute(String attrName, String lang) Returns a single best-match attribute, or none if no match is available in the entry. LDAP version 3 allows adding a subtype specification to an attribute name. "cn;lang-ja", for example, indicates a Japanese language Expires July 3, 2000 [Page 19] JAVA LDAP API January 2000 subtype of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype of "cn;lang-ja". This feature may be used to provide multiple localizations in the same Directory. For attributes which do not vary among localizations, only the base attribute may be stored, whereas for others there may be varying degrees of specialization. getAttribute(attrName,lang) returns the subtype that matches attrName and that best matches lang. If there are subtypes other than "lang" subtypes included in attrName, e.g. "cn;binary", only attributes with all of those subtypes are returned. If lang is null or empty, the method behaves as getAttribute(attrName). If there are no matching attributes, null is returned. Example: Assume the entry contains only the following attributes: cn;lang-en cn;lang-ja-JP-kanji sn getAttribute( "cn" ) returns null. getAttribute( "sn" ) returns the "sn" attribute. getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute. getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute. getAttribute( "cn", "lang-ja" ) returns null. getAttribute( "sn", "lang-en" ) returns the "sn" attribute. Parameters are: attrName The name of an attribute to retrieve, with or without subtype specification(s). "cn", "cn;phonetic", and cn;binary" are valid attribute names. lang A language specification as in [9], with optional subtypes appended using "-" as separator. "lang- en", "lang-en-us", "lang-ja", and "lang-ja-JP- kanji" are valid language specification. 4.3.6 getAttributes public Enumeration getAttributes() Returns an enumeration of the attributes in this attribute set. 4.3.7 getSubset public LDAPAttributeSet getSubset(String subtype) Expires July 3, 2000 [Page 20] JAVA LDAP API January 2000 Creates a new attribute set containing only the attributes that have the specified subtypes. For example, suppose an attribute set contains the following attributes: cn cn;lang-ja sn;phonetic;lang-ja sn;lang-us Calling the getSubset method and passing lang-ja as the argument, the method returns an attribute set containing the following attributes: cn;lang-ja sn;phonetic;lang-ja Parameters are: subtype - Semi-colon delimited list of subtypes to include. For example: "lang-ja" // Only Japanese language subtypes "binary" // Only binary subtypes "binary;lang-ja" // Only Japanese language subtypes which also are binary 4.3.8 remove public synchronized void remove(String name) Removes the specified attribute from the set. If the attribute is not a member of the set, nothing happens. Parameters are: name Name of the attribute to remove from this set. To remove an LDAPAttribute by object, the LDAPAttribute.getName method can be used: LDAPAttributeSet.remove( attr.getName() ); 4.3.9 removeElementAt public void removeElementAt(int index) throws ArrayIndexOutOfBoundsException Expires July 3, 2000 [Page 21] JAVA LDAP API January 2000 Removes the attribute at the position specified by the index. The index is 0-based. Parameters are: index Index of the attribute to remove. 4.3.10 size public int size() Returns the number of attributes in this set. 4.4 public interface LDAPBind 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 the LDAPConstraints object) or for all operations (through LDAPConnection.setOption()). 4.4.1 bind public void bind (LDAPConnection conn) throws LDAPException This method is called by LDAPConnection when authenticating. An implementation may access the host, port, credentials, and other information in the LDAPConnection to decide on an appropriate authentication mechanism, and/or may interact with a user or external module. An LDAPException is thrown on failure, as in LDAPConnection.bind(). Parameters are: conn An established connection to an LDAP server. 4.5 public class LDAPCompareAttrNames implements LDAPEntryComparator An object of this class supports sorting search results by attribute name, in ascending or descending order. 4.5.1 Constructors public LDAPCompareAttrNames(String attrName) Expires July 3, 2000 [Page 22] JAVA LDAP API January 2000 Constructs an object that will sort results by a single attribute, in ascending order. public LDAPCompareAttrNames(String attrName, boolean ascendingFlag) Constructs an object that will sort results by a single attribute, in either ascending or descending order. public LDAPCompareAttrNames(String[] attrNames) Constructs an object that will sort by one or more attributes, in the order provided, in ascending order. public LDAPCompareAttrNames(String[] attrNames, boolean[] ascendingFlags) throws LDAPException Constructs an object that will sort by one or more attributes, in the order provided, in either ascending or descending order for each attribute. Parameters are: attrName Name of an attribute to sort by. attrNames Array of names of attributes to sort by. ascendingFlag true to sort in ascending order, false for descending order. ascendingFlags Array of flags, one for each attrName, where each one is true to sort in ascending order, false for descending order. An LDAPException is thrown if the length of ascendingFlags is not greater than or equal to the length of attrNames. 4.5.2 getLocale public Locale getLocale () Returns the Locale to be used for sorting, if a Locale has been specified. If null, a basic String.compareTo() is used for collation. If non-null, a Locale-specific collation is used. 4.5.3 setLocale Expires July 3, 2000 [Page 23] JAVA LDAP API January 2000 public void setLocale (Locale locale) Sets the Locale to be used for sorting. Parameters are: locale The Locale to be used for sorting. 4.5.4 isGreater public boolean isGreater (LDAPEntry entry1, LDAPEntry entry2) Returns true if entry1 is to be considered greater than entry2, for the purpose of sorting, based on the attribute name or names provided on object construction. Parameters are: entry1 Target entry for comparison. entry2 Entry to be compared to. 4.6 public class LDAPConnection implements LDAPv3, Cloneable LDAPConnection is the central class that encapsulates the connection to a Directory Server through the LDAP protocol. It implements the LDAPv2 and LDAPv3 interfaces. 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. Besides the methods described for LDAPv2 and LDAPv3, LDAPConnection provides the following methods. 4.6.1 Constructors public LDAPConnection() Constructs a new LDAPConnection object, which represents a connection to an LDAP server. Calling the constructor does not actually establish the connection. To connect to the LDAP server, use the connect method. public LDAPConnection(LDAPSocketFactory factory) Expires July 3, 2000 [Page 24] JAVA LDAP API January 2000 Constructs a new LDAPConnection object, which will use the supplied class factory to construct a socket connection during LDAPConnection.connect(). Parameters are: factory An object capable of producing a Socket. 4.6.2 clone public Object clone() Returns a copy of the object with a private context, but sharing the network connection if there is one. The network connection remains open until all clones have disconnected or gone out of scope. Any connection opened after cloning is private to the object making the connection. The clone can freely modify options and search constraints, and issue requests, without affecting the source object or other clones. If the clone disconnects or reconnects, it is completely dissociated from the source object and other clones. Reauthenticating in a clone, however, is a global operation which will affect the source object and all associated clones, because it applies to the single shared physical connection. Any request by an associated object after one has reauthenticated will carry the new identity. 4.6.3 finalize public void finalize() throws LDAPException Closes the connection if open and releases any other resources held by the object. 4.6.4 getAuthenticationDN public String getAuthenticationDN() Returns the distinguished name (DN) used for authentication by this object. null is returned if no authentication has been performed. 4.6.5 getAuthenticationMethod public String getAuthenticationMethod() Returns the method used to authenticate the connection. The return value is one of the following: Expires July 3, 2000 [Page 25] JAVA LDAP API January 2000 "none" If the connection is not authenticated "simple" If simple authentication was used, also if a null or empty authentication DN was specified "sasl" If a SASL mechanism was used to authenticate 4.6.6 getAuthenticationPassword public String getAuthenticationPassword() Returns the password used for simple authentication by this object. null is returned if no authentication has been performed. 4.6.7 getHost public String getHost() Returns the host name of the LDAP server to which the object is or was last connected, in the format originally specified. 4.6.8 getInputStream public InputStream getInputStream() Returns the stream used by the connection object for receiving data from the LDAP server. 4.6.9 getOutputStream public OutputStream getOutputStream() Returns the stream used by the connection object to send data to the LDAP server. 4.6.10 getPort public int getPort() Returns the port number of the LDAP server to which the object is or was last connected. 4.6.11 getProperty public Object getProperty(String name) throws LDAPException Expires July 3, 2000 [Page 26] JAVA LDAP API January 2000 Gets a property of a connection object. Parameters are: name Name of the property to be returned. The following read-only properties are available for any given connection: LDAP_PROPERTY_SDK The version of this SDK, as a Float data type. LDAP_PROPERTY_PROTOCOL The highest supported version of the LDAP protocol, as a Float data type. LDAP_PROPERTY_SECURITY A comma-separated list of the types of authentication supported, as a String. Other properties may be available in particular implementations of the class, and used to modify operations such as search. A deep copy of the property is provided where applicable; a client does not need to clone the object received. An LDAPException is thrown if the requested property is not available. 4.6.12 getConstraints public LDAPConstraints getConstraints() Returns the set of constraints that apply to all operations performed through this connection (unless a different set of constraints is specified when calling an operation method). Note that the getOption method can be used to get individual constraints (rather than getting the entire set of constraints). 4.6.13 getSearchConstraints Expires July 3, 2000 [Page 27] JAVA LDAP API January 2000 public LDAPSearchConstraints getSearchConstraints() Returns the set of constraints that apply to search operations performed through this connection (unless a different set of constraints is specified when calling the search operation method). 4.6.14 getSocketFactory public LDAPSocketFactory getSocketFactory() Returns the LDAPSocketFactory used to establish a connection to a server. 4.6.15 isBound public boolean isBound() Indicates whether the object has authenticated to the connected LDAP server. 4.6.16 isConnected public boolean isConnected() Indicates whether the connection represented by this object is open at this time. 4.6.17 read 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 filter and scope, these are not used. Of the information specified in the URL, this method only uses the LDAP host name and port number, the base distinguished name (DN), and the list of attributes to return. The method returns the entry specified by the base DN. Expires July 3, 2000 [Page 28] JAVA LDAP API January 2000 Parameters are: toGet LDAP URL specifying the entry to read. cons Constraints specific to the operation. 4.6.18 search 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: toGet LDAP URL specifying the entry to read. cons Constraints specific to the search. 4.6.19 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). Note that the setOption method can be used to set individual constraints (rather than setting the entire set of constraints). Expires July 3, 2000 [Page 29] JAVA LDAP API January 2000 4.6.20 setInputStream public void setInputStream(InputStream stream) Sets the stream used by the connection object for receiving data from the LDAP server. 4.6.21 setOutputStream public void setOutputStream(OutputStream stream) Sets the stream used by the connection object to send data to the LDAP server. 4.6.22 setProperty public void setProperty(String name, Object value) throws LDAPException Sets a property of a connection object. No property names have been defined at this time, but the mechanism is in place in order to support revisional as well as dynamic extensions to operation modifiers. Parameters are: name Name of the property to set. value Value to assign to the property. An LDAPException is thrown if the specified property is not supported. 4.6.23 setSearchConstraints public void setSearchConstraints(LDAPSearchConstraints cons) Sets the constraints that apply to all search operations performed through this connection (unless a different set of constraints is specified when calling a search operation method). Typically, the setSearchConstraints method is used to create a slightly different set of search constraints to apply to a particular search. 4.6.24 setSocketFactory Expires July 3, 2000 [Page 30] JAVA LDAP API January 2000 public void setSocketFactory(LDAPSocketFactory factory) Establishes the default LDAPSocketFactory used to establish a connection to a server. This method is implemented as once-only. It is useful to be able to change the run-time connection behavior of a whole application with a single instruction, but the results would be confusing, and the side- effects dangerous, if the global default factory could be changed at arbitrary times by different threads. It should be called before the first connect(). If called (for the first time) after connecting, the new factory will not be used until/unless a new connection is attempted with the object. A typical usage would be: if (usingTLS) { LDAPConnection.setSocketFactory(myTLSFactory); } ... LDAPConnection conn = new LDAPConnection(); conn.connect(myHost, myPort); In this example, connections are constructed with the default LDAPSocketFactory. At application start-up time, the default may be set to use a particular provided TLS socket factory. Parameters are: factory A factory object which can construct socket connections for an LDAPConnection. 4.7 public class LDAPConstraints A set of options to control any operation. There is always an LDAPConstraints associated with an LDAPConnection object; its values can be changed with LDAPConnection.setOption, or overridden by passing an LDAPConstraints object to an operation. 4.7.1 Constructors public LDAPConstraints() Constructs an LDAPConstraints object that specifies the default set of constraints. public LDAPConstraints(int msLimit, boolean doReferrals, LDAPBind binder, Expires July 3, 2000 [Page 31] JAVA LDAP API January 2000 int hop_limit) public LDAPConstraints(int msLimit, boolean doReferrals, LDAPRebind reauth, int hop_limit) Constructs a new LDAPConstraints object and allows specifying the operational constraints in that object. Parameters are: msLimit Maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit). This is an interface-imposed limit. doReferrals Specify true to follow referrals automatically, or false to throw an LDAPReferralException error if the server sends back a referral (false by default). binder Custom authentication processor, called when the LDAPConnection needs to authenticate, typically on following a referral. null may be specified to indicate default authentication processing. reauth Specifies an object of the class that implements the LDAPRebind interface. The object will be used when the client follows referrals automatically. The object provides a method for getting the distinguished name and password used to authenticate to another LDAP server during a referral. Specifying null indicates the default LDAPRebind will be used if one has been assigned with LDAPConnection.setOption(), or anonymous authentication otherwise. hop_limit Maximum number of referrals to follow in a sequence when attempting to resolve a request, when doing automatic referral following. 4.7.2 getHopLimit public int getHopLimit() Returns the maximum number of hops to follow during automatic referral following. Expires July 3, 2000 [Page 32] JAVA LDAP API January 2000 4.7.3 getBindProc public LDAPBind getBindProc() Returns an object that can process authentication. It may be null. 4.7.4 getRebindProc public LDAPRebind getRebindProc() Returns the object that provides the method for getting authentication information. It may be null. 4.7.5 getReferrals public boolean getReferrals() Specifies whether nor not referrals are followed automatically. Returns true if referrals are to be followed automatically, or false if referrals throw an LDAPReferralException. 4.7.6 getTimeLimit public int getTimeLimit() Returns the maximum number of milliseconds to wait for any operation under these constraints. If 0, there is no maximum time limit on waiting for the operation results. The actual granularity of the timeout depends on the implementation. 4.7.7 setHopLimit public void setHopLimit(int hop_limit) Sets the maximum number of hops to follow in sequence during automatic referral following. The default is 5. Parameters are: hop_limit Maximum number of chained referrals to follow automatically. 4.7.8 setBindProc public void setBindProc(LDAPBind binder) Expires July 3, 2000 [Page 33] JAVA LDAP API January 2000 Specifies the object that will process authentication requests. The default is null. Parameters are: binder An object that implements LDAPBind. 4.7.9 setRebindProc public void setRebindProc(LDAPRebind reauth) Specifies the object that provides the method for getting authentication information. The default is null. If referrals is set to true, and the reauth is null, referrals will be followed with anonymous (= no) authentication. Parameters are: reauth An object that implements LDAPRebind. 4.7.10 setReferrals public void setReferrals(boolean doReferrals) Specifies whether nor not referrals are followed automatically, or if referrals throw an LDAPReferralException. Referrals of any type other than to an LDAP server (i.e. a referral URL other than ldap://something) are ignored on automatic referral following. The default is false. Parameters are: doReferrals True to follow referrals automatically. 4.7.11 setTimeLimit public void setTimeLimit(int msLimit) Sets the maximum number of milliseconds to wait for any operation under these search constraints. If 0, there is no maximum time limit on waiting for the operation results. The actual granularity of the timeout depends on the implementation. Parameters are: msLimit Maximum milliseconds to wait. 4.7.12 getClientControls Expires July 3, 2000 [Page 34] JAVA LDAP API January 2000 public LDAPControl[] getClientControls() Returns controls to be used by the interface. 4.7.13 getServerControls public LDAPControl[] getServerControls() Returns controls to be sent to the server. 4.7.14 setClientControls public void setClientControls( LDAPControl control ) public void setClientControls( LDAPControl[] controls ) Sets controls for use by the interface. Parameters are: control A single client control. controls An array of client controls. 4.7.15 setServerControls public void setServerControls( LDAPControl control ) public void setServerControls( LDAPControl[] controls ) Sets controls to be sent to the server. Parameters are: control A single control to be sent to the server. controls An array of controls to be sent to the server. 4.8 public class LDAPControl implements Cloneable An LDAPControl encapsulates optional additional parameters or constraints to be applied to LDAP operations. If set as a Server Control, it is sent to the server along with operation requests. If set as a Client Control, it is not sent to the server, but rather interpreted locally by the client. LDAPControl is an LDAPv3 extension, and is not supported in an LDAPv2 environment. Expires July 3, 2000 [Page 35] JAVA LDAP API January 2000 4.8.1 Constructors public LDAPControl(String id, boolean critical, byte vals[]) Parameters are: id The type of the Control, as a string. critical True if the LDAP operation should be discarded if the server does not support this Control. vals Control-specific data. 4.8.2 clone public Object clone() Returns a deep copy of the object. 4.8.3 getID public String getID() Returns the identifier of the control. 4.8.4 getValue public byte[] getValue() Returns the control-specific data of the object. 4.8.5 isCritical public boolean isCritical() Returns true if the control must be supported for an associated operation to be executed. 4.8.6 newInstance public static LDAPControl newInstance(byte[] data) Instantiates a control, given the raw data representing it in an LDAP message. Expires July 3, 2000 [Page 36] JAVA LDAP API January 2000 4.8.7 register public static void register(String oid, Class controlClass) Registers a class to be instantiated on receipt of a control with the given oid. Any previous registration for the oid is overridden. The controlClass must be an extension of LDAPControl. Parameters are: oid The Object Identifier of the Control. controlClass A class which can instantiate an LDAPControl. 4.9 public class LDAPDN A utility class representing a distinguished name (DN). 4.9.1 equals public static boolean equals (String dn1, String dn2) Returns true if the two strings correspond to the same DN, after appropriate normalization. Parameters are: dn1 String form of first DN to compare. dn2 String form of second DN to compare. 4.9.2 escapeRDN public static String escapeRDN (String rdn) Returns the RDN after escaping the characters requiring escaping [5]. For example, for the rdn ôcn=Acme, Incö, ôcn=Acme\, Incö is returned. Parameters are: rdn The RDN to escape. 4.9.3 unescapeRDN public static String unescapeRDN (String rdn) Expires July 3, 2000 [Page 37] JAVA LDAP API January 2000 Returns the RDN after unescaping the characters requiring escaping [5]. For example, for the rdn ôcn=Acme\, Incö, ôcn=Acme, Incö is returned. Parameters are: rdn The RDN to unescape. 4.9.4 explodeDN public static String[] explodeDN(String dn, boolean noTypes) Returns the individual components of a distinguished name (DN). Parameters are: dn Distinguished name, e.g. "cn=Babs Jensen,ou=Accounting,o=Acme,c=us" noTypes If true, returns only the values of the components, and not the names, e.g. "Babs Jensen", "Accounting", "Acme", "us" - instead of "cn=Babs Jensen", "ou=Accounting", "o=Acme", and "c=us". 4.9.5 explodeRDN public static String[] explodeRDN(String rdn, boolean noTypes) Returns the individual components of a relative distinguished name (RDN). Parameters are: rdn Relative distinguished name, i.e. the left-most component of a distinguished name. noTypes If true, returns only the values of the components, and not the names. 4.10 public class LDAPEntry An LDAPEntry represents a single entry in a directory, consisting of a distinguished name (DN) and zero or more attributes. An instance of LDAPEntry is created in order to add an entry to a Directory, and instances are returned on a search by enumerating an LDAPSearchResults. Expires July 3, 2000 [Page 38] JAVA LDAP API January 2000 4.10.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. attrs The initial set of attributes assigned to the entry. 4.10.2 getAttribute public LDAPAttribute[] getAttribute(String attrName) Returns the attributes matching the specified attrName. Parameters are: attrName The name of the attribute or attributes to return. See 4.3.5 for the syntax and semantics relevant to this parameter. 4.10.3 getAttributeSet public LDAPAttributeSet getAttributeSet() Returns the attribute set of the entry. All base and subtype variants of all attributes are returned. The LDAPAttributeSet returned may be empty if there are no attributes in the entry. Expires July 3, 2000 [Page 39] JAVA LDAP API January 2000 public LDAPAttributeSet getAttributeSet(String subtype) Returns an attribute set from the entry, consisting of only those attributes matching the specified subtype(s). This may be used to extract only a particular language variant subtype of each attribute, if it exists. "subtype" may be, for example, "lang-ja", "binary", or "lang-ja;phonetic". If more than one subtype is specified, separated with a semicolon, only those attributes with all of the named subtypes will be returned. The LDAPAttributeSet returned may be empty if there are no matching attributes in the entry. Parameters are: subtype One or more subtype specification(s), separated with semicolons. "lang-ja" and "lang-en;phonetic" are valid subtype specifications. 4.10.4 getDN public String getDN() Returns the distinguished name of the entry. 4.11 public class LDAPExtendedOperation An LDAPExtendedOperation encapsulates an ID which uniquely identifies a particular extended operation, known to a particular server, and the data associated with the operation. 4.11.1 Constructors public LDAPExtendedOperation(String oid, byte[] vals) Constructs a new object with the specified object ID and data. Parameters are: oid The unique identifier of the operation. vals The operation-specific data of the operation. 4.11.2 getID public String getID() Expires July 3, 2000 [Page 40] JAVA LDAP API January 2000 Returns the unique identifier of the operation. 4.11.3 getValue public byte[] getValue() Returns the operation-specific data (not a copy, a reference). 4.12 public interface LDAPEntryComparator An object of this class can implement arbitrary sorting algorithms for search results. 4.12.1 isGreater public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2) Returns true if entry1 is to be considered greater than or equal to entry2, for the purpose of sorting. Parameters are: entry1 Target entry for comparison. entry2 Entry to be compared to. 4.13 public class LDAPException extends Exception Thrown to indicate that an error has occurred. An LDAPException can result from physical problems (such as network errors) as well as problems with LDAP operations (for example, if the LDAP add operation fails because of a duplicate entry). Most errors that occur throw this type of exception. The getLDAPResultCode() method returns the specific result code, which can be compared against standard LDAP result codes as defined in [5], section 4. 4.13.1 Constructors public LDAPException() Constructs a default exception with no specific error information. Expires July 3, 2000 [Page 41] JAVA LDAP API January 2000 public LDAPException(String message, int resultCode) Constructs an exception with an error code and a specified string as additional information. Parameters are: message The additional error information. resultCode The result code returned 4.13.2 errorCodeToString public String errorCodeToString() Returns a String representing the internal error code, in the default Locale. public static String errorCodeToString( int code ) Returns a String representing an arbitrary error code, in the default Locale, or null if there is no such code. public String errorCodeToString( Locale locale ) Returns a String representing the internal error code, in the specified Locale, or null if a String representation is not available for the requested Locale. public static String errorCodeToString( int code, Locale locale ) Returns a String representing an arbitrary error code, in the specified Locale, or null if there is no such code or if a String representation is not available for the requested Locale. Parameters are: code One of the error codes listed in "Error codes" below. locale A Locale in which to render the error String. 4.13.3 getLDAPErrorMessage Expires July 3, 2000 [Page 42] JAVA LDAP API January 2000 public String getLDAPErrorMessage() Returns the error message, if this message is available (that is, if this message was set). If the message was not set, this method returns null. 4.13.4 getLDAPResultCode public int getLDAPResultCode() Returns the result code from the exception. The codes are defined as public final static int members of this class. If the exception is a result of error information returned from a directory operation, the code will be one of those defined in [5]. Otherwise, a local error code is returned (see "Error codes" below). 4.13.5 getMatchedDN public String getMatchedDN() Returns the part of a submitted distinguished name which could be matched by the server. If the exception was caused by a local error, such as no server available, the return value is null. If the exception resulted from an operation being executed on a server, the value is an empty String except when the result of the operation was one of the following: NO_SUCH_OBJECT ALIAS_PROBLEM INVALID_DN_SYNTAX ALIAS_DEREFERENCING_PROBLEM 4.13.6 Error codes See [5] for a discussion of the meanings of the codes. ADMIN_LIMIT_EXCEEDED AFFECTS_MULTIPLE_DSAS ALIAS_DEREFERENCING_PROBLEM ALIAS_PROBLEM ATTRIBUTE_OR_VALUE_EXISTS AUTH_METHOD_NOT_SUPPORTED BUSY COMPARE_FALSE COMPARE_TRUE CONFIDENTIALITY_REQUIRED CONSTRAINT_VIOLATION ENTRY_ALREADY_EXISTS INAPPROPRIATE_AUTHENTICATION Expires July 3, 2000 [Page 43] JAVA LDAP API January 2000 INAPPROPRIATE_MATCHING INSUFFICIENT_ACCESS_RIGHTS INVALID_ATTRIBUTE_SYNTAX INVALID_CREDENTIALS INVALID_DN_SYNTAX IS_LEAF LDAP_PARTIAL_RESULTS LOOP_DETECT NAMING_VIOLATION NO_SUCH_ATTRIBUTE NO_SUCH_OBJECT NOT_ALLOWED_ON_NONLEAF NOT_ALLOWED_ON_RDN OBJECT_CLASS_MODS_PROHIBITED OBJECT_CLASS_VIOLATION OPERATIONS_ERROR OTHER PROTOCOL_ERROR REFERRAL SASL_BIND_IN_PROGRESS SIZE_LIMIT_EXCEEDED STRONG_AUTH_REQUIRED SUCCESS TIME_LIMIT_EXCEEDED UNAVAILABLE UNAVAILABLE_CRITICAL_EXTENSION UNDEFINED_ATTRIBUTE_TYPE UNWILLING_TO_PERFORM Local errors, resulting from actions other than an operation on a server, are among the following, listed in [7]: AUTH_UNKNOWN CLIENT_LOOP CONNECT_ERROR CONTROL_NOT_FOUND DECODING_ERROR ENCODING_ERROR FILTER_ERROR LOCAL_ERROR LDAP_NOT_SUPPORTED LDAP_TIMEOUT MORE_RESULTS_TO_RETURN NO_MEMORY NO_RESULTS_RETURNED PARAM_ERROR REFERRAL_LIMIT_EXCEEDED SERVER_DOWN USER_CANCELLED 4.14 public class LDAPMatchingRuleSchema extends LDAPSchemaElement Expires July 3, 2000 [Page 44] JAVA LDAP API January 2000 The LDAPMatchingRuleSchema class represents the definition of a matching rule. It is used to query matching rule syntax, and to add or delete a matching rule definition in a Directory. See [2] for a description of matching rule representation in LDAP. 4.14.1 Constructors public LDAPMatchingRuleSchema(String name, String oid, String description, String[] attributes, String syntaxString, String[] aliases) Constructs a matching rule definition for adding to or deleting from a Directory. public LDAPMatchingRuleSchema(String rawMatchingRule, String rawMatchingRuleUse) Constructs a matching rule definition from the raw String values returned on a Directory query for "matchingRule" and for "matchingRuleUse" for the same rule. Parameters are: name Name of the attribute. oid Unique Object Identifer of the attribute - in dotted numerical format. description Optional description of the attribute. attributes OIDs of attributes to which the rule applies. syntaxString Unique Object Identifer of the syntax of the attribute - in dotted numerical format. aliases Optional list of additional names by which the matching rule may be known; null if there are no aliases. rawMatchingRule The raw String value returned on a Directory query for "matchingRule". rawMatchingRuleUse The raw String value returned on a Directory query for "matchingRuleUse". Expires July 3, 2000 [Page 45] JAVA LDAP API January 2000 4.14.2 getAttributes public String[] getAttributes() Returns the OIDs of the attributes to which this rule applies. 4.15 public class LDAPModification A single change specification for an LDAPAttribute. 4.15.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: LDAPModification.ADD The value should be added to the attribute LDAPModification.DELETE The value should be removed from the attribute LDAPModification.REPLACE The value should replace all existing values of the attribute attr The attribute (possibly with values) to be modified. 4.15.2 getAttribute public LDAPAttribute getAttribute() Returns the attribute (possibly with values) to be modified. 4.15.3 getOp public int getOp() Expires July 3, 2000 [Page 46] JAVA LDAP API January 2000 Returns the type of modification specified by this object. 4.16 public class LDAPModificationSet A collection of modifications to be made to the attributes of a single entry. 4.16.1 Constructors public LDAPModificationSet() Constructs a new, empty set of modifications. 4.16.2 add public synchronized void add(int op, LDAPAttribute attr) Specifies another modification to be added to the set of modifications. Parameters are: op The type of modification to make, as described for LDAPModification. attr The attribute (possibly with values) to be modified. 4.16.3 elementAt public LDAPModification elementAt(int index) throws ArrayIndexOutOfBoundsException Retrieves a particular LDAPModification object at the position specified by the index. Parameters are: index Index of the modification to get. 4.16.4 remove public synchronized void remove(String name) Removes the first attribute with the specified name in the set of modifications. Expires July 3, 2000 [Page 47] JAVA LDAP API January 2000 Parameters are: name Name of the attribute to be removed. 4.16.5 removeElementAt public void removeElementAt(int index) throws ArrayIndexOutOfBoundsException Removes a particular LDAPModification object at the position specified by the index. Parameters are: index Index of the modification to remove. 4.16.6 size public int size() Retrieves the number of LDAPModification objects in this set. 4.17 public class LDAPObjectClassSchema The LDAPObjectClassSchema class represents the definition of an object class. It is used to query the syntax of an object class, and to add or delete an object class definition in a Directory. See [2] for a description of object class representation in LDAP. 4.17.1 Constructors public LDAPObjectClassSchema(String name, String oid, String[] superiors, String description, String[] required, String[] optional, int type, String[] aliases) Constructs an object class definition for adding to or deleting from a Directory. public LDAPObjectClassSchema(String raw) Expires July 3, 2000 [Page 48] JAVA LDAP API January 2000 Constructs an object class definition from the raw String value returned on a Directory query for "objectclasses". Parameters are: name Name of the object class. oid Unique Object Identifer of the object class - in dotted numerical format. description Optional description of the object class. superiors The object classes this one derives from. required A list of attributes required for an entry with this object class. optional A list of attributes acceptable but not required for an entry with this object class. type One of ABSTRACT, AUXILIARY, or STRUCTURAL. These are constants defined in LDAPObjectClassSchema. aliases Optional list of additional names by which the object class may be known; null if there are no aliases. raw The raw String value returned on a Directory query for "objectclasses". 4.17.2 getSuperiors public String[] getSuperiors() Returns the object classes which this one derives from. 4.17.3 getRequiredAttributes public String[] getRequiredAttributes() Returns a list of attributes required of an entry with this object class. 4.17.4 getOptionalAttributes public String[] getOptionalAttributes() Expires July 3, 2000 [Page 49] JAVA LDAP API January 2000 Returns a list of attributes acceptable but not required of an entry with this object class. 4.17.5 getType public int getType() Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are constants defined in LDAPObjectClassSchema. 4.18 public class LDAPRebindAuth Represents information used to authenticate the client in cases where the client follows referrals automatically. 4.18.1 Constructors public LDAPRebindAuth ( String dn, String password ) Constructs information that is used by the client for authentication when following referrals automatically. Parameters are: dn Distinguished name to use in authenticating to the server. password Password to use in authenticating to the server. 4.18.2 getDN public String getDN() Returns the distinguished name to be used for reauthentication on automatic referral following. 4.18.3 getPassword public String getPassword() Returns the password to be used for reauthentication on automatic referral following. 4.19 public interface LDAPRebind Used to provide credentials for reauthentication on processing a referral. Expires July 3, 2000 [Page 50] JAVA LDAP API January 2000 4.19.1 getRebindAuthentication public LDAPRebindAuth getRebindAuthentication (String host, int port) Returns an object which can provide credentials for authenticating to a server at the provided host name and port number. Parameters are: host Contains a hostname or dotted string representing the IP address of a host running an LDAP server. port Contains the TCP or UDP port number to connect to. 4.20 public class LDAPReferralException extends LDAPException This exception, derived from LDAPException, is thrown when a server returns a referral and automatic referral following has not been enabled. 4.20.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, int resultCode, String serverMessage) Parameters are: message The additional error information. resultCode The result code returned serverMessage Error message specifying additional information from the server. Expires July 3, 2000 [Page 51] JAVA LDAP API January 2000 4.20.2 getURLs public LDAPUrl[] getURLs() Gets the list of referrals (LDAP URLs to other servers) returned by the LDAP server. This exception is only thrown, and therefor the URL list only available, if automatic referral following is not enabled. The referrals may include URLs of a type other than ones for an LDAP server (i.e. a referral URL other than ldap://something). 4.21 public class LDAPSchema The LDAPSchema supports querying a Directory Server for its schema, and obtaining definitions of individual schema elements. 4.21.1 Constructors public LDAPSchema() Constructs an empty LDAPSchema object. 4.21.2 fetchSchema public void fetchSchema(LDAPConnection ld) throws LDAPException Retrieves the entire schema from a Directory Server. public void fetchSchema(LDAPConnection ld, String dn) throws LDAPException Retrieves the schema in effect at a particular entry in the Directory Server. The fetchSchema methods are the only methods that interact with a Directory Server. The other methods access information acquired through fetchSchema. An LDAPException is thrown as for LDAPConnection.search() (4.28.12) if the schema cannot be retrieved with the specified connection. Parameters are: ld An open connection to a Directory Server. dn Distinguished name of the entry from which to return schema. The subschemasubentry attribute of the entry is queried to find the location of the schema to be returned. Expires July 3, 2000 [Page 52] JAVA LDAP API January 2000 4.21.3 getAttribute public LDAPAttributeSchema getAttribute( String name ) Returns a particular attribute definition, or null if not found. Parameters are: name Name of the attribute for which a definition is to be returned. 4.21.4 getObjectClass public LDAPObjectClassSchema getObjectClass( String name ) Returns a particular object class definition, or null if not found. Parameters are: name Name of the object class for which a definition is to be returned. 4.21.5 getMatchingRule public LDAPMatchingRuleSchema getMatchingRule( String name ) Returns a particular matching rule definition, or null if not found. Parameters are: name Name of the matching rule for which a definition is to be returned. 4.21.6 getAttributes public Enumeration getAttributes() Returns an enumeration of attribute definitions. 4.21.7 getObjectClasses public Enumeration getObjectClasses() Returns an enumeration of object class definitions. Expires July 3, 2000 [Page 53] JAVA LDAP API January 2000 4.21.8 getMatchingRules public Enumeration getMatchingRules() Returns an enumeration of matching rule definitions. 4.21.9 getAttributeNames public Enumeration getAttributeNames() Returns an enumeration of attribute names. 4.21.10 getObjectClassNames public Enumeration getObjectClassNames() Returns an enumeration of object class names. 4.21.11 getMatchingRuleNames public Enumeration getMatchingRuleNames() Returns an enumeration of matching rule names. 4.22 public abstract class LDAPSchemaElement The LDAPSchemaElement class is the base class for representing schema elements in LDAP. 4.22.1 getAliases public String[] getAliases() Returns an array of alternative names of the element, or null if there are none. With respect to the protocol-level schema element syntax definition of [2], the array consists of all values but the first of the NAME qualifier. 4.22.2 getDescription public String getDescription() Returns the description of the element. With respect to the protocol- level schema element syntax definition of [2], the value is that of the DESC qualifier. Expires July 3, 2000 [Page 54] JAVA LDAP API January 2000 4.22.3 getName public String getName() Returns the name of the element. With respect to the protocol-level schema element syntax definition of [2], the value is that of the first NAME qualifier. 4.22.4 getID public String getID() Returns the Unique Object Identifier of the element. 4.22.5 getQualifier public String[] getQualifier(String name) Returns an array of all values of a specified optional or non- standard qualifier of the element. This method may be used to access the values of vendor-specific qualifiers (which begin with "X-" [2]). Parameters are: name The name of the qualifier, case-sensitive. 4.22.6 getQualifierNames public Enumeration getQualifierNames() Returns an enumeration of all qualifiers of the element which are not defined in [2]. 4.22.7 isObsolete public boolean isObsolete() Returns true if the element is obsolete (has the OBSOLETE qualifier in its LDAP definition [2]. 4.22.8 getValue public String getValue() Returns a String in a format suitable for directly adding to a Directory, as a value of the particular schema element attribute. Expires July 3, 2000 [Page 55] JAVA LDAP API January 2000 4.22.9 setQualifier public void setQualifier(String name, String[] values) Sets the values of a specified optional or non-standard qualifier of the element. This method may be used to set the values of vendor- specific qualifiers (which begin with "X-" [2]). Parameters are: name The name of the qualifier, case-sensitive. values The values to set for the qualifier. 4.22.10 add public void add(LDAPConnection ld) throws LDAPException public void add(LDAPConnection ld, String dn) throws LDAPException Adds the definition to a Directory. An exception is thrown if the definition can't be added. Parameters are: ld An open connection to a Directory Server. Typically the connection must have been authenticated to add a schema definition. dn Entry at which to determine the SubschemaSubentry to which the schema element is to be added. 4.22.11 remove public void remove(LDAPConnection ld) throws LDAPException public void remove(LDAPConnection ld, String dn) throws LDAPException Removes the definition from a Directory. An exception is thrown if the definition can't be removed. Parameters are: ld An open connection to a Directory Server. Typically the connection must have been authenticated to remove a schema definition. Expires July 3, 2000 [Page 56] JAVA LDAP API January 2000 dn Entry at which to determine the SubschemaSubentry to remove the schema element from. 4.22.12 modify public void modify(LDAPConnection ld LDAPSchemaElement newValue) throws LDAPException public void modify(LDAPConnection ld LDAPSchemaElement newValue, String dn) throws LDAPException Replace a single value of the schema element definition in the schema. An exception is thrown if the definition can't be modified. Parameters are: ld An open connection to a Directory Server. Typically the connection must have been authenticated to modify a schema definition. newValue The new schema element value. dn Entry at which to determine the SubschemaSubentry to store the schema change in. 4.23 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.setOption, or overridden by passing an LDAPConstraints object to the search operation. 4.23.1 Constructors public LDAPSearchConstraints() Constructs an LDAPSearchConstraints object that specifies the default set of search constraints. public LDAPSearchConstraints(int msLimit, int serverTimeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPBind binder, Expires July 3, 2000 [Page 57] JAVA LDAP API January 2000 int hop_limit) public LDAPSearchConstraints(int msLimit, int serverTimeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPRebind reauth, int hop_limit) Constructs a new LDAPSearchConstraints object and allows specifying the operational constraints in that object. Parameters are: msLimit Maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit). This is an interface-imposed limit. serverTimeLimit Maximum time in seconds that the server should spend returning results. This is a server-imposed limit. dereference Specifies when aliases should be dereferenced. Must be either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from LDAPv2 (LDAPv2.LDAP_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). batchSize Specify the number of results to block on during enumeration. 0 means to block until all results are in (1 by default). binder Custom authentication processor, called when the LDAPConnection needs to authenticate, typically on following a referral. null may be specified to indicate default authentication processing. reauth Specifies an object of the class that implements the LDAPRebind interface. The object will be used when the client follows referrals automatically. The object provides a method for getting the Expires July 3, 2000 [Page 58] JAVA LDAP API January 2000 distinguished name and password used to authenticate to another LDAP server during a referral. Specifying null indicates the default LDAPRebind will be used if one has been assigned with LDAPConnection.setOption(), or anonymous authentication otherwise. hop_limit Maximum number of referrals to follow in a sequence when attempting to resolve a request, when doing automatic referral following. 4.23.2 getBatchSize public int getBatchSize() Returns the number of results to block on during enumeration of search results. This should be 0 if intermediate results are not needed, and 1 if results are to be processed as they come in. 4.23.3 getDereference public int getDereference() Specifies when aliases should be dereferenced. Returns either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from LDAPv2. 4.23.4 getMaxResults public int getMaxResults() Returns the maximum number of search results to be returned; 0 means no limit. 4.23.5 getServerTimeLimit public int getServerTimeLimit() Reports the maximum number of seconds that the server is to wait when returning search results while using this constraint object 4.23.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 Expires July 3, 2000 [Page 59] JAVA LDAP API January 2000 needed, and 1 if results are to be processed as they come in. The default is 1. Parameters are: batchSize Blocking size on search enumerations. 4.23.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 LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from LDAPv2. 4.23.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 Maxumum number of search results to return. 4.23.9 setServerTimeLimit public void setServerTimeLimit(int seconds) Sets the maximum number of seconds that the server is to wait when returning search results. The parameter is only recognized on search operations. 4.24 public class LDAPSearchResults An LDAPSearchResults object is returned from a search operation. It implements Enumeration, thereby providing access to all entries retrieved during the operation. 4.24.1 getCount Expires July 3, 2000 [Page 60] JAVA LDAP API January 2000 public int getCount() Returns a count of the entries in the search result. If the search is asynchronous (batch size not 0), this reports the number of results received so far. 4.24.2 getResponseControls public LDAPControl[] getResponseControls() Returns the latest Server Controls returned by a Directory Server in the context of this search request, or null if no Server Controls were returned. 4.24.3 hasMoreElements public boolean hasMoreElements() Specifies whether or not there are more search results in the enumeration. If true, there are more search results. 4.24.4 next public LDAPEntry next() throws LDAPException Returns the next result in the enumeration as an LDAPEntry. If automatic referral following is disabled, and there are one or more referrals among the search results, next() will throw an LDAPReferralException the last time it is called, after all other results have been returned. 4.24.5 nextElement public Object nextElement() Returns the next result in the enumeration as an Object. This the default implementation of Enumeration.nextElement(). The returned value may be an LDAPEntry or an LDAPReferralException. 4.24.6 sort public void sort(LDAPEntryComparator comp) Sorts all entries in the results using the provided comparison object. If the object has been partially or completely enumerated, only remaining elements are sorted. Sorting the results requires that they all be present. This implies that Expires July 3, 2000 [Page 61] JAVA LDAP API January 2000 LDAPSearchResults.nextElement() will always block until all results have been retrieved, after a sort operation. The LDAPCompareAttrNames class is provided to support the common need to collate by a single or multiple attribute values, in ascending or descending order. Examples are: res.sort(new LDAPCompareAttrNames("cn")); res.sort(new LDAPCompareAttrNames("cn", false)); String[] attrNames = { "sn", "givenname" }; res.sort(new LDAPCompareAttrNames(attrNames)); Parameters are: comp An object that implements the LDAPEntryComparator interface to compare two objects of type LDAPEntry. 4.25 public interface LDAPSocketFactory Used to construct a socket connection for use in an LDAPConnection. An implementation of this interface may, for example, provide a TLSSocket connected to a secure server. 4.25.1 makeSocket public Socket makeSocket(String host, int port) throws IOException, UnknownHostException Returns a socket connected using the provided host name and port number. There may be additional makeSocket methods defined when interfaces to establish TLS and SASL authentication in the java environment have been standardized. Parameters are: host Contains a hostname or dotted string representing the IP address of a host running an LDAP server to connect to. port Contains the TCP or UDP port number to connect to or contact. The default LDAP port is 389. Expires July 3, 2000 [Page 62] JAVA LDAP API January 2000 4.26 public class LDAPSortKey Encapsulates parameters for sorting search results. 4.26.1 Constructors public LDAPSortKey( String keyDescription ) Constructs a new LDAPSortKey object using a, possibly complex, sorting specification. public LDAPSortKey( String key, boolean reverse) Constructs a new LDAPSortKey object using an attribute name and a sort order. public LDAPSortKey( String key, boolean reverse, String matchRule) Constructs a new LDAPSortKey object using an attribute name, a sort order, and a matching rule. Parameters are: keyDescription A single attribute specification to sort by. If prefixed with "-", reverse order sorting is requested. A matching rule OID may be appended following ":". Examples: "cn" "-cn" "-cn:1.2.3.4.5" key An attribute name, e.g. "cn". reverse True to sort in reverse collation order. matchRule The object ID (OID) of a matching rule used for collation. If the object will be used to request server-side sorting of search results, it should be the OID of a matching rule known to be supported by that server. 4.26.2 getKey public String getKey() Expires July 3, 2000 [Page 63] JAVA LDAP API January 2000 Returns the attribute to be used for collation. 4.26.3 getReverse public boolean getReverse() Returns true if the sort key specifies reverse-order sorting. 4.26.4 getMatchRule public String getMatchRule() Returns the OID to be used as matching rule, or null if none is to be used. 4.27 public class LDAPUrl Encapsulates parameters of an LDAP Url query, as defined in [6]. An LDAPUrl object can be passed to LDAPConnection.search to retrieve search results. 4.27.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) Constructs a full-blown LDAP URL to specify an LDAP search operation. Parameters are: Expires July 3, 2000 [Page 64] JAVA LDAP API January 2000 url An explicit URL string, e.g. "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn ,sn?sub?(objectclass=inetOrgPerson)". host Host name of LDAP server, or null for "nearest X.500/LDAP". port Port number for LDAP server (use LDAPConnection.DEFAULT_PORT for default port). dn Distinguished name of object to fetch. attrNames Names of attributes to retrieve. null for all attributes. scope Depth of search (in DN namespace). Use one of SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPv2. filter Search filter specifying the search criteria, as defined in [3]. 4.27.2 decode public static String decode(String URLEncoded) throws MalformedURLException Decodes a URL-encoded string. Any occurences of %HH are decoded to the hex value represented. However, this method does NOT decode "+" into " ". See [8] for details on URL encoding/decoding. Parameters are: URLEncoded String to decode. 4.27.3 encode public static String encode(String toEncode) Encodes an arbitrary string. Any illegal characters are encoded as %HH. However, this method does NOT encode " " into "+". Parameters are: toEncode String to encode. 4.27.4 getAttributes public String[] getAttributeArray() Expires July 3, 2000 [Page 65] JAVA LDAP API January 2000 Returns an array of attribute names specified in the URL. 4.27.5 getAttributes public Enumeration getAttributes() Returns an Enumerator for the attribute names specified in the URL. 4.27.6 getDN public String getDN() Returns the distinguished name encapsulated in the URL. 4.27.7 getFilter public String getFilter() Returns the search filter [6], or the default filter - (objectclass=*) - if none was specified. 4.27.8 getHost public String getHost() Returns the host name of the LDAP server to connect to. 4.27.9 getPort public int getPort() Returns the port number of the LDAP server to connect to. 4.27.10 getUrl public String getUrl() Returns a valid string representation of this LDAP URL. 4.28 public interface LDAPv2 As a mechanism to support planned and future LDAP protocol extensions, functionality is defined in an interface - LDAPv2, corresponding to version 2 of the LDAP protocol. LDAPConnection must Expires July 3, 2000 [Page 66] JAVA LDAP API January 2000 implement at least LDAPv2, and may implement LDAPv3. Applications can test for support of these protocol levels in a given package with the instanceof operator. 4.28.1 abandon public void abandon(LDAPSearchResults results) throws LDAPException Notifies the server to not send additional results associated with this LDAPSearchResults object, and discards any results already received. Parameters are: results An object returned from a search. 4.28.2 add public void add(LDAPEntry entry, LDAPConstraints cons) throws LDAPException Adds an entry to the directory. Parameters are: entry LDAPEntry object specifying the distinguished name and attributes of the new entry. cons Constraints specific to the operation. 4.28.3 bind public void bind(String dn, String passwd) throws LDAPException Authenticates to the LDAP server (that the object is currently connected to) using the specified name and password. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded. Parameters are: dn If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name. Expires July 3, 2000 [Page 67] JAVA LDAP API January 2000 passwd If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password. 4.28.4 compare public boolean compare(String dn, LDAPAttribute attr) throws LDAPException public boolean compare(String dn, LDAPAttribute attr, LDAPConstraints cons) throws LDAPException Checks to see if an entry contains an attribute with a specified value. Returns 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. cons Constraints specific to the operation. 4.28.5 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. public void connect(String host, int port, String dn, String passwd) Expires July 3, 2000 [Page 68] JAVA LDAP API January 2000 throws LDAPException Connects to the specified host and port and uses the specified DN and password to authenticate to the server. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. This is equivalent to connect(host, port) followed by bind(dn, passwd). Parameters are: host Contains a hostname or dotted string representing the IP address of a host running an LDAP server to connect to. Alternatively, it may contain a list of host names, space-delimited. Each host name may include a trailing colon and port number. In the case where more than one host name is specified, each host name in turn will be contacted until a connection can be established. Examples: "directory.knowledge.com" "199.254.1.2" "directory.knowledge.com:1050 people.catalog.com 199.254.1.2" port Contains the TCP or UDP port number to connect to or contact. The default LDAP port is 389. "port" is ignored for any host name which includes a colon and port number. dn If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name. passwd If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password. 4.28.6 delete public void delete(String dn) throws LDAPException public void delete(String dn, LDAPConstraints cons) throws LDAPException Deletes the entry for the specified DN from the directory. Parameters are: Expires July 3, 2000 [Page 69] JAVA LDAP API January 2000 dn Distinguished name of the entry to modify. cons Constraints specific to the operation. 4.28.7 disconnect public void disconnect() throws LDAPException Disconnects from the LDAP server. Before the object can perform LDAP operations again, it must reconnect to the server by calling connect. 4.28.8 getOption public Object getOption(int option) throws LDAPException Returns the value of the specified option for this object. Parameters are: option See LDAPConnection.setOption for a description of valid options. 4.28.9 modify public void modify(String dn, LDAPModification mod) throws LDAPException public void modify(String dn, LDAPModification mod, LDAPConstraints cons) throws LDAPException Makes a single change to an existing entry in the directory (for example, changes the value of an attribute, adds a new attribute value, or removes an existing attribute value). The LDAPModification object specifies both the change to be made and the LDAPAttribute value to be changed. public void modify(String dn, LDAPModificationSet mods) throws LDAPException public void modify(String dn, LDAPModificationSet mods, Expires July 3, 2000 [Page 70] JAVA LDAP API January 2000 LDAPConstraints cons) throws LDAPException Makes a set of changes to an existing entry in the directory (for example, changes attribute values, adds new attribute values, or removes existing attribute values). Parameters are: dn Distinguished name of the entry to modify. mod A single change to be made to the entry. mods A set of changes to be made to the entry. cons Constraints specific to the operation. 4.28.10 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 Reads the entry for the specified distinguished name (DN) and retrieves only the specified attributes from the entry. Parameters are: dn Distinguished name of the entry to retrieve. cons Constraints specific to the operation. attrs Names of attributes to retrieve. 4.28.11 rename Expires July 3, 2000 [Page 71] JAVA LDAP API January 2000 public void rename(String dn, String newRdn, boolean deleteOldRdn) throws LDAPException public void rename(String dn, String newRdn, boolean deleteOldRdn, LDAPConstraints cons) throws LDAPException Renames an existing entry in the directory. Parameters are: dn Current distinguished name of the entry. newRdn New relative distinguished name for the entry. deleteOldRdn If true, the old name is not retained as an attribute value. cons Constraints specific to the operation. 4.28.12 search public LDAPSearchResults search(String base, int scope, String filter, String attrs[], boolean typesOnly) 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 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 Expires July 3, 2000 [Page 72] JAVA LDAP API January 2000 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. Parameters are: base The base distinguished name to search from. scope The scope of the entries to search. The following are the valid options: LDAPv2.SCOPE_BASE Search only the base DN LDAPv2.SCOPE_ONE Search only entries under the base DN LDAPv2.SCOPE_SUB Search the base DN and all entries within its subtree filter Search filter specifying the search criteria, as defined in [3]. 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. cons Constraints specific to the search. 4.28.13 setOption public void setOption(int option, Object value) throws LDAPException Sets the value of the specified option for this object. These options represent the default search constraints for the current connection. Some of these options are also propagated through the LDAPConstraints, which can be obtained from the connection object with the getSearchConstraints method. The option that is set here applies to all subsequent searches performed through the current connection, unless it is overridden with an LDAPConstraints at the time of search. Expires July 3, 2000 [Page 73] JAVA LDAP API January 2000 To set a constraint only for a particular search, create an LDAPConstraints object with the new constraints and pass it to the LDAPConnection.search method. Parameters are: option One of the following options: Option Type Description LDAPConnection.DEREF Integer Specifies under what circumstances the object dereferences aliases. By default, the value of this option is LDAPConnection.DEREF _ NEVER. Legal values for this option are: LDAPConnection.DEREF_NEVER Aliases are never dereferenced. LDAPConnection.DEREF_FINDING aliases are dereferenced when finding the starting point for the search (but not when searching under that starting entry). LDAPConnection.DEREF_SEARCHING Aliases are dereferenced when searching the entries beneath the starting point of the search (but not when finding the starting entry). LDAPConnection.DEREF_ALWAYS Aliases are always dereferenced (both when finding the starting point for the search and when searching under that starting entry). Expires July 3, 2000 [Page 74] JAVA LDAP API January 2000 LDAPConnection.SIZELIMIT Integer Specifies the maximum number of search results to return. If this option is set to 0, there is no maximum limit. By default, the value of this option is 1000. LDAPConnection.SERVER_TIMELIMIT Integer Sets the maximum number of seconds that the server is to wait when returning search results. The parameter is only recognized on search operations. By default, the value of this option is 0. LDAPConnection.TIMELIMIT Integer Specifies the maximum number of milliseconds to wait for results before timing out. If this option is set to 0, there is no maximum time limit. The actual granularity of the timeout depends on the implementation. By default, the value of this option is 0. LDAPConnection.REFERRALS Boolean Specifies whether or not the client follows referrals automatically. If true, the client follows referrals automatically. If Expires July 3, 2000 [Page 75] JAVA LDAP API January 2000 false, an LDAPReferralException is raised when a referral is detected. Referrals of any type other to an LDAP server (i.e. a referral URL other than ldap://something) are ignored on automatic referral following. By default, the value of this option is false. LDAPConnection.REFERRALS_REAUTHENTICATION LDAPRebind Specifies an object that implements the LDAPRebind interface. A user of the class library must define this class and the getRebindAuthentica- tion method that will be used to get the distinguished name and password to use for authentication. If this value is null and REFERRALS is true, referrals will be followed with anonymous (= no) authentication. By default, the value of this option is null. LDAPConnection.BIND LDAPBind Specifies an object that can process an authentication request, overriding the default authentication behavior. This is typically used for Expires July 3, 2000 [Page 76] JAVA LDAP API January 2000 processing authentication during referral following. LDAPConnection.REFERRALS_HOP_LIMIT Integer Specifies the maximum number of referrals in a sequence that the client will follow. For example, if REFERRALS_HOP_LIMIT is 5, the client will follow no more than 5 referrals in a row when resolving a single LDAP request. The default value of this option is 10. LDAPConnection.BATCHSIZE Integer Specifies the number of search results to return at a time. For example, if BATCHSIZE is 1, enumerating an LDAPSearchResults will block only until one entry is available. If it is 0, enumerating will block until all entries have been retrieved from the server. The default value of this option is 1. value The value to assign to the option. The value must be the java.lang object wrapper for the appropriate parameter (e.g. boolean->Boolean, int->Integer). 4.29 public interface LDAPv3 extends LDAPv2 LDAPv3 extends LDAPv2 by adding support for features of version 3 of the LDAP protocol. LDAPConnection implements at least LDAPv2, and may Expires July 3, 2000 [Page 77] JAVA LDAP API January 2000 also implement LDAPv3. Applications can test for support of these protocol levels in a given package with the instanceof operator. 4.29.1 bind public void bind(int version, String dn, String passwd) throws LDAPException Authenticates to the LDAP server (that the object is currently connected to) using the specified name and password, with the specified LDAP protocol version. If the server does not support the requested protocol version, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded. Parameters are: version LDAP protocol version requested: currently 2 or 3. dn If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name. passwd If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password. public void bind(String dn, Properties props, javax.security.auth.callback.CallbackHandler cbh) throws LDAPException public void bind(String dn, String[] mechanisms, Hashtable props, javax.security.auth.callback.CallbackHandler cbh) throws LDAPException Authenticates to the LDAP server (that the object is currently connected to) using the specified name and of a specified set of mechanisms. If none of the requested SASL mechanisms is available, an Expires July 3, 2000 [Page 78] JAVA LDAP API January 2000 exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded. If mechanisms is null, or if the first version of the method is called, the LDAP server will be interrogated for its supportedSaslMechanisms attribute of its root DSE. Parameters are: dn If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name. mechanisms An array of IANA-registered SASL mechanisms which the client is willing to use for authentication. props Optional qualifiers for the authentication session. cbh A class which may be called by the Mechanism Driver to obtain additional information required, such as additional credentials. 4.29.2 connect public void connect(int version, String host, int port, String dn, String passwd) throws LDAPException Connects to the specified host and port and uses the specified DN and password to authenticate to the server, with the specified LDAP protocol version. If the server does not support the requested protocol version, an exception is thrown. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. This is equivalent to connect(host, port) followed by bind(version, dn, passwd). Parameters are: version LDAP protocol version requested: currently 2 or 3. host Contains a hostname or dotted string representing the IP address of a host running an LDAP server to connect to. Alternatively, it may contain a list of host names, space-delimited. Each host name may include a trailing colon and port Expires July 3, 2000 [Page 79] JAVA LDAP API January 2000 number. In the case where more than one host name is specified, each host name in turn will be contacted until a connection can be established. Examples: "directory.knowledge.com" "199.254.1.2" "directory.knowledge.com:1050 people.catalog.com 199.254.1.2" port Contains the TCP or UDP port number to connect to or contact. The default LDAP port is 389. "port" is ignored for any host name which includes a colon and port number. dn If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name. passwd If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password. 4.29.3 extendedOperation public LDAPExtendedOperation extendedOperation( LDAPExtendedOperation op ) throws LDAPException Provides a means to access extended, non-mandatory operations offered by a particular LDAP version 3 compliant server. Returns an operation-specific object, containing an ID and an Octet String or BER-encoded value(s). Parameters are: op Object which contains an identifier of the extended operation, which should be one recognized by the particular server this client is connected to, and operation-specific sequence of Octet String or BER-encoded value(s). 4.29.4 getResponseControls public LDAPControl[] getResponseControls() Expires July 3, 2000 [Page 80] JAVA LDAP API January 2000 Returns the latest Server Controls returned by a Directory Server with a response to an LDAP request from the current thread, or null if the latest response contained no Server Controls. 4.29.5 rename 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 Renames an existing entry in the directory, possibly repositioning it in the directory tree. Parameters are: dn Current distinguished name of the entry. newRdn New relative distinguished name for the entry. newParentdn Distinguished name of the existing entry which is to be the new parent of the entry. deleteOldRdn If true, the old name is not retained as an attribute value. cons Constraints specific to the operation. 4.30 Client and Server Controls LDAPv3 operations can be extended through the use of controls. Controls may be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls. The LDAP API also supports a client-side extension mechanism through the use of client controls (these controls affect the behavior of the LDAP API only and are never sent to a server). A common class is used to represent both types of controls - LDAPControl. Controls are set and retrieved in LDAPConnection with the setOption and getOption methods, using the keys LDAPv3.SERVERCONTROLS and LDAPv3.CLIENTCONTROLS. Either a single LDAPControl or an array may be passed, e.g. Expires July 3, 2000 [Page 81] JAVA LDAP API January 2000 LDAPControl control = new LDAPControl( type, critical, vals ); ld.setOption( LDAPv3.SERVERCONTROLS, control ); or LDAPControl[] controls = new LDAPControl[2]; controls[0] = new LDAPControl( type0, critical0, vals0 ); controls[1] = new LDAPControl( type1, critical1, vals1 ); ld.setOption( LDAPv3.SERVERCONTROLS, controls ); Server controls returned to a client as part of the response to an operation can be obtained with LDAPv3.getResponseControls(). Support for specific controls is defined in a package "controls" subordinate to the main LDAP package. 5. Security Considerations LDAP supports security through protocol-level authentication, using clear-text passwords or other more secure mechanisms. It also supports running over TLS, which provides strong security at the transport layer. This draft does not cover TLS implementations, although it identifies a mechanism for supplying one, through the LDAPSocketFactory interface. An interface to using SASL for configurable authentication and session protection is provided, but implementations are outside the scope of this document. 6. Acknowledgements The proposed API builds on earlier work done in collaboration with Thomas Kwan and Stephan Gudmundson, then of of NCware Technologies Corp. It also includes suggestions by Jim Sermersheim of Novell. Steve Sonntag of Novell provided extensive review of of both content and style. 7. Bibliography [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation X.520. [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol: Attribute Syntax Definitions", RFC 2252, December 1997 [3] T. Howes, "A String Representation of LDAP Search Filters," RFC 1960, June 1996. Expires July 3, 2000 [Page 82] JAVA LDAP API January 2000 [4] S. Kille, "A String Representation of Distinguished Names," RFC 1779, March 1995. [5] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [6] T. Howes, M. Smith, "An LDAP URL Format", RFC 2255, December 1997. [7] T. Howes, M. Smith, "The LDAP Application Program Interface", Internet Draft draft-ietf-ldapext-ldap-c-api-03.txt, June 1999. [8] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994. [9] H. Alvestrans, "Tags for the Identification of Languages", RFC 1766, March 1995. [10] R. Weltman, C. Tomlinson, "The Java LDAP Application Program Interface Asynchronous Extension", Internet Draft draft-ietf- ldapext-ldap-java-api-asynch-ext-04.txt, December 1999. 8. Authors' Addresses Rob Weltman Netscape Communications Corp. 501 E. Middlefield Rd. Mountain View, CA 94043 USA +1 650 937-3301 rweltman@netscape.com Christine Tomlinson Innosoft International, Inc. 8911 Capital of Texas Highway Suite 4140 Austin, TX US 78759 +1 512 231 1600 christine.tomlinson@innosoft.com Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd. Mountain View, CA 94043 USA +1 650 937-3477 mcs@netscape.com Tim Howes Expires July 3, 2000 [Page 83] JAVA LDAP API January 2000 1345 Fairway Drive Los Altos, CA 94024 USA +1 650 787-5384 timhowes@yahoo.com Expires July 3, 2000 [Page 84] JAVA LDAP API January 2000 9. Appendix A - Sample java LDAP programs import netscape.ldap.*; import java.util.*; public class SearchJensen { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* authenticate to the directory as nobody */ /* This is not really necessary if explicit authentication is not desired, because there is already anonymous authentication at connect time */ ld.bind( "", "" ); /* search for all entries with surname of Jensen */ String MY_FILTER = "sn=Jensen"; String MY_SEARCHBASE = "o=Ace Industry, c=US"; LDAPSearchConstraints cons = ld.getSearchConstraints(); /* Setting the batchSize to one will cause the result enumeration below to block on one result at a time, allowing us to update a list or do other things as results come in. */ /* We could set it to 0 if we just wanted to get all results and were willing to block until then */ cons.setBatchSize( 1 ); LDAPSearchResults res = ld.search( MY_SEARCHBASE, ld.SCOPE_ONE, MY_FILTER, null, false, cons ); /* Loop on results until finished */ while ( res.hasMoreElements() ) { /* Next directory entry */ LDAPEntry findEntry = (LDAPEntry)res.nextElement(); System.out.println( findEntry.getDN() ); /* Get the attributes of the entry */ LDAPAttributeSet findAttrs = findEntry.getAttributeSet(); Enumeration enumAttrs = findAttrs.getAttributes(); System.out.println( "Attributes: " ); Expires July 3, 2000 [Page 85] JAVA LDAP API January 2000 /* Loop on attributes */ while ( enumAttrs.hasMoreElements() ) { LDAPAttribute anAttr = (LDAPAttribute)enumAttrs.nextElement(); String attrName = anAttr.getName(); System.out.println( "" + attrName ); /* Loop on values for this attribute */ Enumeration enumVals = anAttr.getStringValues(); while ( enumVals.hasMoreElements() ) { String aVal = (String)enumVals.nextElement(); System.out.println( "" + aVal ); } } } } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } /* Done, so disconnect */ if ( ld.isConnected() ) ld.disconnect(); } } Expires July 3, 2000 [Page 86] JAVA LDAP API January 2000 import netscape.ldap.*; import java.util.*; public class ModifyEmail { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* authenticate to the directory as Bab Jensen */ String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US"; String MY_PASSWORD = "MysteryLady"; ld.bind( MY_NAME, MY_PASSWORD ); /* Prepare to change my email address */ LDAPAttribute attrEmail = new LDAPAttribute( "mail", "babs@ace.com" ); LDAPModification mod = new LDAPModification( LDAPModification.REPLACE, attrEmail ); /* Now modify the entry in the directory */ ld.modify( MY_NAME, mod ); System.out.println( "Entry modified" ); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } /* Done, so disconnect */ if ( ld.isConnected() ) ld.disconnect(); } } Expires July 3, 2000 [Page 87] JAVA LDAP API January 2000 import netscape.ldap.*; import java.util.*; public class ShowSchema { public static void main( String[] args ) { LDAPConnection ld = new LDAPConnection(); try { /* Connect to server */ String MY_HOST = "localhost"; int MY_PORT = 389; ld.connect( MY_HOST, MY_PORT ); /* Fetch the schema (anonymous is okay for reading) */ LDAPSchema schema = new LDAPSchema(); schema.fetchSchema( ld ); /* What is the definition of "userPassword"? */ LDAPAttributeSchema a = schema.getAttribute( "userpassword" ); if ( a != null ) { String syntax = a.getSyntaxString(); String syntaxString = "string"; if ( syntax.equals(BINARY_SYNTAX) ) syntaxString = "binary"; else if (syntax.equals(INTEGER_SYNTAX) ) syntaxString = "integer"; String single = "multi-valued"; if ( a.isSingleValued() ) single = "single-valued"; System.out.println( "userPassword. " + "OID = " + a.getID() + ", type = " + syntaxString + ", " + single ); ); /* What are the possible attributes for "person"? */ LDAPObjectClassSchema o = schema.getObjectClass( "person" ); if ( o != null ) { Enumeration required = o.getRequiredAttributes(); Enumeration optional = o.getOptionalAttributes(); System.out.println( "Required attributes for person:" ); while( required.hasMoreElements() ) System.out.println( " " + (String)required.nextElement() ); System.out.println( "Optional attributes for person:" ); while(optional.hasMoreElements() ) System.out.println( " " + (String) optional.nextElement() ); Expires July 3, 2000 [Page 88] JAVA LDAP API January 2000 ); } catch( LDAPException e ) { System.out.println( "Error: " + e.toString() ); } /* Done, so disconnect */ if ( ld.isConnected() ) ld.disconnect(); } protected static final String BINARY_SYNTAX = "1.3.6.1.4.1.1466.115.121.1.5"; protected static final String INTEGER_SYNTAX = "1.3.6.1.4.1.1466.115.121.1.27"; } 10. Appendix B - Changes from ldap-java-api-08.txt 10.1 Standards track Added intended category to first page header. 10.2 SASL references Removed all references to a Java SASL internet draft. 10.3 LDAPv2 Removed static methods search(LDAPUrl url). The methods are still present in LDAPConnection. 11. Appendix C - Changes from ldap-java-api-07.txt 11.1 LDAPAttributeSchema Removed getAliases() because it is already defined in the superior class LDAPSchemaElement. Removed getSyntax() which returned an integer. 11.2 LDAPConnection Added getAuthenticationMethod() (4.6.5). 11.3 LDAPSchemaElement Changed getOID() to getID() (4.22.4). Expires July 3, 2000 [Page 89] JAVA LDAP API January 2000 12. Appendix D - Changes from ldap-java-api-06.txt 12.1 LDAPAttributeSchema Added a constructor that takes the attribute syntax as a String, an optional superior attribute type, and an optional list of aliases (4.2.1). Removed previous constructor. Added getSuperior() (4.2.3) and getSyntaxString() (4.2.2). 12.2 LDAPConnection Added getInputStream() (4.6.8) getOutputStream() (4.6.9), setInputStream() (4.6.20), and setOutputStream() (4.6.21). They are used when establishing a security layer with SASL, and may also be used to interpose a proxy. 12.3 LDAPDN Added equals() (4.9.1). 12.4 LDAPException Added additional error codes defined in [7] (4.13). 12.5 LDAPMatchingRuleSchema Added a constructor that takes the attribute syntax as a String and an optional list of aliases (4.14.1). Removed previous constructor. 12.6 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 (4.17.1). Removed previous constructor. Added getSuperiors() (4.17.2) and getType() (4.17.5). Removed getSuperior(). 12.7 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 (4.22.10 - 4.22.12). Added getAliases() (4.22.1), getQualifier() (4.22.5), getQualiferNames() (4.22.6), isObsolete() (4.22.7), and setQualifier() (4.22.9). Expires July 3, 2000 [Page 90] JAVA LDAP API January 2000 13. Appendix E - Changes from ldap-java-api-05.txt 13.1 LDAPConnection Distinguished between getConstraints() and getSearchConstraints(), and between setConstraints() and setSearchConstraints(). 13.2 LDAPConstraints LDAPBind and LDAPRebind should not be specified in the same constructor. Added setClientControls(). 13.3 LDAPSearchConstraints LDAPBind and LDAPRebind should not be specified in the same constructor. 13.4 LDAPControl newInstance() is now static. 13.5 LDAPv3 Changed the signature of the bind() methods to match the Java SASL Internet Draft. 14. Appendix F - Changes from ldap-java-api-04.txt 14.1 LDAPAttribute Added getByteValueArray() and getStringValueArray(). 14.2 LDAPCompareAttrNames Added getLocale() and setLocale(). 14.3 LDAPSchemaElement Added modify(). Expires July 3, 2000 [Page 91] JAVA LDAP API January 2000 14.4 LDAPSchemaElement Added fetchSchema(LDAPConnection, String). 15. Appendix G - Changes from ldap-java-api-03.txt 15.1 LDAPBind New interface, to support sophisticated reauthentication mechanisms. 15.2 LDAPControl Added methods register() and newInstance(), to support dynamic registration and instantiation of server response controls. 15.3 LDAPConstraints Separated interface time limit from server search time limit. Moved all search-only constraints to LDAPSearchConstraints. 15.4 LDAPRebind Reverted back to original name, instead of LDAPReauthentication as it was in the previous draft. 15.5 LDAPRebindProc Reverted back from LDAPCredentials. 15.6 LDAPSearchConstraints Reinstated this class, to represent all constraints applicable to a search. LDAPConstraints (which it extends) only represents common constraints for all operations. 15.7 LDAPSearchResults Added getResponseControls(). 15.8 LDAPv2 Added abandon(). Separated interface time limit from server search time limit. Changed authenticate() to bind(). Expires July 3, 2000 [Page 92] JAVA LDAP API January 2000 15.9 LDAPv3 Changed authenticate() to bind(). 16. Appendix H - Changes from ldap-java-api-02.txt 16.1 LDAPSearchConstraints Renamed to LDAPConstraints, since it can be applied to operations other than search. 16.2 LDAPRebind Renamed to LDAPReauthentication. Added a definition of its single method. 16.3 LDAPRebindProc Renamed to LDAPCredentials. 17. Appendix I - Changes from ldap-java-api-01.txt 17.1 LDAPAttribute Added a copy constructor. Added support for subtypes, and for language subtypes in particular. 17.2 LDAPAttributeSet LDAPAttributeSet implements Cloneable. Added getSubset() for subtype support. 17.3 LDAPDN Added support for escaping and unescaping an RDN. 17.4 LDAPException Added the SASL_BIND_IN_PROGRESS error code. Expires July 3, 2000 [Page 93] JAVA LDAP API January 2000 17.5 LDAPSearchResults Added getCount(), to report the number of results returned. 17.6 LDAPConnection Added a signature that passes LDAPConstraints to read(LDAPURL). 17.7 LDAPv2 Added signatures that pass LDAPConstraints to the following methods: add() compare() modify() read() rename() 17.8 LDAPv3 Removed "Preferred Language", because it has been dropped from the extension work. Added a signature that passes LDAPConstraints to rename(). Expires July 3, 2000 [Page 94]