idnits 2.17.1 draft-ietf-asid-ldap-java-api-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 62 longer pages, the longest (page 2) being 234 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 63 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 16 instances of too long lines in the document, the longest one being 4 characters in excess of 72. ** The abstract seems to contain references ([9], [13]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 10 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 535 has weird spacing: '...ingFlag true...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 26, 1997) is 9681 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '9' on line 2574 looks like a reference -- Missing reference section? '13' on line 2588 looks like a reference -- Missing reference section? '2' on line 2555 looks like a reference -- Missing reference section? '7' on line 2568 looks like a reference -- Missing reference section? '1' on line 2552 looks like a reference -- Missing reference section? '4' on line 2562 looks like a reference -- Missing reference section? '8' on line 2572 looks like a reference -- Missing reference section? '14' on line 2592 looks like a reference -- Missing reference section? '11' on line 2580 looks like a reference -- Missing reference section? '10' on line 2577 looks like a reference -- Missing reference section? '3' on line 2559 looks like a reference -- Missing reference section? '15' on line 2595 looks like a reference -- Missing reference section? '0' on line 2523 looks like a reference -- Missing reference section? '5' on line 2565 looks like a reference -- Missing reference section? '12' on line 2585 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Rob Weltman 3 INTERNET-DRAFT Netscape Communications Corp. 4 Tim Howes 5 Netscape Communications Corp. 6 Mark Smith 7 Netscape Communications Corp. 8 September 26, 1997 10 The Java LDAP Application Program Interface 11 draft-ietf-asid-ldap-java-api-01.txt 13 Status of this Memo 15 This document is an Internet-Draft. Internet-Drafts are working docu- 16 ments of the Internet Engineering Task Force (IETF), its areas, and its 17 working groups. Note that other groups may also distribute working 18 documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference material 23 or to cite them other than as ``work in progress.'' 25 To learn the current status of any Internet-Draft, please check the 26 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 27 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 28 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 30 Abstract 32 This document defines a java language application program interface to 33 the lightweight directory access protocol (LDAP), in the form of a class 34 library. It complements but does not replace RFC 1823 ([9]), which 35 describes a C language application program interface. It updates and 36 replaces draft-ietf-asid-ldap-java-api-00.txt [13], in adding clarifica- 37 tion on behavior under various circumstances, and in revising support 38 for language-sensitive attribute parsing. Other additions and correc- 39 tions are listed in the appendix. 41 1. Introduction 43 The LDAP class library is designed to provide powerful, yet simple, 44 access to a LDAP directory services. It defines a synchronous interface 45 to LDAP, with support for partial results on searching, to suit a wide 46 variety of applications. This document gives a brief overview of the 48 JAVA LDAP API September 1997 50 LDAP model, then an overview of the constituents of the class library. 51 The public class methods are described in detail, followed by an appen- 52 dix that provides some example code demonstrating the use of the 53 classes, and an appendix listing changes from earlier drafts. 55 2. Overview of the LDAP model 57 LDAP is the lightweight directory access protocol, described in [2] and 58 [7]. It defines a lightweight access mechanism in which clients send 59 requests to and receive responses from LDAP servers. 61 The LDAP information model comes from X.500 [1] and is based on the 62 entry, which contains information about some object (e.g., a person). 63 Entries are composed of attributes, which have a type and one or more 64 values. Each attribute has a syntax that determines what kinds of values 65 are allowed in the attribute (e.g., ASCII characters, a jpeg photograph, 66 etc.) and how those values behave during directory operations (e.g., is 67 case significant during comparisons). 69 Entries may be organized in a tree structure, usually based on politi- 70 cal, geographical, and organizational boundaries. Other structures are 71 possible, including a flat namespace. Each entry is uniquely named rela- 72 tive to its sibling entries by its relative distinguished name (RDN) 73 consisting of one or more distinguished attribute values from the entry. 74 At most one value from each attribute may be used in the RDN. For exam- 75 ple, the entry for the person Babs Jensen might be named with the "Bar- 76 bara Jensen" value from the commonName attribute. 78 A globally unique name for an entry, called a distinguished name or DN, 79 is constructed by concatenating the sequence of RDNs from the entry up 80 to the root of the tree. For example, if Babs worked for the University 81 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 82 o=University of Michigan, c=US". The DN format used by LDAP is defined 83 in [4]. 85 Operations are provided to authenticate, search for and retrieve infor- 86 mation, modify information, and add and delete entries from the tree. 88 An LDAP server may return referrals if it cannot completely service a 89 request (for example if the request specifies a directory base outside 90 of the tree managed by the server). The LDAP class library offers the 91 programmer two options: the programmer can catch these referrals as 92 exceptions and explicitly issue new requests to the referred-to servers, 93 or the programmer can let the library automatically follow the refer- 94 rals. In the latter case, the programmer may also provide a reauthenti- 95 cation object, allowing automatic referrals to proceed with appropriate 96 credentials (as opposed to anonymous authentication) for each referred- 97 to server. 99 JAVA LDAP API September 1997 101 Before the client encodes and sends a string value to a server, the 102 string values are converted from the java 16-bit Unicode format to UTF-8 103 format. Then, when the values are received by the server, the values are 104 converted back to 16-bit Unicodeformat. The integrity of double-byte 105 and other non-ASCII character sets is fully preserved. 107 The next sections give an overview of how the class library is used and 108 detailed descriptions of the LDAP class methods that implement all of 109 these functions. 111 3. Overview of the LDAP classes 113 The central LDAP class is LDAPConnection. It provides methods to estab- 114 lish an authenticated or anonymous connection to an LDAP server, as well 115 as methods to search for, modify, compare, and delete entries in the 116 directory. 118 The LDAPConnection class also provides fields for storing settings that 119 are specific to the LDAP session (such as limits on the number of 120 results returned or timeout limits). An LDAPConnection object can be 121 cloned, allowing objects to share a single network connection but use 122 different settings (using LDAPConnection.setOption()). 124 To support extensions of the LDAP protocol LDAPConnection and to add the 125 capability to determine the LDAP protocol level supported by an LDAPCon- 126 nection object, LDAPConnection implements a protocol interface, which is 127 currently LDAPv3. 129 A search conducted by an LDAPConnection object returns results in an 130 LDAPSearchResults object, which can be enumerated to access the entries 131 found. Each entry (represented by an LDAPEntry object) provides access 132 to the attributes (represented by LDAPAttribute objects) returned for 133 that entry. Each attribute can produce the values found as byte arrays 134 or as Strings. 136 3.1. Interfaces 138 LDAPEntryComparator An interface to support arbitrary sorting algo- 139 rithms for entries returned by a search operation. 140 The basic java LDAP classes include one implemen- 141 tation: LDAPCompareAttrNames, to sort in ascending 142 order based on one or more attribute names. 144 LDAPRebind A programmer desiring reauthentication on automat- 145 ically following referrals must implement this 147 JAVA LDAP API September 1997 149 interface. Without it, automatically followed 150 referrals will use anonymous authentication. 151 Referrals of any type other to an LDAP server 152 (i.e. a referral URL other than ldap://something) 153 are ignored on automatic referral following. 155 LDAPSocketFactory Programmers needing to provide or use specialized 156 socket connections, including Transport Layer 157 Security (TLS) based ones, can provide an object 158 constructor to implement them using this inter- 159 face. 161 LDAPv2 This interface defines the functionality of the 162 LDAP version 2 protocol. It is implemented by 163 LDAPConnection. 165 LDAPv3 This interface extends LDAPv2, adding the func- 166 tionality of the LDAP version 3 protocol. It is 167 implemented by LDAPConnection. 169 3.2. Classes 171 LDAPAttribute Represents the name and values of one attribute of 172 a directory entry. 174 LDAPAttributeSet A collection of LDAPAttributes. 176 LDAPCompareAttrNames An implementation of LDAPEntryComparator, to sup- 177 port sorting of search results by one or more 178 attributes. 180 LDAPConnection Implements LDAPv3 and is the central point for 181 interactions with a directory. 183 LDAPControl Sets additional parameters or constraints for an 184 LDAP operation, either on the server or on the 185 client. 187 JAVA LDAP API September 1997 189 LDAPDN A utility class to facilitate composition and 190 decomposition of distinguished names (DNs). 192 LDAPEntry Represents a single entry in a directory. 194 LDAPExtendedOperation Encapsulates the ID and data associated with the 195 sending or receiving of an extended operation (an 196 LDAPv3 feature). 198 LDAPModification A single add/delete/replace operation to an 199 LDAPAttribute. 201 LDAPModificationSet A collection of LDAPModifications 203 LDAPRebindAuth An implementation of LDAPRebind must be able to 204 provide an LDAPRebindAuth at the time of a refer- 205 ral. The class encapsulates reauthentication 206 credentials. 208 LDAPSearchConstraints Defines the options controlling search operations. 210 LDAPSearchResults The enumerable results of a search operation. 212 LDAPSortKey Specifies how search results are to be sorted. 214 LDAPUrl Encapsulates parameters of an LDAP Url query, as 215 defined in [8]. 217 3.3. Exceptions 219 LDAPException General exception, which includes an error message 220 and an LDAP error code. 222 LDAPReferralException Derived from LDAPException and contains a list of 223 LDAPUrls corresponding to referrals received on an 224 LDAP operation. 226 JAVA LDAP API September 1997 228 4. Overview of LDAP API use 230 An application generally uses the LDAP API in four steps. 232 - Construct an LDAPConnection. Initialize an LDAP session with a 233 directory server. The LDAPConnection.connect() call establishes a 234 handle to the session, allowing multiple sessions to be open at 235 once, on different instances of LDAPConnection. 237 - Authenticate to the LDAP server with LDAPConnection.authenticate(). 239 - Perform some LDAP operations and obtain some results. 240 LDAPConnection.search() returns an LDAPSearchResults, which can be 241 enumerated to access all entries found. LDAPConnection.read() 242 returns a single entry. 244 - Close the connection. The LDAPConnection.disconnect() call closes 245 the connection. 247 All operations are synchronous - they do not return until the operation 248 has completed. In the java environment, it is appropriate to create a 249 thread for the operation rather than providing parallel synchronous and 250 asynchronous operations, as is the case in the C language API described 251 in [9]. To facilitate user feedback during searches, intermediate search 252 results can be obtained before the entire search operation is completed 253 by specifying the number of entries to return at a time. 255 Standard java Enumerations are used to parse search results. Errors 256 result in the throwing of an LDAPException, with a specific error code 257 and context-specific textual information available. 259 The following sections describe the LDAP classes in more detail. 261 5. The java LDAP classes 263 5.1. public class LDAPAttribute 265 The LDAPAttribute class represents the name and values of an attribute. 266 It is used to specify an attribute to be added to, deleted from, or 267 modified in a Directory entry. It is also returned on a search of a 268 Directory. 270 5.1.1. Constructors 272 public LDAPAttribute(String attrName) 274 JAVA LDAP API September 1997 276 Constructs an attribute with no values. 278 public LDAPAttribute(String attrName, 279 byte attrBytes[]) 281 Constructs an attribute with a byte-formatted value. 283 public LDAPAttribute(String attrName, 284 String attrString) 286 Constructs an attribute that has a single string value. 288 public LDAPAttribute(String attrName, 289 String attrStrings[]) 291 Constructs an attribute that has an array of string values. 293 Parameters are: 295 attrName Name of the attribute. 297 attrBytes Value of the attribute as raw bytes. 299 attrString Value of the attribute as a String. 301 attrStrings Array of values as Strings. 303 attrBytesArray Array of values as raw byte arrays. 305 5.1.2. addValue 307 public synchronized void addValue(String attrString) 309 Adds a string value to the attribute. 311 public synchronized void addValue(byte attrBytes[]) 313 Adds a byte[]-formatted value to the attribute. 315 Parameters are: 317 attrString Value of the attribute as a String. 319 JAVA LDAP API September 1997 321 attrBytes Value of the attribute as raw bytes. 323 5.1.3. getByteValues 325 public Enumeration getByteValues() 327 Returns an enumerator for the values of the attribute in byte[] for- 328 mat. 330 5.1.4. getStringValues 332 public Enumeration getStringValues() 334 Returns an enumerator for the string values of an attribute. 336 5.1.5. getName 338 public String getName() 340 Returns the name of the attribute. 342 5.1.6. removeValue 344 public synchronized void removeValue(String attrString) 346 Removes a string value from the attribute. 348 public synchronized void removeValue(byte attrValue[]) 350 Removes a byte[]-formatted value from the attribute. 352 Parameters are: 354 attrString Value of the attribute as a String. 356 attrBytes Value of the attribute as raw bytes. 358 5.1.7. size 360 public int size() 362 Returns the number of values of the attribute. 364 JAVA LDAP API September 1997 366 5.2. public class LDAPAttributeSet 368 An LDAPAttributeSet is a collection of LDAPAttributes, as returned in an 369 entry on a search or read operation, or used to construct an entry to be 370 added to a directory. 372 5.2.1. Constructors 374 public LDAPAttributeSet() 376 Constructs a new set of attributes. This set is initially empty. 378 5.2.2. add 380 public synchronized void add(LDAPAttribute attr) 382 Adds the specified attribute to this attribute set. 384 Parameters are: 386 attr Attribute to add to this set. 388 5.2.3. elementAt 390 public LDAPAttribute elementAt(int index) 391 throws ArrayIndexOutOfBoundsException 393 Returns the attribute at the position specified by the index. The 394 index is 0-based. 396 Parameters are: 398 index Index of the attribute to get. 400 5.2.4. getAttribute 402 public LDAPAttribute[] getAttribute(String attrName) 404 Returns the attribute matching the specified attrName. For example, 405 getAttribute("cn") returns only the "cn" attribute; 406 getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute. 407 In both cases, null is returned if there is no exact match to the 408 specified attrName. 410 JAVA LDAP API September 1997 412 public LDAPAttribute[] getAttribute(String attrName, String lang) 414 Returns a single best-match attribute, or none if no match is avail- 415 able in the entry. 417 LDAP version 3 allows adding a subtype specification to an attribute 418 name. "cn;lang-ja", for example, indicates a Japanese language sub- 419 type of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype of 420 "cn;lang-ja". This feature may be used to provide multiple localiza- 421 tions in the same Directory. For attributes which do not vary among 422 localizations, only the base attribute may be stored, whereas for 423 others there may be varying degrees of specialization. 425 getAttribute(attrName,lang) returns the subtype that matches attrName 426 and that best matches lang. If there are subtypes other than "lang" 427 subtypes included in attrName, e.g. "cn;binary", only attributes with 428 all of those subtypes are returned. If lang is null or empty, the 429 method behaves as getAttribute(attrName). If there are no matching 430 attributes, null is returned. 432 Example: 433 Assume the entry contains only the following attributes: 434 cn;lang-en 435 cn;lang-ja-JP-kanji 436 sn 437 getAttribute( "cn" ) returns null. 438 getAttribute( "sn" ) returns the "sn" attribute. 439 getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute. 440 getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute. 441 getAttribute( "cn", "lang-ja" ) returns null. 442 getAttribute( "sn", "lang-en" ) returns the "sn" attribute. 444 Parameters are: 446 attrName The name of an attribute to retrieve, with or without 447 subtype specification(s). "cn", "cn;phonetic", and 448 "cn;binary" are valid attribute names. 450 lang A language specification as in [14], with optional 451 subtypes appended using "-" as separator. "lang-en", 452 "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are 453 valid language specification. 455 5.2.5. getAttributes 457 public Enumeration getAttributes() 459 JAVA LDAP API September 1997 461 Returns an enumeration of the attributes in this attribute set. 463 5.2.6. remove 465 public synchronized void remove(String name) 467 Removes the specified attribute from the set. If the attribute is not 468 a member of the set, nothing happens. 470 Parameters are: 472 name Name of the attribute to remove from this set. To 473 remove an LDAPAttribute by object, the 474 LDAPAttribute.getName method can be used: 476 LDAPAttributeSet.remove( attr.getName() ); 478 5.2.7. removeElementAt 480 public void removeElementAt(int index) 481 throws ArrayIndexOutOfBoundsException 483 Removes the attribute at the position specified by the index. The 484 index is 0-based. 486 Parameters are: 488 index Index of the attribute to remove. 490 5.2.8. size 492 public int size() 494 Returns the number of attributes in this set. 496 5.3. public class LDAPCompareAttrNames implements LDAPEntryComparator 498 An object of this class supports sorting search results by attribute 499 name, in ascending or descending order. 501 5.3.1. Constructors 503 public LDAPCompareAttrNames(String attrName) 505 JAVA LDAP API September 1997 507 Constructs an object that will sort results by a single attribute, in 508 ascending order. 510 public LDAPCompareAttrNames(String attrName, 511 boolean ascendingFlag) 513 Constructs an object that will sort results by a single attribute, in 514 either ascending or descending order. 516 public LDAPCompareAttrNames(String[] attrNames) 518 Constructs an object that will sort by one or more attributes, in the 519 order provided, in ascending order. 521 public LDAPCompareAttrNames(String[] attrNames, 522 boolean[] ascendingFlags) 523 throws LDAPException 525 Constructs an object that will sort by one or more attributes, in the 526 order provided, in either ascending or descending order for each 527 attribute. 529 Parameters are: 531 attrName Name of an attribute to sort by. 533 attrNames Array of names of attributes to sort by. 535 ascendingFlag true to sort in ascending order, false for descending 536 order. 538 ascendingFlags Array of flags, one for each attrName, where each one 539 is true to sort in ascending order, false for des- 540 cending order. An LDAPException is thrown if the 541 length of ascendingFlags is not greater than or equal 542 to the length of attrNames. 544 5.3.2. isGreater 546 public boolean isGreater (LDAPEntry entry1, LDAPEntry entry2) 548 Returns true if entry1 is to be considered greater than entry2, for 549 the purpose of sorting, based on the attribute name or names provided 550 on object construction. 552 JAVA LDAP API September 1997 554 Parameters are: 556 entry1 Target entry for comparison. 558 entry2 Entry to be compared to. 560 5.4. public class LDAPConnection implements LDAPv3, Cloneable 562 LDAPConnection is the central class that encapsulates the connection to 563 a Directory Server through the LDAP protocol. It implements the LDAPv2 564 and LDAPv3 interfaces. An LDAPConnection object is not connected on con- 565 struction, and may only be connected to one server at one port. Multiple 566 threads may share this single connection, and an application may have 567 more than one LDAPConnection object, connected to the same or different 568 Directory Servers. 570 Besides the methods described for LDAPv2 and LDAPv3, LDAPConnection pro- 571 vides the following methods. 573 5.4.1. Constructors 575 public LDAPConnection() 577 Constructs a new LDAPConnection object, which represents a connection 578 to an LDAP server. 580 Calling the constructor does not actually establish the connection. 581 To connect to the LDAP server, use the connect method. 583 public LDAPConnection(LDAPSocketFactory factory) 585 Constructs a new LDAPConnection object, which will use the supplied 586 class factory to construct a socket connection during 587 LDAPConnection.connect(). 589 Parameters are: 591 factory An object capable of producing a Socket. 593 5.4.2. clone 595 public LDAPConnection clone() 597 Returns a copy of the object with a private context, but sharing the 598 network connection if there is one. The network connection remains 600 JAVA LDAP API September 1997 602 open until all clones have disconnected or gone out of scope. Any 603 connection opened after cloning is private to the object making the 604 connection. 606 5.4.3. getAuthenticationDN 608 public String getAuthenticationDN() 610 Returns the distinguished name (DN) used for authentication by this 611 object. 613 5.4.4. getAuthenticationPassword 615 public String getAuthenticationPassword() 617 Returns the password used for simple authentication by this object. 619 5.4.5. getHost 621 public String getHost() 623 Returns the host name of the LDAP server to which the object is or 624 was last connected, in the format originally specified. 626 5.4.6. getPort 628 public int getPort() 630 Returns the port number of the LDAP server to which the object is or 631 was last connected. 633 5.4.7. getProperty 635 public Object getProperty(String name) throws LDAPException 637 Gets a property of a connection object. 639 Parameters are: 641 name Name of the property to be returned. 643 The following read-only properties are available for 644 any given connection: 646 JAVA LDAP API September 1997 648 LDAP_PROPERTY_SDK The version of this SDK, as a Float 649 data type. 651 LDAP_PROPERTY_PROTOCOL The highest supported version of the 652 LDAP protocol, as a Float data type. 654 LDAP_PROPERTY_SECURITY A comma-separated list of the types 655 of authentication supported, as a 656 String. 658 Other properties may be available in particular implementations of 659 the class, and used to modify operations such as search. 661 An LDAPException is thrown if the requested property is not avail- 662 able. 664 5.4.8. getSearchConstraints 666 public LDAPSearchConstraints getSearchConstraints() 668 Returns the set of search constraints that apply to all searches per- 669 formed through this connection (unless a different set of search con- 670 straints is specified when calling the search method). 672 Note that the getOption method can be used to get individual con- 673 straints (rather than getting the entire set of constraints). 675 Typically, the getSearchConstraints method is used to create a 676 slightly different set of search constraints to apply to a particular 677 search. 679 5.4.9. getSocketFactory 681 public static LDAPSocketFactory getSocketFactory() 683 Returns the default LDAPSocketFactory used to establish a connection 684 to a server. 686 5.4.10. isAuthenticated 688 public boolean isAthenticated() 690 Indicates whether the object has authenticated to the connected LDAP 691 server. 693 JAVA LDAP API September 1997 695 5.4.11. isConnected 697 public boolean isConnected() 699 Indicates whether the connection represented by this object is open 700 at this time. 702 5.4.12. read 704 public static LDAPEntry read(LDAPUrl toGet) throws LDAPException 706 Reads the entry specified by the LDAP URL. 708 When this method is called, a new connection is created automati- 709 cally, using the host and port specified in the URL. After finding 710 the entry, the method closes the connection (in other words, it 711 disconnects from the LDAP server). 713 If the URL specifies a filter and scope, these are not used. Of the 714 information specified in the URL, this method only uses the LDAP host 715 name and port number, the base distinguished name (DN), and the list 716 of attributes to return. 718 The method returns the entry specified by the base DN. 720 Parameters are: 722 toGet LDAP URL specifying the entry to read. 724 5.4.13. search 726 public static LDAPSearchResults search(LDAPUrl toGet) throws LDAPEx- 727 ception 729 Performs the search specified by the LDAP URL, returning an enumer- 730 able LDAPSearchResults object. 732 public static LDAPSearchResults search(LDAPUrl toGet, 733 LDAPSearchConstraints cons) 734 throws LDAPException 736 Perfoms the search specified by the LDAP URL. This method also allows 737 specifying constraints for the search (such as the maximum number of 738 entries to find or the maximum time to wait for search results). 740 JAVA LDAP API September 1997 742 As part of the search constraints, a choice can be made as to whether 743 to have the results delivered all at once or in smaller batches. If 744 the results are to be delivered in smaller batches, each iteration 745 blocks only until the next batch of results is returned. 747 Parameters are: 749 toGet LDAP URL specifying the entry to read. 751 cons Constraints specific to the search. 753 5.4.14. setOption 755 public void setOption(int option, 756 Object value) 757 throws LDAPException 759 Sets the value of the specified option for this LDAPConnection 760 object. 762 These options represent the default search constraints for the 763 current connection. Some of these options are also propagated through 764 the LDAPSearchConstraints, which can be obtained from the connection 765 object with the getSearchConstraints method. 767 The option that is set here applies to all subsequent searches per- 768 formed through the current connection, unless it is overridden with 769 an LDAPSearchConstraints at the time of search. 771 To set a constraint only for a particular search, create an LDAPSear- 772 chConstraints object with the new constraints and pass it to the 773 LDAPConnection.search method. 775 Parameters are: 777 option One of the following options: 779 Option Type Description 781 LDAPv2.DEREF Integer Specifies under what 782 circumstances the object 783 dereferences aliases. 784 By default, the value of 785 this option is 787 JAVA LDAP API September 1997 789 LDAPv2.DEREF_NEVER. 791 Legal values for this option are: 793 LDAPv2.DEREF_NEVER Aliases are never dereferenced. 795 LDAPv2.DEREF_FINDING aliases are dereferenced when find- 796 ing the starting point for the 797 search (but not when searching 798 under that starting entry). 800 LDAPv2.DEREF_SEARCHING Aliases are dereferenced when 801 searching the entries beneath the 802 starting point of the search (but 803 not when finding the starting 804 entry). 806 LDAPv2.DEREF_ALWAYS Aliases are always dereferenced 807 (both when finding the starting 808 point for the search and when 809 searching under that starting 810 entry). 812 LDAPv2.SIZELIMIT Integer Specifies the maximum 813 number of search results 814 to return. If this 815 option is set to 0, 816 there is no maximum 817 limit. 819 By default, the value of 820 this option is 1000. 822 LDAPv2.TIMELIMIT Integer Specifies the maximum 823 number of milliseconds 824 to wait for results 825 before timing out. If 826 this option is set to 0, 827 there is no maximum time 828 limit. The actual granu- 829 larity of the timeout 830 depends on the implemen- 831 tation. 833 JAVA LDAP API September 1997 835 By default, the value of 836 this option is 0. 838 LDAPv2.REFERRALS Boolean Specifies whether or not 839 the client follows 840 referrals automatically. 841 If true, the client fol- 842 lows referrals automati- 843 cally. If false, an 844 LDAPReferralException is 845 raised when a referral 846 is detected. 848 Referrals of any type 849 other to an LDAP server 850 (i.e. a referral URL 851 other than 852 ldap://something) are 853 ignored on automatic 854 referral following. 856 By default, the value of 857 this option is false. 859 LDAPv2.REFERRALS_REBIND_PROC LDAPRebind Specifies an object that 860 implements the LDAPRe- 861 bind interface. A user 862 of the class library 863 must define this class 864 and the getRebindAuthen- 865 tication method that 866 will be used to get the 867 distinguished name and 868 password to use for 869 authentication. If this 870 value is null and REFER- 871 RALS is true, referrals 872 will be followed with 873 anonymous (= no) authen- 874 tication. 876 By default, the value of 877 this option is null. 879 LDAPv2.REFERRALS_HOP_LIMIT Integer Specifies the maximum 881 JAVA LDAP API September 1997 883 number of referrals in a 884 sequence that the client 885 will follow. For exam- 886 ple, if 887 REFERRALS_HOP_LIMIT is 888 5, the client will fol- 889 low no more than 5 890 referrals in a row when 891 resolving a single LDAP 892 request. 894 The default value of 895 this option is 10. 897 LDAPv2.BATCHSIZE Integer Specifies the number of 898 search results to return 899 at a time. For example, 900 if BATCHSIZE is 1, 901 enumerating an LDAPSear- 902 chResults will block 903 only until one entry is 904 available. If it is 0, 905 enumerating will block 906 until all entries have 907 been retrieved from the 908 server. 910 The default value of 911 this option is 1. 913 value The value to assign to the option. The value must be 914 the java.lang object wrapper for the appropriate 915 parameter (e.g. boolean->Boolean, int->Integer) . 917 5.4.15. setProperty 919 public void setProperty(String name, Object value) throws LDAPExcep- 920 tion 922 Sets a property of a connection object. 924 No property names have been defined at this time, but the mechanism 925 is in place in order to support revisional as well as dynamic exten- 926 sions to operation modifiers. 928 JAVA LDAP API September 1997 930 Parameters are: 932 name Name of the property to set. 934 value Value to assign to the property. 936 An LDAPException is thrown if the specified property 937 is not supported. 939 5.4.16. setSocketFactory 941 public static void setSocketFactory(LDAPSocketFactory factory) 943 Establishes the default LDAPSocketFactory used to establish a connec- 944 tion to a server. 946 This method is implemented as once-only. It is useful to be able to 947 change the run-time connection behavior of a whole application with a 948 single instruction, but the results would be confusing, and the 949 side-effects dangerous, if the global default factory could be 950 changed at arbitrary times by different threads. It should be called 951 before the first connect(). If called (for the first time) after con- 952 necting, the new factory will not be used until/unless a new connec- 953 tion is attempted with the object. 955 A typical usage would be: 957 if (usingTLS) { 958 LDAPConnection.setSocketFactory(myTLSFactory); 959 } 960 ... 961 LDAPConnection conn = new LDAPConnection(); 962 conn.connect(myHost, myPort); 964 In this example, connections are constructed with the default LDAP- 965 SocketFactory. At application start-up time, the default may be set 966 to use a particular provided TLS socket factory. 968 Parameters are: 970 factory A factory object which can construct socket connec- 971 tions for an LDAPConnection. 973 5.5. public class LDAPControl implements Cloneable 975 An LDAPControl encapsulates optional additional parameters or con- 976 straints to be applied to LDAP operations. If set as a Server Control, 978 JAVA LDAP API September 1997 980 it is sent to the server along with operation requests. If set as a 981 Client Control, it is not sent to the server, but rather interpreted 982 locally by the client. LDAPControl is an LDAPv3 extension, and is not 983 supported in an LDAPv2 environment. 985 5.5.1. Constructors 987 public LDAPControl(String id, 988 boolean critical, 989 byte vals[]) 991 Parameters are: 993 id The type of the Control, as a string. 995 critical True if the LDAP operation should be discarded if the 996 server does not support this Control. 998 vals Control-specific data. 1000 5.5.2. getID 1002 public String getID() 1004 Returns the identifier of the control. 1006 5.5.3. isCritical 1008 public boolean isCritical() 1010 Returns true if the control must be supported for an associated 1011 operation to be executed. 1013 5.5.4. getValue 1015 public byte[] getValue() 1017 Returns the control-specific data of the object. 1019 5.6. public class LDAPDN 1021 A utility class representing a distinguished name (DN). 1023 JAVA LDAP API September 1997 1025 5.6.1. explodeDN 1027 public static String[] explodeDN(String dn, 1028 boolean noTypes) 1030 Returns the individual components of a distinguished name (DN). 1032 Parameters are: 1034 dn Distinguished name, e.g. "cn=Babs 1035 Jensen,ou=Accounting,o=Acme,c=us" 1037 noTypes If true, returns only the values of the components, 1038 and not the names, e.g. "Babs Jensen", "Accounting", 1039 "Acme", "us" - instead of "cn=Babs Jensen", 1040 "ou=Accounting", "o=Acme", and "c=us". 1042 5.6.2. explodeRDN 1044 public static String[] explodeRDN(String rdn, 1045 boolean noTypes) 1047 Returns the individual components of a relative distinguished name 1048 (RDN). 1050 Parameters are: 1052 rdn Relative distinguished name, i.e. the left-most com- 1053 ponent of a distinguished name. 1055 noTypes If true, returns only the values of the components, 1056 and not the names. 1058 5.7. public class LDAPEntry 1060 An LDAPEntry represents a single entry in a directory, consisting of a 1061 distinguished name (DN) and zero or more attributes. An instance of 1062 LDAPEntry is created in order to add an entry to a Directory, and 1063 instances are returned on a search by enumerating an LDAPSearchResults. 1065 5.7.1. Constructors 1067 public LDAPEntry() 1069 Constructs an empty entry. 1071 JAVA LDAP API September 1997 1073 public LDAPEntry(String dn) 1075 Constructs a new entry with the specified distinguished name and with 1076 an empty attribute set. 1078 public LDAPEntry(String dn 1079 LDAPAttributeSet attrs) 1081 Constructs a new entry with the specified distinguished name and set 1082 of attributes. 1084 Parameters are: 1086 dn The distinguished name of the new entry. The value is 1087 not validated. An invalid distinguished name will 1088 cause adding of the entry to a directory to fail. 1090 attrs The initial set of attributes assigned to the entry. 1092 5.7.2. getAttribute 1094 public LDAPAttribute[] getAttribute(String attrName) 1096 Returns the attribute matching the specified attrName. For example, 1097 getAttribute("cn") returns only the "cn" attribute; 1098 getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute. 1099 In both cases, null is returned if there is no exact match to the 1100 specified attrName. 1102 public LDAPAttribute[] getAttribute(String attrName, String lang) 1104 Returns a single best-match attribute, or none if no match is avail- 1105 able in the entry. 1107 LDAP version 3 allows adding a subtype specification to an attribute 1108 name. "cn;lang-ja", for example, indicates a Japanese language sub- 1109 type of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype of 1110 "cn;lang-ja". This feature may be used to provide multiple localiza- 1111 tions in the same Directory. For attributes which do not vary among 1112 localizations, only the base attribute may be stored, whereas for 1113 others there may be varying degrees of specialization. 1115 getAttribute(attrName,lang) returns the subtype that matches attrName 1116 and that best matches lang. If there are subtypes other than "lang" 1117 subtypes included in attrName, e.g. "cn;binary", only attributes with 1118 all of those subtypes are returned. If lang is null or empty, the 1120 JAVA LDAP API September 1997 1122 method behaves as getAttribute(attrName). If there are no matching 1123 attributes, null is returned. 1125 Example: 1126 Assume the entry contains only the following attributes: 1127 cn;lang-en 1128 cn;lang-ja-JP-kanji 1129 sn 1130 getAttribute( "cn" ) returns null. 1131 getAttribute( "sn" ) returns the "sn" attribute. 1132 getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute. 1133 getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute. 1134 getAttribute( "cn", "lang-ja" ) returns null. 1135 getAttribute( "sn", "lang-en" ) returns the "sn" attribute. 1137 Parameters are: 1139 attrName The name of an attribute to retrieve, with or without 1140 subtype specification(s). "cn", "cn;phonetic", and 1141 "cn;binary" are valid attribute names. 1143 lang A language specification as in [14], with optional 1144 subtypes appended using "-" as separator. "lang-en", 1145 "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are 1146 valid language specification. 1148 5.7.3. getAttributeSet 1150 public LDAPAttributeSet getAttributeSet() 1152 Returns the attribute set of the entry. All base and subtype variants 1153 of all attributes are returned. The LDAPAttributeSet returned may be 1154 empty if there are no attributes in the entry. 1156 public LDAPAttributeSet getAttributeSet(String subtype) 1158 Returns an attribute set from the entry, consisting of only those 1159 attributes matching the specified subtype(s). This may be used to 1160 extract only a particular language variant subtype of each attribute, 1161 if it exists. "subtype" may be, for example, "lang-ja", "binary", or 1162 "lang-ja;phonetic". If more than one subtype is specified, separated 1163 with a semicolon, only those attributes with all of the named sub- 1164 types will be returned. The LDAPAttributeSet returned may be empty 1165 if there are no matching attributes in the entry. 1167 Parameters are: 1169 JAVA LDAP API September 1997 1171 subtype One or more subtype specification(s), separated with 1172 semicolons. "lang-ja" and "lang-en;phonetic" are 1173 valid subtype specifications. 1175 5.7.4. getDN 1177 public String getDN() 1179 Returns the distinguished name of the entry. 1181 5.8. public class LDAPExtendedOperation 1183 An LDAPExtendedOperation encapsulates an ID which uniquely identifies a 1184 particular extended operation, known to a particular server, and the 1185 data associated with the operation. 1187 5.8.1. Constructors 1189 public LDAPExtendedOperation(String oid, 1190 byte[] vals) 1192 Constructs a new object with the specified object ID and data. 1194 Parameters are: 1196 oid The unique identifier of the operation. 1198 vals The operation-specific data of the operation/ 1200 5.8.2. getID 1202 public String getID() 1204 Returns the unique identifier of the operation. 1206 5.8.3. getValue 1208 public byte[] getValue() 1210 Returns the operation-specific data (not a copy, a reference). 1212 JAVA LDAP API September 1997 1214 5.9. public interface LDAPEntryComparator 1216 An object of this class can implement arbitrary sorting algorithms for 1217 search results. 1219 5.9.1. isGreater 1221 public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2) 1223 Returns true if entry1 is to be considered greater than or equal to 1224 entry2, for the purpose of sorting. 1226 Parameters are: 1228 entry1 Target entry for comparison. 1230 entry2 Entry to be compared to. 1232 5.10. public class LDAPException extends Exception 1234 Thrown to indicate that an error has occurred. An LDAPException can 1235 result from physical problems (such as network errors) as well as prob- 1236 lems with LDAP operations (for example, if the LDAP add operation fails 1237 because of a duplicate entry). 1239 Most errors that occur throw this type of exception. The 1240 getLDAPResultCode() method returns the specific result code, which can 1241 be compared against standard LDAP result codes as defined in [11], sec- 1242 tion 4. 1244 5.10.1. Constructors 1246 public LDAPException() 1248 Constructs a default exception with no specific error information. 1250 public LDAPException(String message, 1251 int resultCode) 1253 Constructs an exception with an error code and a specified string as 1254 additional information. 1256 Parameters are: 1258 JAVA LDAP API September 1997 1260 message The additional error information. 1262 resultCode The result code returned 1264 5.10.2. getLDAPErrorMessage 1266 public String getLDAPErrorMessage() 1268 Returns the error message, if this message is available (that is, if 1269 this message was set). If the message was not set, this method 1270 returns null. 1272 5.10.3. getLDAPResultCode 1274 public int getLDAPResultCode() 1276 Returns the result code from the exception. The codes are defined as 1277 public final static int members of this class. If the exception is a 1278 result of error information returned from a directory operation, the 1279 code will be one of those defined in [11]. Otherwise, a local error 1280 code is returned (see "Error codes" below). 1282 5.10.4. getMatchedDN 1284 public String getMatchedDN() 1286 Returns the part of a submitted distinguished name which could be 1287 matched by the server. If the exception was caused by a local error, 1288 such as no server available, the return value is null. If the excep- 1289 tion resulted from an operation being executed on a server, the value 1290 is an empty String except when the result of the operation was one of 1291 the following: 1293 NO_SUCH_OBJECT 1294 ALIAS_PROBLEM 1295 INVALID_DN_SYNTAX 1296 ALIAS_DEREFERENCING_PROBLEM 1298 5.10.5. Error codes 1300 See [11] and [7] for a discussion of the meanings of the codes. 1302 ADMIN_LIMIT_EXCEEDED 1303 AFFECTS_MULTIPLE_DSAS 1304 ALIAS_DEREFERENCING_PROBLEM 1306 JAVA LDAP API September 1997 1308 ALIAS_PROBLEM 1309 ATTRIBUTE_OR_VALUE_EXISTS 1310 AUTH_METHOD_NOT_SUPPORTED 1311 BUSY 1312 COMPARE_FALSE 1313 COMPARE_TRUE 1314 CONFIDENTIALITY_REQUIRED 1315 CONSTRAINT_VIOLATION 1316 ENTRY_ALREADY_EXISTS 1317 INAPPROPRIATE_AUTHENTICATION 1318 INAPPROPRIATE_MATCHING 1319 INSUFFICIENT_ACCESS_RIGHTS 1320 INVALID_ATTRIBUTE_SYNTAX 1321 INVALID_CREDENTIALS 1322 INVALID_DN_SYNTAX 1323 IS_LEAF 1324 LDAP_PARTIAL_RESULTS 1325 LOOP_DETECT 1326 NAMING_VIOLATION 1327 NO_SUCH_ATTRIBUTE 1328 NO_SUCH_OBJECT 1329 NOT_ALLOWED_ON_NONLEAF 1330 NOT_ALLOWED_ON_RDN 1331 OBJECT_CLASS_MODS_PROHIBITED 1332 OBJECT_CLASS_VIOLATION 1333 OPERATIONS_ERROR 1334 OTHER 1335 PROTOCOL_ERROR 1336 REFERRAL 1337 SIZE_LIMIT_EXCEEDED 1338 STRONG_AUTH_NOT_SUPPORTED 1339 STRONG_AUTH_REQUIRED 1340 SUCCESS 1341 TIME_LIMIT_EXCEEDED 1342 UNAVAILABLE 1343 UNAVAILABLE_CRITICAL_EXTENSION 1344 UNDEFINED_ATTRIBUTE_TYPE 1345 UNWILLING_TO_PERFORM 1347 Local errors, resulting from actions other than an operation on a 1348 server, are among the following: 1350 CONNECT_ERROR 1351 PARAM_ERROR 1352 SERVER_DOWN 1354 JAVA LDAP API September 1997 1356 5.11. public class LDAPModification 1358 A single change specification for an LDAPAttribute. 1360 5.11.1. Constructors 1362 public LDAPModification(int op, 1363 LDAPAttribute attr) 1365 Specifies a modification to be made to an attribute. 1367 Parameters are: 1369 op The type of modification to make, which can be one of 1370 the following: 1372 LDAPModification.ADD The value should be added to the attri- 1373 bute 1375 LDAPModification.DELETE The value should be removed from the 1376 attribute 1378 LDAPModification.REPLACE The value should replace all existing 1379 values of the attribute 1381 attr The attribute (possibly with values) to be modified. 1383 5.11.2. getAttribute 1385 public LDAPAttribute getAttribute() 1387 Returns the attribute (possibly with values) to be modified. 1389 5.11.3. getOp 1391 public int getOp() 1393 Returns the type of modification specified by this object. 1395 5.12. public class LDAPModificationSet 1397 A collection of modifications to be made to the attributes of a single 1398 entry. 1400 JAVA LDAP API September 1997 1402 5.12.1. Constructors 1404 public LDAPModificationSet() 1406 Constructs a new, empty set of modifications. 1408 5.12.2. add 1410 public synchronized void add(int op, 1411 LDAPAttribute attr) 1413 Specifies another modification to be added to the set of modifica- 1414 tions. 1416 Parameters are: 1418 op The type of modification to make, as described for 1419 LDAPModification. 1421 attr The attribute (possibly with values) to be modified. 1423 5.12.3. elementAt 1425 public LDAPModification elementAt(int index) 1426 throws ArrayIndexOutOfBoundsException 1428 Retrieves a particular LDAPModification object at the position speci- 1429 fied by the index. 1431 Parameters are: 1433 index Index of the modification to get. 1435 5.12.4. remove 1437 public synchronized void remove(String name) 1439 Removes the first attribute with the specified name in the set of 1440 modifications. 1442 Parameters are: 1444 name Name of the attribute to be removed. 1446 JAVA LDAP API September 1997 1448 5.12.5. removeElementAt 1450 public void removeElementAt(int index) 1451 throws ArrayIndexOutOfBoundsException 1453 Removes a particular LDAPModification object at the position speci- 1454 fied by the index. 1456 index Index of the modification to remove. 1458 5.12.6. size 1460 public int size() 1462 Retrieves the number of LDAPModification objects in this set. 1464 5.13. public class LDAPRebindAuth 1466 Represents information used to authenticate the client in cases where 1467 the client follows referrals automatically. 1469 5.13.1. Constructors 1471 public LDAPRebindAuth(String dn, 1472 String password) 1474 Constructs information that is used by the client for authentication 1475 when following referrals automatically. 1477 5.13.2. getDN 1479 public String getDN() 1481 Returns the distinguished name to be used for reauthentication on 1482 automatic referral following. 1484 5.13.3. getPassword 1486 public String getPassword() 1488 Returns the password to be used for reauthentication on automatic 1489 referral following. 1491 JAVA LDAP API September 1997 1493 5.14. public class LDAPReferralException extends LDAPException 1495 This exception, derived from LDAPException, is thrown when a server 1496 returns a referral and automatic referral following has not been 1497 enabled. 1499 5.14.1. Constructors 1501 public LDAPReferralException() 1503 Constructs a default exception with no specific error information. 1505 public LDAPReferralException(String message) 1507 Constructs a default exception with a specified string as additional 1508 information. This form is used for lower-level errors. 1510 public LDAPReferralException(String message, 1511 int resultCode, 1512 String serverMessage) 1514 Parameters are: 1516 message The additional error information. 1518 resultCode The result code returned 1520 serverMessage Error message specifying additional information from 1521 the server. 1523 5.14.2. getURLs 1525 public LDAPUrl[] getURLs() 1527 Gets the list of referrals (LDAP URLs to other servers) returned by 1528 the LDAP server. This exception is only thrown, and therefor the URL 1529 list only available, if automatic referral following is not enabled. 1530 The referrals may include URLs of a type other than ones for an LDAP 1531 server (i.e. a referral URL other than ldap://something). 1533 5.15. public class LDAPSearchConstraints 1535 A set of options to control a search operation. There is always an 1537 JAVA LDAP API September 1997 1539 LDAPSearchConstraints associated with an LDAPConnection object; its 1540 values can be changed with LDAPConnection.setOption, or overridden by 1541 passing an LDAPSearchConstraints object to the search operation. 1543 5.15.1. Constructors 1545 public LDAPSearchConstraints() 1547 Constructs an LDAPSearchConstraints object that specifies the default 1548 set of search constraints. 1550 public LDAPSearchConstraints(int msLimit, 1551 int dereference, 1552 int maxResults, 1553 boolean doReferrals, 1554 int batchSize, 1555 LDAPRebind rebind_proc, 1556 int hop_limit) 1558 Constructs a new LDAPSearchConstraints object and allows specifying 1559 the search constraints in that object. 1561 Parameters are: 1563 msLimit Maximum time in milliseconds to wait for results (0 1564 by default, which means that there is no maximum time 1565 limit). 1567 dereference Specifies when aliases should be dereferenced. Must 1568 be either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, 1569 LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from 1570 LDAPv2 (LDAPv2.LDAP_DEREF_NEVER by default). 1572 maxResults Maximum number of search results to return (1000 by 1573 default). 1575 doReferrals Specify true to follow referrals automatically, or 1576 false to throw an LDAPReferralException error if the 1577 server sends back a referral (false by default) 1579 batchSize Specify the number of results to block on during 1580 enumeration. 0 means to block until all results are 1581 in (1 by default). 1583 rebind_proc Specifies an object of the class that implements the 1584 LDAPRebind interface. The object will be used when 1586 JAVA LDAP API September 1997 1588 the client follows referrals automatically. The 1589 object provides a method for getting the dis- 1590 tinguished name and password used to authenticate to 1591 another LDAP server during a referral. This field is 1592 null by default. 1594 hop_limit Maximum number of referrals to follow in a sequence 1595 when attempting to resolve a request, when doing 1596 automatic referral following. 1598 5.15.2. getBatchSize 1600 public int getBatchSize() 1602 Returns the number of results to block on during enumeration of 1603 search results. This should be 0 if intermediate results are not 1604 needed, and 1 if results are to be processed as they come in. 1606 5.15.3. getDereference 1608 public int getDereference() 1610 Specifies when aliases should be dereferenced. Returns either 1611 LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or 1612 LDAP_DEREF_ALWAYS from LDAPv2. 1614 5.15.4. getHopLimit 1616 public int getHopLimit() 1618 Returns the maximum number of hops to follow during automatic refer- 1619 ral following. 1621 5.15.5. getMaxResults 1623 public int getMaxResults() 1625 Returns the maximum number of search results to be returned; 0 means 1626 no limit. 1628 5.15.6. getRebindProc 1630 public LDAPRebind getRebindProc() 1632 JAVA LDAP API September 1997 1634 Returns the object that provides the method for getting authentica- 1635 tion information. 1637 5.15.7. getReferrals 1639 public boolean getReferrals() 1641 Specifies whether nor not referrals are followed automatically. 1642 Returns true if referrals are to be followed automatically, or false 1643 if referrals throw an LDAPReferralException. 1645 5.15.8. getTimeLimit 1647 public int getTimeLimit() 1649 Returns the maximum number of milliseconds to wait for any operation 1650 under these search constraints. If 0, there is no maximum time limit 1651 on waiting for the operation results. The actual granularity of the 1652 timeout depends on the implementation. 1654 5.15.9. setBatchSize 1656 public void setBatchSize(int batchSize) 1658 Sets the suggested number of results to block on during enumeration 1659 of search results. This should be 0 if intermediate results are not 1660 needed, and 1 if results are to be processed as they come in. The 1661 default is 1. 1663 Parameters are: 1665 batchSize Blocking size on search enumerations. 1667 5.15.10. setDereference 1669 public void setDereference(int dereference) 1671 Sets a preference indicating whether or not aliases should be 1672 dereferenced, and if so, when. 1674 Parameters are: 1676 dereference Either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, 1677 LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from 1679 JAVA LDAP API September 1997 1681 LDAPv2. 1683 5.15.11. setHopLimit 1685 public void setHopLimit(int hop_limit) 1687 Sets the maximum number of hops to follow in sequence during 1688 automatic referral following. The default is 5. 1690 Parameters are: 1692 hop_limit Maximum number of chained referrals to follow 1693 automatically. 1695 5.15.12. setMaxResults 1697 public void setMaxResults(int maxResults) 1699 Sets the maximum number of search results to be returned; 0 means no 1700 limit. The default is 1000. 1702 Parameters are: 1704 maxResults Maxumum number of search results to return. 1706 5.15.13. setRebindProc 1708 public void setRebindProc(LDAPRebind rebind_proc) 1710 Specifies the object that provides the method for getting authentica- 1711 tion information. The default is null. If referrals is set to true, 1712 and the rebindProc is null, referrals will be followed with anonymous 1713 (= no) authentication. 1715 Parameters are: 1717 rebind_proc An object that implements LDAPRebind. 1719 5.15.14. setReferrals 1721 public void setReferrals(boolean doReferrals) 1723 Specifies whether nor not referrals are followed automatically, or if 1724 referrals throw an LDAPReferralException. Referrals of any type 1726 JAVA LDAP API September 1997 1728 other to an LDAP server (i.e. a referral URL other than 1729 ldap://something) are ignored on automatic referral following. The 1730 default is false. 1732 Parameters are: 1734 doReferrals True to follow referrals automatically. 1736 5.15.15. setTimeLimit 1738 public void setTimeLimit(int msLimit) 1740 Sets the maximum number of milliseconds to wait for any operation 1741 under these search constraints. If 0, there is no maximum time limit 1742 on waiting for the operation results. The actual granularity of the 1743 timeout depends on the implementation. 1745 Parameters are: 1747 msLimit Maximum milliseconds to wait. 1749 5.16. public class LDAPSearchResults 1751 An LDAPSearchResults object is returned from a search operation. It 1752 implements Enumeration, thereby providing access to all entries 1753 retrieved during the operation. 1755 5.16.1. hasMoreElements 1757 public boolean hasMoreElements() 1759 Specifies whether or not there are more search results in the 1760 enumeration. If true, there are more search results. 1762 5.16.2. next 1764 public LDAPEntry next() throws LDAPException 1766 Returns the next result in the enumeration as an LDAPEntry. If 1767 automatic referral following is disabled, and there are one or more 1768 referrals among the search results, next() will throw an LDAPRefer- 1769 ralException the last time it is called, after all other results have 1770 been returned. 1772 JAVA LDAP API September 1997 1774 5.16.3. nextElement 1776 public Object nextElement() 1778 Returns the next result in the enumeration as an Object. This the 1779 default implementation of Enumeration.nextElement(). The returned 1780 value may be an LDAPEntry or an LDAPReferralException. 1782 5.16.4. sort 1784 public void sort(LDAPEntryComparator comp) 1786 Sorts all entries in the results using the provided comparison 1787 object. If the object has been partially or completely enumerated, 1788 only remaining elements are sorted. Sorting the results requires that 1789 they all be present. This implies that 1790 LDAPSearchResults.nextElement() will always block until all results 1791 have been retrieved, after a sort operation. 1793 The LDAPCompareAttrNames class is provided to support the common need 1794 to collate by a single or multiple attribute values, in ascending or 1795 descending order. Examples are: 1797 res.sort(new LDAPCompareAttrNames("cn")); 1799 res.sort(new LDAPCompareAttrNames("cn", false)); 1801 String[] attrNames = { "sn", "givenname" }; 1802 res.sort(new LDAPCompareAttrNames(attrNames)); 1804 Parameters are: 1806 comp An object that implements the LDAPEntryComparator 1807 interface to compare two objects of type LDAPEntry. 1809 5.17. public interface LDAPSocketFactory 1811 Used to construct a socket connection for use in an LDAPConnection. An 1812 implementation of this interface may, for example, provide a TLSSocket 1813 connected to a secure server. 1815 5.17.1. makeSocket 1817 public Socket makeSocket(String host, int port) 1818 throws IOException, UnknownHostException 1820 JAVA LDAP API September 1997 1822 Returns a socket connected using the provided host name and port 1823 number. 1825 There may be additional makeSocket methods defined when interfaces to 1826 establish TLS and SASL authentication in the java environment have 1827 been standardized. 1829 Parameters are: 1831 host Contains a hostname or dotted string representing the 1832 IP address of a host running an LDAP server to con- 1833 nect to. 1835 port Contains the TCP or UDP port number to connect to or 1836 contact. The default LDAP port is 389. 1838 5.18. public class LDAPSortKey 1840 Encapsulates parameters for sorting search results. 1842 5.18.1. Constructors 1844 public LDAPSortKey( String keyDescription ) 1846 Constructs a new LDAPSortKey object using a, possibly complex, sort- 1847 ing specification. 1849 public LDAPSortKey( String key, boolean reverse) 1851 Constructs a new LDAPSortKey object using an attribute name and a 1852 sort order. 1854 public LDAPSortKey( String key, boolean reverse, String matchRule) 1856 Constructs a new LDAPSortKey object using an attribute name, a sort 1857 order, and a matching rule. 1859 Parameters are: 1861 keyDescription A single attribute specification to sort by. If pre- 1862 fixed with "-", reverse order sorting is requested. A 1863 matching rule OID may be appended following ":". 1864 Examples: 1865 "cn" 1867 JAVA LDAP API September 1997 1869 "-cn" 1870 "-cn:1.2.3.4.5" 1872 key An attribute name, e.g. "cn". 1874 reverse True to sort in reverse collation order. 1876 matchRule The object ID (OID) of a matching rule used for col- 1877 lation. If the object will be used to request 1878 server-side sorting of search results, it should be 1879 the OID of a matching rule known to be supported by 1880 that server. 1882 5.18.2. getKey 1884 public String getKey() 1886 Returns the attribute to be used for collation. 1888 5.18.3. getReverse 1890 public boolean getReverse() 1892 Returns true if the sort key specifies reverse-order sorting. 1894 5.18.4. getMatchRule 1896 public String getMatchRule() 1898 Returns the OID to be used as matching rule, or null if none is to be 1899 used. 1901 5.19. public class LDAPUrl 1903 Encapsulates parameters of an LDAP Url query, as defined in [8]. An 1904 LDAPUrl object can be passed to LDAPConnection.search to retrieve search 1905 results. 1907 5.19.1. Constructors 1909 public LDAPUrl(String url) throws MalformedURLException 1911 JAVA LDAP API September 1997 1913 Constructs a URL object with the specified string as URL. 1915 public LDAPUrl(String host, 1916 int port, 1917 String dn) 1919 Constructs with the specified host, port, and DN. This form is used 1920 to create URL references to a particular object in the directory. 1922 public LDAPUrl(String host, 1923 int port, 1924 String dn, 1925 String attrNames[], 1926 int scope, 1927 String filter) 1929 Constructs a full-blown LDAP URL to specify an LDAP search operation. 1931 Parameters are: 1933 url An explicit URL string, e.g. 1934 "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn,sn?sub? 1935 (objectclass=inetOrgPerson)". 1937 host Host name of LDAP server, or null for "nearest 1938 X.500/LDAP". 1940 port Port number for LDAP server (use 1941 LDAPConnection.DEFAULT_PORT for default port). 1943 dn Distinguished name of object to fetch. 1945 attrNames Names of attributes to retrieve. null for all attri- 1946 butes. 1948 scope Depth of search (in DN namespace). Use one of 1949 SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPv2. 1951 5.19.2. decode 1953 public static String decode(String URLEncoded) throws MalformedURLEx- 1954 ception 1956 Decodes a URL-encoded string. Any occurences of %HH are decoded to 1957 the hex value represented. However, this routine does NOT decode "+" 1959 JAVA LDAP API September 1997 1961 into " ". See [10] for details on URL encoding/decoding. 1963 Parameters are: 1965 URLEncoded String to decode. 1967 5.19.3. encode 1969 public static String encode(String toEncode) 1971 Encodes an arbitrary string. Any illegal characters are encoded as 1972 %HH. However, this routine does NOT encode " " into "+". 1974 Parameters are: 1976 toEncode String to encode. 1978 5.19.4. getAttributes 1980 public String[] getAttributeArray() 1982 Return an array of attribute names specified in the URL 1984 5.19.5. getAttributes 1986 public Enumeration getAttributes() 1988 Return an Enumerator for the attribute names specified in the URL 1990 5.19.6. getDN 1992 public String getDN() 1994 Return the distinguished name encapsulated in the URL. 1996 5.19.7. getFilter 1998 public String getFilter() 2000 Returns the search filter [8], or the default filter - 2001 (objectclass=*) - if none was specified. 2003 JAVA LDAP API September 1997 2005 5.19.8. getHost 2007 public String getHost() 2009 Returns the host name of the LDAP server to connect to. 2011 5.19.9. getPort 2013 public int getPort() 2015 Returns the port number of the LDAP server to connect to. 2017 5.19.10. getUrl 2019 public String getUrl() 2021 Returns a valid string representation of this LDAP URL. 2023 5.20. public interface LDAPv2 2025 As a mechanism to support planned and future LDAP protocol extensions, 2026 functionality is defined in an interface - LDAPv2, corresponding to ver- 2027 sion 2 of the LDAP protocol. LDAPConnection must implement at least 2028 LDAPv2, and may implement LDAPv3. Applications can test for support of 2029 these protocol levels in a given package with the instanceof operator. 2031 5.20.1. add 2033 public void add(LDAPEntry entry) throws LDAPException 2035 Adds an entry to the directory. 2037 Parameters are: 2039 entry LDAPEntry object specifying the distinguished name 2040 and attributes of the new entry. 2042 5.20.2. authenticate 2044 public void authenticate(String dn, 2045 String passwd) 2046 throws LDAPException 2048 Authenticates to the LDAP server (that the object is currently con- 2049 nected to) using the specified name and password. If the object has 2051 JAVA LDAP API September 1997 2053 been disconnected from an LDAP server, this method attempts to recon- 2054 nect to the server. If the object had already authenticated, the old 2055 authentication is discarded. 2057 Parameters are: 2059 dn If non-null and non-empty, specifies that the connec- 2060 tion and all operations through it should be authen- 2061 ticated with dn as the distinguished name. 2063 passwd If non-null and non-empty, specifies that the connec- 2064 tion and all operations through it should be authen- 2065 ticated with dn as the distinguished name and passwd 2066 as password. 2068 5.20.3. compare 2070 public boolean compare(String dn, 2071 LDAPAttribute attr) 2072 throws LDAPException 2074 Checks to see if an entry contains an attribute with a specified 2075 value. Returns true if the entry has the value, and false if the 2076 entry does not have the value or the attribute. 2078 Parameters are: 2080 dn The distinguished name of the entry to use in the 2081 comparison. 2083 attr The attribute to compare against the entry. The 2084 method checks to see if the entry has an attribute 2085 with the same name and value as this attribute. 2087 5.20.4. connect 2089 public void connect(String host, 2090 int port) 2091 throws LDAPException 2093 Connects to the specified host and port. If this LDAPConnection 2094 object represents an open connection, the connection is closed first 2095 before the new connection is opened. At this point there is no 2096 authentication, and any operations will be conducted as an anonymous 2097 client. 2099 JAVA LDAP API September 1997 2101 public void connect(String host, 2102 int port, 2103 String dn, 2104 String passwd) 2105 throws LDAPException 2107 Connects to the specified host and port and uses the specified DN and 2108 password to authenticate to the server. If this LDAPConnection object 2109 represents an open connection, the connection is closed first before 2110 the new connection is opened. This is equivalent to connect(host, 2111 port) followed by authenticate(dn, passwd). 2113 Parameters are: 2115 host Contains a hostname or dotted string representing the 2116 IP address of a host running an LDAP server to con- 2117 nect to. Alternatively, it may contain a list of host 2118 names, space-delimited. Each host name may include a 2119 trailing colon and port number. In the case where 2120 more than one host name is specified, each host name 2121 in turn will be contacted until a connection can be 2122 established. Examples: 2124 "directory.knowledge.com" 2125 "199.254.1.2" 2126 "directory.knowledge.com:1050 people.catalog.com 199.254.1.2" 2128 port Contains the TCP or UDP port number to connect to or 2129 contact. The default LDAP port is 389. "port" is 2130 ignored for any host name which includes a colon and 2131 port number. 2133 dn If non-null and non-empty, specifies that the connec- 2134 tion and all operations through it should be authen- 2135 ticated with dn as the distinguished name. 2137 passwd If non-null and non-empty, specifies that the connec- 2138 tion and all operations through it should be authen- 2139 ticated with dn as the distinguished name and passwd 2140 as password. 2142 5.20.5. delete 2144 public void delete(String dn) throws LDAPException 2146 Deletes the entry for the specified DN from the directory. 2148 JAVA LDAP API September 1997 2150 Parameters are: 2152 dn Distinguished name of the entry to modify. 2154 5.20.6. disconnect 2156 public synchronized void disconnect() throws LDAPException 2158 Disconnects from the LDAP server. Before the object can perform LDAP 2159 operations again, it must reconnect to the server by calling connect. 2161 5.20.7. getOption 2163 public Object getOption(int option) throws LDAPException 2165 Returns the value of the specified option for this object. 2167 Parameters are: 2169 option See LDAPConnection.setOption for a description of 2170 valid options. 2172 5.20.8. modify 2174 public void modify(String dn, 2175 LDAPModification mod) 2176 throws LDAPException 2178 Makes a single change to an existing entry in the directory (for 2179 example, changes the value of an attribute, adds a new attribute 2180 value, or removes an existing attribute value). 2182 The LDAPModification object specifies both the change to be made and 2183 the LDAPAttribute value to be changed. 2185 public void modify(String dn, 2186 LDAPModificationSet mods) 2187 throws LDAPException 2189 Makes a set of changes to an existing entry in the directory (for 2190 example, changes attribute values, adds new attribute values, or 2191 removes existing attribute values). 2193 JAVA LDAP API September 1997 2195 Parameters are: 2197 dn Distinguished name of the entry to modify. 2199 mod A single change to be made to the entry. 2201 mods A set of changes to be made to the entry. 2203 5.20.9. read 2205 public LDAPEntry read(String dn) throws LDAPException 2207 Reads the entry for the specified distiguished name (DN) and 2208 retrieves all attributes for the entry. 2210 public LDAPEntry read(String dn, 2211 String attrs[]) 2212 throws LDAPException 2214 Reads the entry for the specified distinguished name (DN) and 2215 retrieves only the specified attributes from the entry. 2217 Parameters are: 2219 dn Distinguished name of the entry to retrieve. 2221 attrs Names of attributes to retrieve. 2223 5.20.10. rename 2225 public void rename(String dn, 2226 String newRdn, 2227 boolean deleteOldRdn) 2228 throws LDAPException 2230 Renames an existing entry in the directory. 2232 Parameters are: 2234 dn Current distinguished name of the entry. 2236 newRdn New relative distinguished name for the entry. 2238 deleteOldRdn If true, the old name is not retained as an attribute 2239 value. 2241 JAVA LDAP API September 1997 2243 5.20.11. search 2245 public LDAPSearchResults search(String base, 2246 int scope, 2247 String filter, 2248 String attrs[], 2249 boolean attrsOnly) 2250 throws LDAPException 2252 Performs the search specified by the parameters. 2254 public LDAPSearchResults search(String base, 2255 int scope, 2256 String filter, 2257 String attrs[], 2258 boolean attrsOnly, 2259 LDAPSearchConstraints cons) 2260 throws LDAPException 2262 Performs the search specified by the parameters, also allowing 2263 specification of constraints for the search (such as the maximum 2264 number of entries to find or the maximum time to wait for search 2265 results). 2267 As part of the search constraints, the function allows specifying 2268 whether or not the results are to be delivered all at once or in 2269 smaller batches. If specified that the results are to be delivered in 2270 smaller batches, each iteration blocks only until the next batch of 2271 results is returned. 2273 Parameters are: 2275 base The base distinguished name to search from. 2277 scope The scope of the entries to search. The following are 2278 the valid options: 2280 LDAPv2.SCOPE_BASE Search only the base DN 2282 LDAPv2.SCOPE_ONE Search only entries under the base 2283 DN 2285 LDAPv2.SCOPE_SUB Search the base DN and all entries 2286 within its subtree 2288 filter Search filter specifying the search criteria, as 2290 JAVA LDAP API September 1997 2292 defined in [3]. 2294 attrs Names of attributes to retrieve. 2296 attrsOnly If true, returns the names but not the values of the 2297 attributes found. If false, returns the names and 2298 values for attributes found 2300 cons Constraints specific to the search. 2302 5.20.12. setOption 2304 public void setOption(int option, 2305 Object value) 2306 throws LDAPException 2308 Sets the value of the specified option for this LDAPConnection 2309 object. 2311 See LDAPConnection.setOption for an implementation. 2313 5.21. public interface LDAPv3 extends LDAPv2 2315 LDAPv3 extends LDAPv2 by adding support for features of version 3 of the 2316 LDAP protocol. LDAPConnection implements at least LDAPv2, and may also 2317 implement LDAPv3. Applications can test for support of these protocol 2318 levels in a given package with the instanceof operator. 2320 5.21.1. Preferred Language 2322 A preferred language, specified as in [14], can be set using setOption. 2323 A Preferred Language Server Control is constructed and sent to the 2324 server with all operations. If the server supports the control, results 2325 returned on search() or read() will be filtered using the control, as 2326 per [15], e.g. 2328 ld.setOption( LDAPv3.PREFERRED_LANGUAGE, "lang-en" ); 2330 5.21.2. authenticate 2332 public void authenticate(int version, 2333 String dn, 2334 String passwd) 2335 throws LDAPException 2337 JAVA LDAP API September 1997 2339 Authenticates to the LDAP server (that the object is currently con- 2340 nected to) using the specified name and password, with the specified 2341 LDAP protocol version. If the server does not support the requested 2342 protocol version, an exception is thrown. If the object has been 2343 disconnected from an LDAP server, this method attempts to reconnect 2344 to the server. If the object had already authenticated, the old 2345 authentication is discarded. 2347 Parameters are: 2349 version LDAP protocol version requested: currently 2 or 3. 2351 dn If non-null and non-empty, specifies that the connec- 2352 tion and all operations through it should be authen- 2353 ticated with dn as the distinguished name. 2355 passwd If non-null and non-empty, specifies that the connec- 2356 tion and all operations through it should be authen- 2357 ticated with dn as the distinguished name and passwd 2358 as password. 2360 5.21.3. authenticate 2362 public void authenticate(String dn, 2363 byte[] credentials, 2364 String[] mechanisms, 2365 Properties props, 2366 SaslAuthenticationCallback authCb) 2367 throws LDAPException 2369 Authenticates to the LDAP server using SASL authentication mechan- 2370 isms. Mechanisms will be tried in the order provided. If a mechanism 2371 requires additional information (e.g. credentials) to procede, and 2372 authCb is not null, authCb's request() method will be called. An 2373 LDAPException is thrown if authentication fails for all specified 2374 mechanisms. 2376 Parameters are: 2378 dn Distinguished name to authenticate as 2380 credentials Initial credentials to use on first authentication 2381 request. The contents are specific to a SASL mechan- 2382 ism. 2384 props Properties to be used for authentication. Some are 2385 only meaningful to a subset of all SASL mechanisms. 2387 JAVA LDAP API September 1997 2389 The following is a partial list of properties and 2390 sample values: 2392 security.userid "default" 2394 security.policy.encryption "true" 2396 security.policy.sign_without_encryption "false" 2398 security.policy.no_encryption "false" 2400 security.policy.encryption.minimum "40" 2402 security.policy.encryption.maximum "128" 2404 security.policy.server_authentication "true" 2406 security.server.fqdn "safe.mcom.com" 2408 security.maxbuffer "4096" 2410 security.ip.local "192.68.1.10" 2412 security.ip.remote "192.68.1.50" 2414 authCb An object implementing the SaslAuthenticationCallback 2415 interface, capable of returning additional information 2416 to a SASL mechanism driver if necessary. This may or may 2417 not involve interactively prompting the user for this 2418 information. The parameter may be null, indicating that 2419 the application will not provide additional information. 2421 5.21.4. extendedOperation 2423 public LDAPExtendedOperation extendedOperation( 2424 LDAPExtendedOperation op ) 2425 throws LDAPException 2427 Provides a means to access extended, non-mandatory operations offered 2428 by a particular LDAP version 3 compliant server. 2430 Returns an operation-specific object, containing an ID and an Octet 2431 String or BER-encoded value(s). 2433 Parameters are: 2435 JAVA LDAP API September 1997 2437 op Object which contains an identifier of the extended 2438 operation, which should be one recognized by the par- 2439 ticular server this client is connected to, and an 2440 operation-specific sequence of Octet String or BER- 2441 encoded value(s). 2443 5.21.5. getResponseControls 2445 public LDAPControl[] getResponseControls() 2447 Returns the latest Server Controls returned by a Directory Server 2448 with a response to an LDAP request from the current thread, or null 2449 if the latest response contained no Server Controls. 2451 5.21.6. rename 2453 public void rename(String dn, 2454 String newRdn, 2455 String newParentdn, 2456 boolean deleteOldRdn) 2457 throws LDAPException 2459 Renames an existing entry in the directory, possibly repositioning it 2460 in the directory tree. 2462 Parameters are: 2464 dn Current distinguished name of the entry. 2466 newRdn New relative distinguished name for the entry. 2468 newParentdn Distinguished name of the existing entry which is to 2469 be the new parent of the entry. 2471 deleteOldRdn If true, the old name is not retained as an attribute 2472 value. 2474 5.22. public interface SaslAuthenticationCallback 2476 Note: this interface is not part of the LDAP classes. It is presented 2477 here to clarify use of SASL mechanisms in authentication using the LDAP 2478 classes. 2480 An application may implement this interface to allow a SASL mechanism 2481 driver to obtain additional information (e.g. credentials) as needed 2483 JAVA LDAP API September 1997 2485 during authentication. The implementation may or may not include 2486 interactively prompting a user. 2488 5.22.1. request 2490 public byte[] request(String prompt, 2491 String type) 2492 throws SaslException 2494 Parameters are: 2496 prompt A prompt that may be presented to a user as a guide 2497 to entering the requested information, or may be used 2498 as a key to forming the user interface for requesting 2499 the information, or may be ignored. 2501 type An identifier of type of information requested by the 2502 SASL mechanism driver, e.g. "password". 2504 5.23. Client and Server Controls 2506 LDAPv3 operations can be extended through the use of controls. Controls 2507 may be sent to a server or returned to the client with any LDAP message. 2508 These controls are referred to as server controls. The LDAP API also 2509 supports a client-side extension mechanism through the use of client 2510 controls (these controls affect the behavior of the LDAP API only and 2511 are never sent to a server). A common class is used to represent both 2512 types of controls - LDAPControl. 2514 Controls are set and retrieved in LDAPConnection with the setOption and 2515 getOption methods, using the keys LDAPv3.SERVERCONTROLS and 2516 LDAPv3.CLIENTCONTROLS. Either a single LDAPControl or an array may be 2517 passed, e.g. 2519 LDAPControl control = new LDAPControl( type, critical, vals ); 2520 ld.setOption( LDAPv3.SERVERCONTROLS, control ); 2521 or 2522 LDAPControl[] controls = new LDAPControl[2]; 2523 controls[0] = new LDAPControl( type0, critical0, vals0 ); 2524 controls[1] = new LDAPControl( type1, critical1, vals1 ); 2525 ld.setOption( LDAPv3.SERVERCONTROLS, controls ); 2527 Server controls returned to a client as part of the response to an 2528 operation can be obtained with LDAPv3.getResponseControls(). 2530 Support for specific controls is defined in a package "controls" subor- 2531 dinate to the main LDAP package. 2533 JAVA LDAP API September 1997 2535 6. Security Considerations 2537 LDAP supports security through protocol-level authentication, using 2538 clear-text passwords or other more secure mechanisms. It also supports 2539 running over TLS, which provides strong security at the transport layer. 2540 This draft does not cover TLS implementations, although it identifies a 2541 mechanism for supplying one, through the LDAPSocketFactory interface. An 2542 interface is defined for using protocol-independent SASL mechanism 2543 drivers for authentication. 2545 7. Acknowledgements 2547 The proposed API builds on earlier work done in collaboration with Tho- 2548 mas Kwan and Stephan Gudmundson, then of of NCware Technologies Corp. 2550 8. Bibliography 2552 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 2553 X.520. 2555 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 2556 Access Protocol: Standard and Pilot Attribute Definitions", Inter- 2557 net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996 2559 [3] T. Howes, "A String Representation of LDAP Search Filters," RFC 2560 1960, June 1996. 2562 [4] S. Kille, "A String Representation of Distinguished Names," RFC 2563 1779, March 1995. 2565 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 2566 ing," RFC 1781, March 1995. 2568 [7] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 2569 (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt, March 2570 1997. 2572 [8] T. Howes, M. Smith, "An LDAP URL Format", RFC 1959, June 1996. 2574 [9] T. Howes, M. Smith, "The LDAP Application Program Interface", RFC 2575 1823, August 1995. 2577 [10] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource Loca- 2578 tors (URL)", RFC 1738, December 1994. 2580 [11] W. Yeong, T. Howes, S. Kille, "Lightweight Directory Access Proto- 2581 col", RFC 1777, March 1995. 2583 JAVA LDAP API September 1997 2585 [12] R. Weltman, "The Java LDAP Application Program Interface", Internet 2586 Draft draft-weltman-java-ldap-01.txt, April 1997. 2588 [13] R. Weltman, T. Howes, M. Smith, "The Java LDAP Application Program 2589 Interface", Internet Draft draft-ietf-asid-ldap-java-api-00.txt, 2590 July 1997. 2592 [14] H. Alvestrans, "Tags for the Identification of Languages", Request 2593 for Comments 1766, March 1995. 2595 [15] M. Wahl, T. Howes, "Use of Language Codes in LDAPv3", Internet 2596 Draft draft-ietf-asid-ldapv3-lang-02.txt, June 1997. 2598 9. Authors' Addresses 2600 Rob Weltman 2601 Netscape Communications Corp. 2602 501 E. Middlefield Rd. 2603 Mountain View, CA 94043 2604 USA 2605 +1 650 937-3301 2606 rweltman@netscape.com 2608 Tim Howes 2609 Netscape Communications Corp. 2610 501 E. Middlefield Rd. 2611 Mountain View, CA 94043 2612 USA 2613 +1 650 937-3419 2614 howes@netscape.com 2616 Mark Smith 2617 Netscape Communications Corp. 2618 501 E. Middlefield Rd. 2619 Mountain View, CA 94043 2620 USA 2621 +1 650 937-3477 2622 mcs@netscape.com 2624 JAVA LDAP API September 1997 2626 10. Appendix A - Sample java LDAP programs 2628 import netscape.ldap.*; 2629 import java.util.*; 2631 public class SearchJensen { 2632 public static void main( String[] args ) 2633 { 2634 try { 2635 LDAPConnection ld = new LDAPConnection(); 2636 /* Connect to server */ 2637 String MY_HOST = "localhost"; 2638 int MY_PORT = 389; 2639 ld.connect( MY_HOST, MY_PORT ); 2641 /* authenticate to the directory as nobody */ 2642 /* This is not really necessary if explicit authentication 2643 is not desired, because there is already anonymous 2644 authentication at connect time */ 2645 ld.authenticate( "", "" ); 2647 /* search for all entries with surname of Jensen */ 2648 String MY_FILTER = "sn=Jensen"; 2649 String MY_SEARCHBASE = "o=Ace Industry, c=US"; 2651 LDAPSearchConstraints cons = ld.getSearchConstraints(); 2652 /* Setting the batchSize to one will cause the result 2653 enumeration below to block on one result at a time, 2654 allowing us to update a list or do other things as 2655 results come in. */ 2656 /* We could set it to 0 if we just wanted to get all 2657 results and were willing to block until then */ 2658 cons.setBatchSize( 1 ); 2659 LDAPSearchResults res = ld.search( MY_SEARCHBASE, 2660 LDAPConnection.SCOPE_ONE, 2661 MY_FILTER, 2662 null, 2663 false, 2664 cons ); 2666 /* Loop on results until finished */ 2667 while ( res.hasMoreElements() ) { 2669 /* Next directory entry */ 2670 LDAPEntry findEntry = (LDAPEntry)res.nextElement(); 2671 System.out.println( findEntry.getDN() ); 2673 /* Get the attributes of the entry */ 2675 JAVA LDAP API September 1997 2677 LDAPAttributeSet findAttrs = findEntry.getAttributeSet(); 2678 Enumeration enumAttrs = findAttrs.getAttributes(); 2679 System.out.println( "Attributes: " ); 2680 /* Loop on attributes */ 2681 while ( enumAttrs.hasMoreElements() ) { 2682 LDAPAttribute anAttr = 2683 (LDAPAttribute)enumAttrs.nextElement(); 2684 String attrName = anAttr.getName(); 2685 System.out.println( "" + attrName ); 2686 /* Loop on values for this attribute */ 2687 Enumeration enumVals = anAttr.getStringValues(); 2688 while ( enumVals.hasMoreElements() ) { 2689 String aVal = ( String )enumVals.nextElement(); 2690 System.out.println( "" + aVal ); 2691 } 2692 } 2693 } 2694 } 2695 catch( LDAPException e ) { 2696 System.out.println( "Error: " + e.toString() ); 2697 } 2698 /* Done, so disconnect */ 2699 if ( ld.isConnected() ) 2700 ld.disconnect(); 2701 } 2702 } 2704 JAVA LDAP API September 1997 2706 import netscape.ldap.*; 2707 import java.util.*; 2709 public class ModifyEmail { 2710 public static void main( String[] args ) 2711 { 2712 try { 2713 LDAPConnection ld = new LDAPConnection(); 2714 /* Connect to server */ 2715 String MY_HOST = "localhost"; 2716 int MY_PORT = 389; 2717 ld.connect( MY_HOST, MY_PORT ); 2719 /* authenticate to the directory as Bab Jensen */ 2720 String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US"; 2721 String MY_PASSWORD = "MysteryLady"; 2722 ld.authenticate( MY_NAME, MY_PASSWORD ); 2724 /* Prepare to change my email address */ 2725 LDAPAttribute attrEmail = 2726 new LDAPAttribute( "mail", "babs@ace.com" ); 2727 LDAPModification mod = 2728 new LDAPModification( LDAPModification.REPLACE, 2729 attrEmail ); 2731 /* Now modify the entry in the directory */ 2732 ld.modify( MY_NAME, mod ); 2733 System.out.println( "Entry modified" ); 2735 } 2736 catch( LDAPException e ) { 2737 System.out.println( "Error: " + e.toString() ); 2738 } 2739 /* Done, so disconnect */ 2740 if ( ld.isConnected() ) 2741 ld.disconnect(); 2742 } 2743 } 2745 JAVA LDAP API September 1997 2747 11. Appendix B - Changes from draft-ietf-asid-ldap-java-api-00.txt 2749 11.1. LDAPConnection 2751 The method setProperty() throws an LDAPException if the specified pro- 2752 perty is not supported. 2754 11.2. Controls 2756 A section was added with support for currently defined LDAP controls. 2758 11.3. LDAPException 2760 Constructors LDAPException(String) and LDAPException(String,int,String) 2761 were removed, and the constructor LDAPException(String,int) was added. 2762 The description stating that the resultCode is no longer valid was 2763 removed. 2765 11.4. LDAPSearchResults 2767 The method next() throws an LDAPReferralException if automatic referral 2768 following is not enabled. 2770 The getBaseAttribute() method was removed. 2772 The getAttribute(attrName) method was redefined to return only an exact 2773 match, and a new method getAttribute(attrName, lang) was added to pro- 2774 vide language-sensitive best-match functionality. Neither method throws 2775 an exception. 2777 11.5. LDAPSecurityException 2779 The class was removed. 2781 11.6. LDAPSortKey 2783 The class was added, to support server-side sorting. 2785 11.7. LDAPv3 2787 The PREFERRED_LANGUAGE option was added to setOption(). 2789 11.8. Examples 2791 The disconnect() was moved to after the exception catcher. An example 2792 of using paged sort controls was added. 2794 JAVA LDAP API September 1997 2796 12. Appendix C - Changes from draft-weltman-java-ldap-00.txt 2798 12.1. LDAPv3 2800 This interface is new. It adds support for features of LDAP protocol 2801 version 3. 2803 12.2. SSL -> TLS 2805 References to the Secure Socket Layer (SSL) have been replaced with 2806 references to Transport Layer Security (TLS). 2808 12.3. LDAPAttributeSet 2810 Methods getAttribute(String name) and getBaseAttribute(String name) were 2811 added. 2813 12.4. LDAPCompareAttrNames 2815 Constructors were added to allow specifying sorting in descending, and 2816 not just ascending, order. 2818 12.5. LDAPCompareAttrNames 2820 Constructors were added to allow specifying sorting in descending, and 2821 not just ascending, order. 2823 12.6. LDAPControl 2825 This is a new class to support the LDAPv3 protocol extension, where 2826 Server or Client Controls may be specified for LDAP operations. 2828 12.7. LDAPEntry 2830 Methods getAttribute(String name) and getBaseAttribute(String name) were 2831 added. 2833 12.8. LDAPException 2835 The method getMatchedDN was added. 2837 12.9. LDAPExtendedOperation 2839 New class to pass extended operations back and forth to/from the server, 2840 for LDAPv3. 2842 JAVA LDAP API September 1997 2844 12.10. LDAPv2 2846 For connect(), the "host" parameter may be a space-delimited list of 2847 hosts to attempt to connect to. Each one may have a colon and a port 2848 number attached. 2850 12.11. Dereferencing aliases 2852 LDAPConnection.setOption(), the LDAPSearchConstraints constructor, 2853 LDAPSearchConstraints.getDereference(), and 2854 LDAPSearchConstraints.setDereference() were changed so that the option 2855 specifying how to dereference aliases is now an integer instead of a 2856 boolean, and the legal values are declared. 2858 12.12. Default referral hop limit 2860 The default referral hop limit in LDAPConnection.setOption() was changed 2861 from 5 to 10. 2863 12.13. Examples 2865 An example of how to modify an existing Directory entry was added to 2866 appendix A. 2868 JAVA LDAP API September 1997 2870 13. Appendix D - Outstanding issues 2872 13.1. Support for SASL authentication 2874 The framework suggested in the LDAPv3 interface for SASL authentication 2875 is tentative. It will need to be extended to and integrated into the 2876 automatic referral-processing architecture, so that an LDAPRebindProc 2877 can initiate new authentication procedures with servers that are 2878 referred to by a search. The current specification only allows for sim- 2879 ple authentication on automatic referral following. 2881 If referrals are handled explicitly rather than automatically, by catch- 2882 ing LDAPReferralException, the caller may use the LDAPv3 SASL framework. 2884 1. Introduction...................................................1 2885 2. Overview of the LDAP model.....................................2 2886 3. Overview of the LDAP classes...................................3 2887 3.1. Interfaces..................................................3 2888 3.2. Classes.....................................................4 2889 3.3. Exceptions..................................................5 2890 4. Overview of LDAP API use.......................................6 2891 5. The java LDAP classes..........................................6 2892 5.1. LDAPAttribute................................................6 2893 5.1.1. Constructors.............................................6 2894 5.1.2. addValue.................................................7 2895 5.1.3. getByteValues............................................8 2896 5.1.4. getStringValues..........................................8 2897 5.1.5. getName..................................................8 2898 5.1.6. removeValue..............................................8 2899 5.1.7. size.....................................................8 2900 5.2. LDAPAttributeSet.............................................9 2901 5.2.1. Constructors.............................................9 2902 5.2.2. add......................................................9 2903 5.2.3. elementAt................................................9 2904 5.2.4. getAttribute.............................................9 2905 5.2.5. getAttributes............................................10 2906 5.2.6. remove...................................................11 2907 5.2.7. removeElementAt..........................................11 2908 5.2.8. size.....................................................11 2909 5.3. LDAPCompareAttrNames.........................................11 2910 5.3.1. Constructors.............................................11 2911 5.3.2. isGreater................................................12 2912 5.4. LDAPConnection...............................................13 2913 5.4.1. Constructors.............................................13 2914 5.4.2. clone....................................................13 2915 5.4.3. getAuthenticationDN......................................14 2916 5.4.4. getAuthenticationPassword................................14 2917 5.4.5. getHost..................................................14 2918 5.4.6. getPort..................................................14 2919 5.4.7. getProperty..............................................14 2920 5.4.8. getSearchConstraints.....................................15 2921 5.4.9. getSocketFactory.........................................15 2922 5.4.10. isAuthenticated..........................................15 2923 5.4.11. isConnected..............................................16 2924 5.4.12. read.....................................................16 2925 5.4.13. search...................................................16 2926 5.4.14. setOption................................................17 2927 5.4.15. setProperty..............................................20 2928 5.4.16. setSocketFactory.........................................21 2929 5.5. LDAPControl..................................................21 2930 5.5.1. Constructors.............................................22 2931 5.5.2. getID....................................................22 2932 5.5.3. isCritical...............................................22 2933 5.5.4. getValue.................................................22 2934 5.6. LDAPDN.......................................................22 2935 5.6.1. explodeDN................................................23 2937 5.6.2. explodeRDN...............................................23 2938 5.7. LDAPEntry....................................................23 2939 5.7.1. Constructors.............................................23 2940 5.7.2. getAttribute.............................................24 2941 5.7.3. getAttributeSet..........................................25 2942 5.7.4. getDN....................................................26 2943 5.8. LDAPExtendedOperation........................................26 2944 5.8.1. Constructors.............................................26 2945 5.8.2. getID....................................................26 2946 5.8.3. getValue.................................................26 2947 5.9. LDAPEntryComparator..........................................27 2948 5.9.1. isGreater................................................27 2949 5.10. LDAPException................................................27 2950 5.10.1. Constructors.............................................27 2951 5.10.2. getLDAPErrorMessage......................................28 2952 5.10.3. getLDAPResultCode........................................28 2953 5.10.4. getMatchedDN.............................................28 2954 5.10.5. Error codes..............................................28 2955 5.11. LDAPModification.............................................30 2956 5.11.1. Constructors.............................................30 2957 5.11.2. getAttribute.............................................30 2958 5.11.3. getOp....................................................30 2959 5.12. LDAPModificationSet..........................................30 2960 5.12.1. Constructors.............................................31 2961 5.12.2. add......................................................31 2962 5.12.3. elementAt................................................31 2963 5.12.4. remove...................................................31 2964 5.12.5. removeElementAt..........................................32 2965 5.12.6. size.....................................................32 2966 5.13. LDAPRebindAuth...............................................32 2967 5.13.1. Constructors.............................................32 2968 5.13.2. getDN....................................................32 2969 5.13.3. getPassword..............................................32 2970 5.14. LDAPReferralException........................................33 2971 5.14.1. Constructors.............................................33 2972 5.14.2. getURLs..................................................33 2973 5.15. LDAPSearchConstraints........................................33 2974 5.15.1. Constructors.............................................34 2975 5.15.2. getBatchSize.............................................35 2976 5.15.3. getDereference...........................................35 2977 5.15.4. getHopLimit..............................................35 2978 5.15.5. getMaxResults............................................35 2979 5.15.6. getRebindProc............................................35 2980 5.15.7. getReferrals.............................................36 2981 5.15.8. getTimeLimit.............................................36 2982 5.15.9. setBatchSize.............................................36 2983 5.15.10. setDereference...........................................36 2984 5.15.11. setHopLimit..............................................37 2985 5.15.12. setMaxResults............................................37 2986 5.15.13. setRebindProc............................................37 2987 5.15.14. setReferrals.............................................37 2988 5.15.15. setTimeLimit.............................................38 2990 5.16. LDAPSearchResults............................................38 2991 5.16.1. hasMoreElements..........................................38 2992 5.16.2. next.....................................................38 2993 5.16.3. nextElement..............................................39 2994 5.16.4. sort.....................................................39 2995 5.17. LDAPSocketFactory............................................39 2996 5.17.1. makeSocket...............................................39 2997 5.18. LDAPSortKey..................................................40 2998 5.18.1. Constructors.............................................40 2999 5.18.2. getKey...................................................41 3000 5.18.3. getReverse...............................................41 3001 5.18.4. getMatchRule.............................................41 3002 5.19. LDAPUrl......................................................41 3003 5.19.1. Constructors.............................................41 3004 5.19.2. decode...................................................42 3005 5.19.3. encode...................................................43 3006 5.19.4. getAttributes............................................43 3007 5.19.5. getAttributes............................................43 3008 5.19.6. getDN....................................................43 3009 5.19.7. getFilter................................................43 3010 5.19.8. getHost..................................................44 3011 5.19.9. getPort..................................................44 3012 5.19.10. getUrl...................................................44 3013 5.20. LDAPv2.......................................................44 3014 5.20.1. add......................................................44 3015 5.20.2. authenticate.............................................44 3016 5.20.3. compare..................................................45 3017 5.20.4. connect..................................................45 3018 5.20.5. delete...................................................46 3019 5.20.6. disconnect...............................................47 3020 5.20.7. getOption................................................47 3021 5.20.8. modify...................................................47 3022 5.20.9. read.....................................................48 3023 5.20.10. rename...................................................48 3024 5.20.11. search...................................................49 3025 5.20.12. setOption................................................50 3026 5.21. LDAPv3.......................................................50 3027 5.21.1. Preferred Language.......................................50 3028 5.21.2. authenticate.............................................50 3029 5.21.3. authenticate.............................................51 3030 5.21.4. extendedOperation........................................52 3031 5.21.5. getResponseControls......................................53 3032 5.21.6. rename...................................................53 3033 5.22. SaslAuthenticationCallback...................................53 3034 5.22.1. request..................................................54 3035 5.23. Client and Server Controls..................................54 3036 6. Security Considerations........................................55 3037 7. Acknowledgements...............................................55 3038 8. Bibliography...................................................55 3039 9. Authors' Addresses.............................................56 3040 10. Appendix A - Sample java LDAP programs.........................57 3041 11. Appendix B - Changes from draft-ietf-asid-ldap-java-api-00.txt.60 3043 11.1. LDAPConnection..............................................60 3044 11.2. Controls....................................................60 3045 11.3. LDAPException...............................................60 3046 11.4. LDAPSearchResults...........................................60 3047 11.5. LDAPSecurityException.......................................60 3048 11.6. LDAPSortKey.................................................60 3049 11.7. LDAPv3......................................................60 3050 11.8. Examples....................................................60 3051 12. Appendix C - Changes from draft-weltman-java-ldap-00.txt.......61 3052 12.1. LDAPv3......................................................61 3053 12.2. SSL -> TLS..................................................61 3054 12.3. LDAPAttributeSet............................................61 3055 12.4. LDAPCompareAttrNames........................................61 3056 12.5. LDAPCompareAttrNames........................................61 3057 12.6. LDAPControl.................................................61 3058 12.7. LDAPEntry...................................................61 3059 12.8. LDAPException...............................................61 3060 12.9. LDAPExtendedOperation.......................................61 3061 12.10. LDAPv2......................................................62 3062 12.11. Dereferencing aliases.......................................62 3063 12.12. Default referral hop limit..................................62 3064 12.13. Examples....................................................62 3065 13. Appendix D - Outstanding issues................................63 3066 13.1. Support for SASL authentication.............................63