home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldap-java-api-01.txt < prev    next >
Text File  |  1997-09-30  |  119KB  |  4,012 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                         Rob Weltman
  8. INTERNET-DRAFT                              Netscape Communications Corp.
  9.                                                                 Tim Howes
  10.                                             Netscape Communications Corp.
  11.                                                                Mark Smith
  12.                                             Netscape Communications Corp.
  13.                                                        September 26, 1997
  14.  
  15.  
  16.               The Java LDAP Application Program Interface
  17.                   draft-ietf-asid-ldap-java-api-01.txt
  18.  
  19.  
  20. Status of this Memo
  21.  
  22. This document is an Internet-Draft.  Internet-Drafts are working docu-
  23. ments of the Internet Engineering Task Force (IETF), its areas, and its
  24. working groups.  Note that other groups may also distribute working
  25. documents as Internet-Drafts.
  26.  
  27. Internet-Drafts are draft documents valid for a maximum of six months
  28. and may be updated, replaced, or obsoleted by other documents at any
  29. time.  It is inappropriate to use Internet-Drafts as reference material
  30. or to cite them other than as ``work in progress.''
  31.  
  32. To learn the current status of any Internet-Draft, please check the
  33. ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
  34. Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
  35. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  36.  
  37. Abstract
  38.  
  39. This document defines a java language application program interface to
  40. the lightweight directory access protocol (LDAP), in the form of a class
  41. library. It complements but does not replace RFC 1823 ([9]), which
  42. describes a C language application program interface. It updates and
  43. replaces draft-ietf-asid-ldap-java-api-00.txt [13], in adding clarifica-
  44. tion on behavior under various circumstances, and in revising support
  45. for language-sensitive attribute parsing. Other additions and correc-
  46. tions are listed in the appendix.
  47.  
  48.  
  49. 1.  Introduction
  50.  
  51. The LDAP class library is designed to provide powerful, yet simple,
  52. access to a LDAP directory services.  It defines a synchronous interface
  53. to LDAP, with support for partial results on searching, to suit a wide
  54. variety of applications. This document gives a brief overview of the
  55.  
  56.  
  57.  
  58. Expires 3/98                                                    [Page 1]
  59.  
  60.  
  61.  
  62.  
  63.  
  64. JAVA LDAP API                                             September 1997
  65.  
  66.  
  67. LDAP model, then an overview of the constituents of the class library.
  68. The public class methods are described in detail, followed by an appen-
  69. dix that provides some example code demonstrating the use of the
  70. classes, and an appendix listing changes from earlier drafts.
  71.  
  72. 2.  Overview of the LDAP model
  73.  
  74. LDAP is the lightweight directory access protocol, described in [2] and
  75. [7]. It defines a lightweight access mechanism in which clients send
  76. requests to and receive responses from LDAP servers.
  77.  
  78. The LDAP information model comes from X.500 [1] and is based on the
  79. entry, which contains information about some object (e.g., a person).
  80. Entries are composed of attributes, which have a type and one or more
  81. values. Each attribute has a syntax that determines what kinds of values
  82. are allowed in the attribute (e.g., ASCII characters, a jpeg photograph,
  83. etc.) and how those values behave during directory operations (e.g., is
  84. case significant during comparisons).
  85.  
  86. Entries may be organized in a tree structure, usually based on politi-
  87. cal, geographical, and organizational boundaries. Other structures are
  88. possible, including a flat namespace. Each entry is uniquely named rela-
  89. tive to its sibling entries by its relative distinguished name (RDN)
  90. consisting of one or more distinguished attribute values from the entry.
  91. At most one value from each attribute may be used in the RDN. For exam-
  92. ple, the entry for the person Babs Jensen might be named with the "Bar-
  93. bara Jensen" value from the commonName attribute.
  94.  
  95. A globally unique name for an entry, called a distinguished name or DN,
  96. is constructed by concatenating the sequence of RDNs from the entry up
  97. to the root of the tree. For example, if Babs worked for the University
  98. of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
  99. o=University of Michigan, c=US". The DN format used by LDAP is defined
  100. in [4].
  101.  
  102. Operations are provided to authenticate, search for and retrieve infor-
  103. mation, modify information, and add and delete entries from the tree.
  104.  
  105. An LDAP server may return referrals if it cannot completely service a
  106. request (for example if the request specifies a directory base outside
  107. of the tree managed by the server). The LDAP class library offers the
  108. programmer two options: the programmer can catch these referrals as
  109. exceptions and explicitly issue new requests to the referred-to servers,
  110. or the programmer can let the library automatically follow the refer-
  111. rals.  In the latter case, the programmer may also provide a reauthenti-
  112. cation object, allowing automatic referrals to proceed with appropriate
  113. credentials (as opposed to anonymous authentication) for each referred-
  114. to server.
  115.  
  116.  
  117.  
  118. Expires 3/98                                                    [Page 2]
  119.  
  120.  
  121.  
  122.  
  123.  
  124. JAVA LDAP API                                             September 1997
  125.  
  126.  
  127. Before the client encodes and sends a string value to a server, the
  128. string values are converted from the java 16-bit Unicode format to UTF-8
  129. format. Then, when the values are received by the server, the values are
  130. converted back to 16-bit Unicodeformat.  The integrity of double-byte
  131. and other non-ASCII character sets is fully preserved.
  132.  
  133. The next sections give an overview of how the class library is used and
  134. detailed descriptions of the LDAP class methods that implement all of
  135. these functions.
  136.  
  137. 3.  Overview of the LDAP classes
  138.  
  139. The central LDAP class is LDAPConnection. It provides methods to estab-
  140. lish an authenticated or anonymous connection to an LDAP server, as well
  141. as methods to search for, modify, compare, and delete entries in the
  142. directory.
  143.  
  144. The LDAPConnection class also provides fields for storing settings that
  145. are specific to the LDAP session (such as limits on the number of
  146. results returned or timeout limits). An LDAPConnection object can be
  147. cloned, allowing objects to share a single network connection but use
  148. different settings (using LDAPConnection.setOption()).
  149.  
  150. To support extensions of the LDAP protocol LDAPConnection and to add the
  151. capability to determine the LDAP protocol level supported by an LDAPCon-
  152. nection object, LDAPConnection implements a protocol interface, which is
  153. currently LDAPv3.
  154.  
  155. A search conducted by an LDAPConnection object returns results in an
  156. LDAPSearchResults object, which can be enumerated to access the entries
  157. found. Each entry (represented by an LDAPEntry object) provides access
  158. to the attributes (represented by LDAPAttribute objects) returned for
  159. that entry. Each attribute can produce the values found as byte arrays
  160. or as Strings.
  161.  
  162.  
  163. 3.1.  Interfaces
  164.  
  165.  
  166. LDAPEntryComparator   An interface to support arbitrary sorting algo-
  167.                       rithms for entries returned by a search operation.
  168.                       The basic java LDAP classes include one implemen-
  169.                       tation: LDAPCompareAttrNames, to sort in ascending
  170.                       order based on one or more attribute names.
  171.  
  172.  
  173. LDAPRebind            A programmer desiring reauthentication on automat-
  174.                       ically following referrals must implement this
  175.  
  176.  
  177.  
  178. Expires 3/98                                                    [Page 3]
  179.  
  180.  
  181.  
  182.  
  183.  
  184. JAVA LDAP API                                             September 1997
  185.  
  186.  
  187.                       interface. Without it, automatically followed
  188.                       referrals will use anonymous authentication.
  189.                       Referrals of any type other to an LDAP server
  190.                       (i.e. a referral URL other than ldap://something)
  191.                       are ignored on automatic referral following.
  192.  
  193.  
  194. LDAPSocketFactory     Programmers needing to provide or use specialized
  195.                       socket connections, including Transport Layer
  196.                       Security (TLS) based ones, can provide an object
  197.                       constructor to implement them using this inter-
  198.                       face.
  199.  
  200.  
  201. LDAPv2                This interface defines the functionality of the
  202.                       LDAP version 2 protocol. It is implemented by
  203.                       LDAPConnection.
  204.  
  205.  
  206. LDAPv3                This interface extends LDAPv2, adding the func-
  207.                       tionality of the LDAP version 3 protocol. It is
  208.                       implemented by LDAPConnection.
  209.  
  210.  
  211. 3.2.  Classes
  212.  
  213.  
  214. LDAPAttribute         Represents the name and values of one attribute of
  215.                       a directory entry.
  216.  
  217.  
  218. LDAPAttributeSet      A collection of LDAPAttributes.
  219.  
  220.  
  221. LDAPCompareAttrNames  An implementation of LDAPEntryComparator, to sup-
  222.                       port sorting of search results by one or more
  223.                       attributes.
  224.  
  225.  
  226. LDAPConnection        Implements LDAPv3 and is the central point for
  227.                       interactions with a directory.
  228.  
  229.  
  230. LDAPControl           Sets additional parameters or constraints for an
  231.                       LDAP operation, either on the server or on the
  232.                       client.
  233.  
  234.  
  235.  
  236.  
  237.  
  238. Expires 3/98                                                    [Page 4]
  239.  
  240.  
  241.  
  242.  
  243.  
  244. JAVA LDAP API                                             September 1997
  245.  
  246.  
  247. LDAPDN                A utility class to facilitate composition and
  248.                       decomposition of distinguished names (DNs).
  249.  
  250.  
  251. LDAPEntry             Represents a single entry in a directory.
  252.  
  253.  
  254. LDAPExtendedOperation Encapsulates the ID and data associated with the
  255.                       sending or receiving of an extended operation (an
  256.                       LDAPv3 feature).
  257.  
  258.  
  259. LDAPModification      A single add/delete/replace operation to an
  260.                       LDAPAttribute.
  261.  
  262.  
  263. LDAPModificationSet   A collection of LDAPModifications
  264.  
  265.  
  266. LDAPRebindAuth        An implementation of LDAPRebind must be able to
  267.                       provide an LDAPRebindAuth at the time of a refer-
  268.                       ral. The class encapsulates reauthentication
  269.                       credentials.
  270.  
  271.  
  272. LDAPSearchConstraints Defines the options controlling search operations.
  273.  
  274.  
  275. LDAPSearchResults     The enumerable results of a search operation.
  276.  
  277.  
  278. LDAPSortKey           Specifies how search results are to be sorted.
  279.  
  280.  
  281. LDAPUrl               Encapsulates parameters of an LDAP Url query, as
  282.                       defined in [8].
  283.  
  284.  
  285. 3.3.  Exceptions
  286.  
  287.  
  288. LDAPException         General exception, which includes an error message
  289.                       and an LDAP error code.
  290.  
  291.  
  292. LDAPReferralException Derived from LDAPException and contains a list of
  293.                       LDAPUrls corresponding to referrals received on an
  294.                       LDAP operation.
  295.  
  296.  
  297.  
  298. Expires 3/98                                                    [Page 5]
  299.  
  300.  
  301.  
  302.  
  303.  
  304. JAVA LDAP API                                             September 1997
  305.  
  306.  
  307. 4.  Overview of LDAP API use
  308.  
  309. An application generally uses the LDAP API in four steps.
  310.  
  311. -    Construct an LDAPConnection.  Initialize an LDAP session with a
  312.      directory server. The LDAPConnection.connect() call establishes a
  313.      handle to the session, allowing multiple sessions to be open at
  314.      once, on different instances of LDAPConnection.
  315.  
  316. -    Authenticate to the LDAP server with LDAPConnection.authenticate().
  317.  
  318. -    Perform some LDAP operations and obtain some results.
  319.      LDAPConnection.search() returns an LDAPSearchResults, which can be
  320.      enumerated to access all entries found. LDAPConnection.read()
  321.      returns a single entry.
  322.  
  323. -    Close the connection. The LDAPConnection.disconnect() call closes
  324.      the connection.
  325.  
  326. All operations are synchronous - they do not return until the operation
  327. has completed. In the java environment, it is appropriate to create a
  328. thread for the operation rather than providing parallel synchronous and
  329. asynchronous operations, as is the case in the C language API described
  330. in [9]. To facilitate user feedback during searches, intermediate search
  331. results can be obtained before the entire search operation is completed
  332. by specifying the number of entries to return at a time.
  333.  
  334. Standard java Enumerations are used to parse search results. Errors
  335. result in the throwing of an LDAPException, with a specific error code
  336. and context-specific textual information available.
  337.  
  338. The following sections describe the LDAP classes in more detail.
  339.  
  340. 5.  The java LDAP classes
  341.  
  342.  
  343. 5.1.  public class LDAPAttribute
  344.  
  345. The LDAPAttribute class represents the name and values of an attribute.
  346. It is used to specify an attribute to be added to, deleted from, or
  347. modified in a Directory entry. It is also returned on a search of a
  348. Directory.
  349.  
  350.  
  351. 5.1.1.  Constructors
  352.  
  353.    public LDAPAttribute(String attrName)
  354.  
  355.  
  356.  
  357.  
  358. Expires 3/98                                                    [Page 6]
  359.  
  360.  
  361.  
  362.  
  363.  
  364. JAVA LDAP API                                             September 1997
  365.  
  366.  
  367.    Constructs an attribute with no values.
  368.  
  369.  
  370.    public LDAPAttribute(String attrName,
  371.                         byte attrBytes[])
  372.  
  373.    Constructs an attribute with a byte-formatted value.
  374.  
  375.  
  376.    public LDAPAttribute(String attrName,
  377.                         String attrString)
  378.  
  379.    Constructs an attribute that has a single string value.
  380.  
  381.  
  382.    public LDAPAttribute(String attrName,
  383.                         String attrStrings[])
  384.  
  385.    Constructs an attribute that has an array of string values.
  386.  
  387.    Parameters are:
  388.  
  389.    attrName        Name of the attribute.
  390.  
  391.    attrBytes       Value of the attribute as raw bytes.
  392.  
  393.    attrString      Value of the attribute as a String.
  394.  
  395.    attrStrings     Array of values as Strings.
  396.  
  397.    attrBytesArray  Array of values as raw byte arrays.
  398.  
  399.  
  400. 5.1.2.  addValue
  401.  
  402.    public synchronized void addValue(String attrString)
  403.  
  404.    Adds a string value to the attribute.
  405.  
  406.  
  407.    public synchronized void addValue(byte attrBytes[])
  408.  
  409.    Adds a byte[]-formatted value to the attribute.
  410.  
  411.    Parameters are:
  412.  
  413.    attrString      Value of the attribute as a String.
  414.  
  415.  
  416.  
  417.  
  418. Expires 3/98                                                    [Page 7]
  419.  
  420.  
  421.  
  422.  
  423.  
  424. JAVA LDAP API                                             September 1997
  425.  
  426.  
  427.    attrBytes       Value of the attribute as raw bytes.
  428.  
  429.  
  430. 5.1.3.  getByteValues
  431.  
  432.    public Enumeration getByteValues()
  433.  
  434.    Returns an enumerator for the values of the attribute in byte[] for-
  435.    mat.
  436.  
  437.  
  438. 5.1.4.  getStringValues
  439.  
  440.    public Enumeration getStringValues()
  441.  
  442.    Returns an enumerator for the string values of an attribute.
  443.  
  444.  
  445. 5.1.5.  getName
  446.  
  447.    public String getName()
  448.  
  449.    Returns the name of the attribute.
  450.  
  451.  
  452. 5.1.6.  removeValue
  453.  
  454.    public synchronized void removeValue(String attrString)
  455.  
  456.    Removes a string value from the attribute.
  457.  
  458.  
  459.    public synchronized void removeValue(byte attrValue[])
  460.  
  461.    Removes a byte[]-formatted value from the attribute.
  462.  
  463.    Parameters are:
  464.  
  465.    attrString      Value of the attribute as a String.
  466.  
  467.    attrBytes       Value of the attribute as raw bytes.
  468.  
  469.  
  470. 5.1.7.  size
  471.  
  472.    public int size()
  473.  
  474.    Returns the number of values of the attribute.
  475.  
  476.  
  477.  
  478. Expires 3/98                                                    [Page 8]
  479.  
  480.  
  481.  
  482.  
  483.  
  484. JAVA LDAP API                                             September 1997
  485.  
  486.  
  487. 5.2.  public class LDAPAttributeSet
  488.  
  489. An LDAPAttributeSet is a collection of LDAPAttributes, as returned in an
  490. entry on a search or read operation, or used to construct an entry to be
  491. added to a directory.
  492.  
  493.  
  494. 5.2.1.  Constructors
  495.  
  496.    public LDAPAttributeSet()
  497.  
  498.    Constructs a new set of attributes. This set is initially empty.
  499.  
  500.  
  501. 5.2.2.  add
  502.  
  503.    public synchronized void add(LDAPAttribute attr)
  504.  
  505.    Adds the specified attribute to this attribute set.
  506.  
  507.    Parameters are:
  508.  
  509.    attr            Attribute to add to this set.
  510.  
  511.  
  512. 5.2.3.  elementAt
  513.  
  514.    public LDAPAttribute elementAt(int index)
  515.                                throws ArrayIndexOutOfBoundsException
  516.  
  517.    Returns the attribute at the position specified by the index.  The
  518.    index is 0-based.
  519.  
  520.    Parameters are:
  521.  
  522.    index           Index of the attribute to get.
  523.  
  524.  
  525. 5.2.4.  getAttribute
  526.  
  527.    public LDAPAttribute[] getAttribute(String attrName)
  528.  
  529.    Returns the attribute matching the specified attrName. For example,
  530.    getAttribute("cn") returns only the "cn" attribute;
  531.    getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute.
  532.    In both cases, null is returned if there is no exact match to the
  533.    specified attrName.
  534.  
  535.  
  536.  
  537.  
  538. Expires 3/98                                                    [Page 9]
  539.  
  540.  
  541.  
  542.  
  543.  
  544. JAVA LDAP API                                             September 1997
  545.  
  546.  
  547.    public LDAPAttribute[] getAttribute(String attrName, String lang)
  548.  
  549.    Returns a single best-match attribute, or none if no match is avail-
  550.    able in the entry.
  551.  
  552.    LDAP version 3 allows adding a subtype specification to an attribute
  553.    name. "cn;lang-ja", for example, indicates a Japanese language sub-
  554.    type of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype of
  555.    "cn;lang-ja". This feature may be used to provide multiple localiza-
  556.    tions in the same Directory. For attributes which do not vary among
  557.    localizations, only the base attribute may be stored, whereas for
  558.    others there may be varying degrees of specialization.
  559.  
  560.    getAttribute(attrName,lang) returns the subtype that matches attrName
  561.    and that best matches lang. If there are subtypes other than "lang"
  562.    subtypes included in attrName, e.g. "cn;binary", only attributes with
  563.    all of those subtypes are returned. If lang is null or empty, the
  564.    method behaves as getAttribute(attrName). If there are no matching
  565.    attributes, null is returned.
  566.  
  567.    Example:
  568.       Assume the entry contains only the following attributes:
  569.          cn;lang-en
  570.          cn;lang-ja-JP-kanji
  571.          sn
  572.       getAttribute( "cn" ) returns null.
  573.       getAttribute( "sn" ) returns the "sn" attribute.
  574.       getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute.
  575.       getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute.
  576.       getAttribute( "cn", "lang-ja" ) returns null.
  577.       getAttribute( "sn", "lang-en" ) returns the "sn" attribute.
  578.  
  579.    Parameters are:
  580.  
  581.    attrName        The name of an attribute to retrieve, with or without
  582.                    subtype specification(s). "cn", "cn;phonetic", and
  583.                    "cn;binary" are valid attribute names.
  584.  
  585.    lang            A language specification as in [14], with optional
  586.                    subtypes appended using "-" as separator. "lang-en",
  587.                    "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are
  588.                    valid language specification.
  589.  
  590.  
  591. 5.2.5.  getAttributes
  592.  
  593.    public Enumeration getAttributes()
  594.  
  595.  
  596.  
  597.  
  598. Expires 3/98                                                   [Page 10]
  599.  
  600.  
  601.  
  602.  
  603.  
  604. JAVA LDAP API                                             September 1997
  605.  
  606.  
  607.    Returns an enumeration of the attributes in this attribute set.
  608.  
  609. 5.2.6.  remove
  610.  
  611.    public synchronized void remove(String name)
  612.  
  613.    Removes the specified attribute from the set. If the attribute is not
  614.    a member of the set, nothing happens.
  615.  
  616.    Parameters are:
  617.  
  618.    name            Name of the attribute to remove from this set. To
  619.                    remove an LDAPAttribute by object, the
  620.                    LDAPAttribute.getName method can be used:
  621.  
  622.                    LDAPAttributeSet.remove( attr.getName() );
  623.  
  624.  
  625. 5.2.7.  removeElementAt
  626.  
  627.    public void removeElementAt(int index)
  628.                                throws ArrayIndexOutOfBoundsException
  629.  
  630.    Removes the attribute at the position specified by the index.  The
  631.    index is 0-based.
  632.  
  633.    Parameters are:
  634.  
  635.    index           Index of the attribute to remove.
  636.  
  637.  
  638. 5.2.8.  size
  639.  
  640.    public int size()
  641.  
  642.    Returns the number of attributes in this set.
  643.  
  644.  
  645. 5.3.  public class LDAPCompareAttrNames implements LDAPEntryComparator
  646.  
  647. An object of this class supports sorting search results by attribute
  648. name, in ascending or descending order.
  649.  
  650.  
  651. 5.3.1.  Constructors
  652.  
  653.    public LDAPCompareAttrNames(String attrName)
  654.  
  655.  
  656.  
  657.  
  658. Expires 3/98                                                   [Page 11]
  659.  
  660.  
  661.  
  662.  
  663.  
  664. JAVA LDAP API                                             September 1997
  665.  
  666.  
  667.    Constructs an object that will sort results by a single attribute, in
  668.    ascending order.
  669.  
  670.  
  671.    public LDAPCompareAttrNames(String attrName,
  672.                                boolean ascendingFlag)
  673.  
  674.    Constructs an object that will sort results by a single attribute, in
  675.    either ascending or descending order.
  676.  
  677.  
  678.    public LDAPCompareAttrNames(String[] attrNames)
  679.  
  680.    Constructs an object that will sort by one or more attributes, in the
  681.    order provided, in ascending order.
  682.  
  683.  
  684.    public LDAPCompareAttrNames(String[] attrNames,
  685.                                boolean[] ascendingFlags)
  686.                                throws LDAPException
  687.  
  688.    Constructs an object that will sort by one or more attributes, in the
  689.    order provided, in either ascending or descending order for each
  690.    attribute.
  691.  
  692.    Parameters are:
  693.  
  694.    attrName        Name of an attribute to sort by.
  695.  
  696.    attrNames       Array of names of attributes to sort by.
  697.  
  698.    ascendingFlag   true to sort in ascending order, false for descending
  699.                    order.
  700.  
  701.    ascendingFlags  Array of flags, one for each attrName, where each one
  702.                    is true to sort in ascending order, false for des-
  703.                    cending order. An LDAPException is thrown if the
  704.                    length of ascendingFlags is not greater than or equal
  705.                    to the length of attrNames.
  706.  
  707.  
  708. 5.3.2.  isGreater
  709.  
  710.    public boolean isGreater (LDAPEntry entry1, LDAPEntry entry2)
  711.  
  712.    Returns true if entry1 is to be considered greater than entry2, for
  713.    the purpose of sorting, based on the attribute name or names provided
  714.    on object construction.
  715.  
  716.  
  717.  
  718. Expires 3/98                                                   [Page 12]
  719.  
  720.  
  721.  
  722.  
  723.  
  724. JAVA LDAP API                                             September 1997
  725.  
  726.  
  727.    Parameters are:
  728.  
  729.    entry1          Target entry for comparison.
  730.  
  731.    entry2          Entry to be compared to.
  732.  
  733.  
  734. 5.4.  public class LDAPConnection implements LDAPv3, Cloneable
  735.  
  736. LDAPConnection is the central class that encapsulates the connection to
  737. a Directory Server through the LDAP protocol. It implements the LDAPv2
  738. and LDAPv3 interfaces. An LDAPConnection object is not connected on con-
  739. struction, and may only be connected to one server at one port. Multiple
  740. threads may share this single connection, and an application may have
  741. more than one LDAPConnection object, connected to the same or different
  742. Directory Servers.
  743.  
  744. Besides the methods described for LDAPv2 and LDAPv3, LDAPConnection pro-
  745. vides the following methods.
  746.  
  747. 5.4.1.  Constructors
  748.  
  749.    public LDAPConnection()
  750.  
  751.    Constructs a new LDAPConnection object, which represents a connection
  752.    to an LDAP server.
  753.  
  754.    Calling the constructor does not actually establish the connection.
  755.    To connect to the LDAP server, use the connect method.
  756.  
  757.  
  758.    public LDAPConnection(LDAPSocketFactory factory)
  759.  
  760.    Constructs a new LDAPConnection object, which will use the supplied
  761.    class factory to construct a socket connection during
  762.    LDAPConnection.connect().
  763.  
  764.    Parameters are:
  765.  
  766.    factory         An object capable of producing a Socket.
  767.  
  768.  
  769. 5.4.2.  clone
  770.  
  771.    public LDAPConnection clone()
  772.  
  773.    Returns a copy of the object with a private context, but sharing the
  774.    network connection if there is one. The network connection remains
  775.  
  776.  
  777.  
  778. Expires 3/98                                                   [Page 13]
  779.  
  780.  
  781.  
  782.  
  783.  
  784. JAVA LDAP API                                             September 1997
  785.  
  786.  
  787.    open until all clones have disconnected or gone out of scope. Any
  788.    connection opened after cloning is private to the object making the
  789.    connection.
  790.  
  791.  
  792. 5.4.3.  getAuthenticationDN
  793.  
  794.    public String getAuthenticationDN()
  795.  
  796.    Returns the distinguished name (DN) used for authentication by this
  797.    object.
  798.  
  799.  
  800. 5.4.4.  getAuthenticationPassword
  801.  
  802.    public String getAuthenticationPassword()
  803.  
  804.    Returns the password used for simple authentication by this object.
  805.  
  806.  
  807. 5.4.5.  getHost
  808.  
  809.    public String getHost()
  810.  
  811.    Returns the host name of the LDAP server to which the object is or
  812.    was last connected, in the format originally specified.
  813.  
  814.  
  815. 5.4.6.  getPort
  816.  
  817.    public int getPort()
  818.  
  819.    Returns the port number of the LDAP server to which the object is or
  820.    was last connected.
  821.  
  822.  
  823. 5.4.7.  getProperty
  824.  
  825.    public Object getProperty(String name) throws LDAPException
  826.  
  827.    Gets a property of a connection object.
  828.  
  829.    Parameters are:
  830.  
  831.    name            Name of the property to be returned.
  832.  
  833.                    The following read-only properties are available for
  834.                    any given connection:
  835.  
  836.  
  837.  
  838. Expires 3/98                                                   [Page 14]
  839.  
  840.  
  841.  
  842.  
  843.  
  844. JAVA LDAP API                                             September 1997
  845.  
  846.  
  847.       LDAP_PROPERTY_SDK             The version of this SDK, as a Float
  848.                                     data type.
  849.  
  850.  
  851.       LDAP_PROPERTY_PROTOCOL        The highest supported version of the
  852.                                     LDAP protocol, as a Float data type.
  853.  
  854.  
  855.       LDAP_PROPERTY_SECURITY        A comma-separated list of the types
  856.                                     of authentication supported, as a
  857.                                     String.
  858.  
  859.    Other properties may be available in particular implementations of
  860.    the class, and used to modify operations such as search.
  861.  
  862.    An LDAPException is thrown if the requested property is not avail-
  863.    able.
  864.  
  865. 5.4.8.  getSearchConstraints
  866.  
  867.    public LDAPSearchConstraints getSearchConstraints()
  868.  
  869.    Returns the set of search constraints that apply to all searches per-
  870.    formed through this connection (unless a different set of search con-
  871.    straints is specified when calling the search method).
  872.  
  873.    Note that the getOption method can be used to get individual con-
  874.    straints (rather than getting the entire set of constraints).
  875.  
  876.    Typically, the getSearchConstraints method is used to create a
  877.    slightly different set of search constraints to apply to a particular
  878.    search.
  879.  
  880.  
  881. 5.4.9.  getSocketFactory
  882.  
  883.    public static LDAPSocketFactory getSocketFactory()
  884.  
  885.    Returns the default LDAPSocketFactory used to establish a connection
  886.    to a server.
  887.  
  888.  
  889. 5.4.10.  isAuthenticated
  890.  
  891.    public boolean isAthenticated()
  892.  
  893.    Indicates whether the object has authenticated to the connected LDAP
  894.    server.
  895.  
  896.  
  897.  
  898. Expires 3/98                                                   [Page 15]
  899.  
  900.  
  901.  
  902.  
  903.  
  904. JAVA LDAP API                                             September 1997
  905.  
  906.  
  907. 5.4.11.  isConnected
  908.  
  909.    public boolean isConnected()
  910.  
  911.    Indicates whether the connection represented by this object is open
  912.    at this time.
  913.  
  914.  
  915. 5.4.12.  read
  916.  
  917.    public static LDAPEntry read(LDAPUrl toGet) throws LDAPException
  918.  
  919.    Reads the entry specified by the LDAP URL.
  920.  
  921.    When this method is called, a new connection is created automati-
  922.    cally, using the host and port specified in the URL. After finding
  923.    the entry, the method closes the connection (in other words, it
  924.    disconnects from the LDAP server).
  925.  
  926.    If the URL specifies a filter and scope, these are not used. Of the
  927.    information specified in the URL, this method only uses the LDAP host
  928.    name and port number, the base distinguished name (DN), and the list
  929.    of attributes to return.
  930.  
  931.    The method returns the entry specified by the base DN.
  932.  
  933.    Parameters are:
  934.  
  935.    toGet           LDAP URL specifying the entry to read.
  936.  
  937.  
  938. 5.4.13.  search
  939.  
  940.    public static LDAPSearchResults search(LDAPUrl toGet) throws LDAPEx-
  941.    ception
  942.  
  943.    Performs the search specified by the LDAP URL, returning an enumer-
  944.    able LDAPSearchResults object.
  945.  
  946.  
  947.    public static LDAPSearchResults search(LDAPUrl toGet,
  948.                                           LDAPSearchConstraints cons)
  949.                                           throws LDAPException
  950.  
  951.    Perfoms the search specified by the LDAP URL. This method also allows
  952.    specifying constraints for the search (such as the maximum number of
  953.    entries to find or the maximum time to wait for search results).
  954.  
  955.  
  956.  
  957.  
  958. Expires 3/98                                                   [Page 16]
  959.  
  960.  
  961.  
  962.  
  963.  
  964. JAVA LDAP API                                             September 1997
  965.  
  966.  
  967.    As part of the search constraints, a choice can be made as to whether
  968.    to have the results delivered all at once or in smaller batches. If
  969.    the results are to be delivered in smaller batches, each iteration
  970.    blocks only until the next batch of results is returned.
  971.  
  972.    Parameters are:
  973.  
  974.    toGet           LDAP URL specifying the entry to read.
  975.  
  976.    cons            Constraints specific to the search.
  977.  
  978.  
  979. 5.4.14.  setOption
  980.  
  981.    public void setOption(int option,
  982.                          Object value)
  983.                          throws LDAPException
  984.  
  985.    Sets the value of the specified option for this LDAPConnection
  986.    object.
  987.  
  988.    These options represent the default search constraints for the
  989.    current connection. Some of these options are also propagated through
  990.    the LDAPSearchConstraints, which can be obtained from the connection
  991.    object with the getSearchConstraints method.
  992.  
  993.    The option that is set here applies to all subsequent searches per-
  994.    formed through the current connection, unless it is overridden with
  995.    an LDAPSearchConstraints at the time of search.
  996.  
  997.    To set a constraint only for a particular search, create an LDAPSear-
  998.    chConstraints object with the new constraints and pass it to the
  999.    LDAPConnection.search method.
  1000.  
  1001.    Parameters are:
  1002.  
  1003.  
  1004.    option          One of the following options:
  1005.  
  1006.  
  1007.       Option                        Type        Description
  1008.  
  1009.  
  1010.       LDAPv2.DEREF                  Integer     Specifies under what
  1011.                                                 circumstances the object
  1012.                                                 dereferences aliases.
  1013.                                                 By default, the value of
  1014.                                                 this option is
  1015.  
  1016.  
  1017.  
  1018. Expires 3/98                                                   [Page 17]
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024. JAVA LDAP API                                             September 1997
  1025.  
  1026.  
  1027.                                                 LDAPv2.DEREF_NEVER.
  1028.  
  1029.             Legal values for this option are:
  1030.  
  1031.             LDAPv2.DEREF_NEVER       Aliases are never dereferenced.
  1032.  
  1033.  
  1034.             LDAPv2.DEREF_FINDING     aliases are dereferenced when find-
  1035.                                      ing the starting point for the
  1036.                                      search (but not when searching
  1037.                                      under that starting entry).
  1038.  
  1039.  
  1040.             LDAPv2.DEREF_SEARCHING   Aliases are dereferenced when
  1041.                                      searching the entries beneath the
  1042.                                      starting point of the search (but
  1043.                                      not when finding the starting
  1044.                                      entry).
  1045.  
  1046.  
  1047.             LDAPv2.DEREF_ALWAYS      Aliases are always dereferenced
  1048.                                      (both when finding the starting
  1049.                                      point for the search and when
  1050.                                      searching under that starting
  1051.                                      entry).
  1052.  
  1053.  
  1054.       LDAPv2.SIZELIMIT              Integer     Specifies the maximum
  1055.                                                 number of search results
  1056.                                                 to return. If this
  1057.                                                 option is set to 0,
  1058.                                                 there is no maximum
  1059.                                                 limit.
  1060.  
  1061.                                                 By default, the value of
  1062.                                                 this option is 1000.
  1063.  
  1064.  
  1065.       LDAPv2.TIMELIMIT              Integer     Specifies the maximum
  1066.                                                 number of milliseconds
  1067.                                                 to wait for results
  1068.                                                 before timing out. If
  1069.                                                 this option is set to 0,
  1070.                                                 there is no maximum time
  1071.                                                 limit. The actual granu-
  1072.                                                 larity of the timeout
  1073.                                                 depends on the implemen-
  1074.                                                 tation.
  1075.  
  1076.  
  1077.  
  1078. Expires 3/98                                                   [Page 18]
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084. JAVA LDAP API                                             September 1997
  1085.  
  1086.  
  1087.                                                 By default, the value of
  1088.                                                 this option is 0.
  1089.  
  1090.  
  1091.       LDAPv2.REFERRALS              Boolean     Specifies whether or not
  1092.                                                 the client follows
  1093.                                                 referrals automatically.
  1094.                                                 If true, the client fol-
  1095.                                                 lows referrals automati-
  1096.                                                 cally.  If false, an
  1097.                                                 LDAPReferralException is
  1098.                                                 raised when a referral
  1099.                                                 is detected.
  1100.  
  1101.                                                 Referrals of any type
  1102.                                                 other to an LDAP server
  1103.                                                 (i.e. a referral URL
  1104.                                                 other than
  1105.                                                 ldap://something) are
  1106.                                                 ignored on automatic
  1107.                                                 referral following.
  1108.  
  1109.                                                 By default, the value of
  1110.                                                 this option is false.
  1111.  
  1112.  
  1113.       LDAPv2.REFERRALS_REBIND_PROC  LDAPRebind  Specifies an object that
  1114.                                                 implements the LDAPRe-
  1115.                                                 bind interface.  A user
  1116.                                                 of the class library
  1117.                                                 must define this class
  1118.                                                 and the getRebindAuthen-
  1119.                                                 tication method that
  1120.                                                 will be used to get the
  1121.                                                 distinguished name and
  1122.                                                 password to use for
  1123.                                                 authentication. If this
  1124.                                                 value is null and REFER-
  1125.                                                 RALS is true, referrals
  1126.                                                 will be followed with
  1127.                                                 anonymous (= no) authen-
  1128.                                                 tication.
  1129.  
  1130.                                                 By default, the value of
  1131.                                                 this option is null.
  1132.  
  1133.  
  1134.       LDAPv2.REFERRALS_HOP_LIMIT     Integer    Specifies the maximum
  1135.  
  1136.  
  1137.  
  1138. Expires 3/98                                                   [Page 19]
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144. JAVA LDAP API                                             September 1997
  1145.  
  1146.  
  1147.                                                 number of referrals in a
  1148.                                                 sequence that the client
  1149.                                                 will follow. For exam-
  1150.                                                 ple, if
  1151.                                                 REFERRALS_HOP_LIMIT is
  1152.                                                 5, the client will fol-
  1153.                                                 low no more than 5
  1154.                                                 referrals in a row when
  1155.                                                 resolving a single LDAP
  1156.                                                 request.
  1157.  
  1158.                                                 The default value of
  1159.                                                 this option is 10.
  1160.  
  1161.  
  1162.       LDAPv2.BATCHSIZE               Integer    Specifies the number of
  1163.                                                 search results to return
  1164.                                                 at a time. For example,
  1165.                                                 if BATCHSIZE is 1,
  1166.                                                 enumerating an LDAPSear-
  1167.                                                 chResults will block
  1168.                                                 only until one entry is
  1169.                                                 available. If it is 0,
  1170.                                                 enumerating will block
  1171.                                                 until all entries have
  1172.                                                 been retrieved from the
  1173.                                                 server.
  1174.  
  1175.                                                 The default value of
  1176.                                                 this option is 1.
  1177.  
  1178.  
  1179.    value           The value to assign to the option. The value must be
  1180.                    the java.lang object wrapper for the appropriate
  1181.                    parameter (e.g. boolean->Boolean, int->Integer) .
  1182.  
  1183.  
  1184. 5.4.15.  setProperty
  1185.  
  1186.    public void setProperty(String name, Object value) throws LDAPExcep-
  1187.    tion
  1188.  
  1189.    Sets a property of a connection object.
  1190.  
  1191.    No property names have been defined at this time, but the mechanism
  1192.    is in place in order to support revisional as well as dynamic exten-
  1193.    sions to operation modifiers.
  1194.  
  1195.  
  1196.  
  1197.  
  1198. Expires 3/98                                                   [Page 20]
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204. JAVA LDAP API                                             September 1997
  1205.  
  1206.  
  1207.    Parameters are:
  1208.  
  1209.    name            Name of the property to set.
  1210.  
  1211.    value           Value to assign to the property.
  1212.  
  1213.                    An LDAPException is thrown if the specified property
  1214.                    is not supported.
  1215.  
  1216. 5.4.16.  setSocketFactory
  1217.  
  1218.    public static void setSocketFactory(LDAPSocketFactory factory)
  1219.  
  1220.    Establishes the default LDAPSocketFactory used to establish a connec-
  1221.    tion to a server.
  1222.  
  1223.    This method is implemented as once-only. It is useful to be able to
  1224.    change the run-time connection behavior of a whole application with a
  1225.    single instruction, but the results would be confusing, and the
  1226.    side-effects dangerous, if the global default factory could be
  1227.    changed at arbitrary times by different threads. It should be called
  1228.    before the first connect(). If called (for the first time) after con-
  1229.    necting, the new factory will not be used until/unless a new connec-
  1230.    tion is attempted with the object.
  1231.  
  1232.    A typical usage would be:
  1233.  
  1234.        if (usingTLS) {
  1235.            LDAPConnection.setSocketFactory(myTLSFactory);
  1236.        }
  1237.        ...
  1238.        LDAPConnection conn = new LDAPConnection();
  1239.        conn.connect(myHost, myPort);
  1240.  
  1241.    In this example, connections are constructed with the default LDAP-
  1242.    SocketFactory.  At application start-up time, the default may be set
  1243.    to use a particular provided TLS socket factory.
  1244.  
  1245.    Parameters are:
  1246.  
  1247.    factory         A factory object which can construct socket connec-
  1248.                    tions for an LDAPConnection.
  1249.  
  1250.  
  1251. 5.5.  public class LDAPControl implements Cloneable
  1252.  
  1253. An LDAPControl encapsulates optional additional parameters or con-
  1254. straints to be applied to LDAP operations. If set as a Server Control,
  1255.  
  1256.  
  1257.  
  1258. Expires 3/98                                                   [Page 21]
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264. JAVA LDAP API                                             September 1997
  1265.  
  1266.  
  1267. it is sent to the server along with operation requests. If set as a
  1268. Client Control, it is not sent to the server, but rather interpreted
  1269. locally by the client. LDAPControl is an LDAPv3 extension, and is not
  1270. supported in an LDAPv2 environment.
  1271.  
  1272.  
  1273. 5.5.1.  Constructors
  1274.  
  1275.    public LDAPControl(String id,
  1276.                       boolean critical,
  1277.                       byte vals[])
  1278.  
  1279.    Parameters are:
  1280.  
  1281.    id              The type of the Control, as a string.
  1282.  
  1283.    critical        True if the LDAP operation should be discarded if the
  1284.                    server does not support this Control.
  1285.  
  1286.    vals            Control-specific data.
  1287.  
  1288.  
  1289. 5.5.2.  getID
  1290.  
  1291.    public String getID()
  1292.  
  1293.    Returns the identifier of the control.
  1294.  
  1295.  
  1296. 5.5.3.  isCritical
  1297.  
  1298.    public boolean isCritical()
  1299.  
  1300.    Returns true if the control must be supported for an associated
  1301.    operation to be executed.
  1302.  
  1303.  
  1304. 5.5.4.  getValue
  1305.  
  1306.    public byte[] getValue()
  1307.  
  1308.    Returns the control-specific data of the object.
  1309.  
  1310.  
  1311. 5.6.  public class LDAPDN
  1312.  
  1313. A utility class representing a distinguished name (DN).
  1314.  
  1315.  
  1316.  
  1317.  
  1318. Expires 3/98                                                   [Page 22]
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. JAVA LDAP API                                             September 1997
  1325.  
  1326.  
  1327. 5.6.1.  explodeDN
  1328.  
  1329.    public static String[] explodeDN(String dn,
  1330.                                     boolean noTypes)
  1331.  
  1332.    Returns the individual components of a distinguished name (DN).
  1333.  
  1334.    Parameters are:
  1335.  
  1336.    dn              Distinguished name, e.g. "cn=Babs
  1337.                    Jensen,ou=Accounting,o=Acme,c=us"
  1338.  
  1339.    noTypes         If true, returns only the values of the components,
  1340.                    and not the names, e.g. "Babs Jensen", "Accounting",
  1341.                    "Acme", "us" - instead of "cn=Babs Jensen",
  1342.                    "ou=Accounting", "o=Acme", and "c=us".
  1343.  
  1344.  
  1345. 5.6.2.  explodeRDN
  1346.  
  1347.    public static String[] explodeRDN(String rdn,
  1348.                                      boolean noTypes)
  1349.  
  1350.    Returns the individual components of a relative distinguished name
  1351.    (RDN).
  1352.  
  1353.    Parameters are:
  1354.  
  1355.    rdn             Relative distinguished name, i.e. the left-most com-
  1356.                    ponent of a distinguished name.
  1357.  
  1358.    noTypes         If true, returns only the values of the components,
  1359.                    and not the names.
  1360.  
  1361.  
  1362. 5.7.  public class LDAPEntry
  1363.  
  1364. An LDAPEntry represents a single entry in a directory, consisting of a
  1365. distinguished name (DN) and zero or more attributes. An instance of
  1366. LDAPEntry is created in order to add an entry to a Directory, and
  1367. instances are returned on a search by enumerating an LDAPSearchResults.
  1368.  
  1369.  
  1370. 5.7.1.  Constructors
  1371.  
  1372.    public LDAPEntry()
  1373.  
  1374.    Constructs an empty entry.
  1375.  
  1376.  
  1377.  
  1378. Expires 3/98                                                   [Page 23]
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384. JAVA LDAP API                                             September 1997
  1385.  
  1386.  
  1387.    public LDAPEntry(String dn)
  1388.  
  1389.    Constructs a new entry with the specified distinguished name and with
  1390.    an empty attribute set.
  1391.  
  1392.  
  1393.    public LDAPEntry(String dn
  1394.                     LDAPAttributeSet attrs)
  1395.  
  1396.    Constructs a new entry with the specified distinguished name and set
  1397.    of attributes.
  1398.  
  1399.    Parameters are:
  1400.  
  1401.    dn              The distinguished name of the new entry. The value is
  1402.                    not validated. An invalid distinguished name will
  1403.                    cause adding of the entry to a directory to fail.
  1404.  
  1405.    attrs           The initial set of attributes assigned to the entry.
  1406.  
  1407.  
  1408. 5.7.2.  getAttribute
  1409.  
  1410.    public LDAPAttribute[] getAttribute(String attrName)
  1411.  
  1412.    Returns the attribute matching the specified attrName. For example,
  1413.    getAttribute("cn") returns only the "cn" attribute;
  1414.    getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute.
  1415.    In both cases, null is returned if there is no exact match to the
  1416.    specified attrName.
  1417.  
  1418.    public LDAPAttribute[] getAttribute(String attrName, String lang)
  1419.  
  1420.    Returns a single best-match attribute, or none if no match is avail-
  1421.    able in the entry.
  1422.  
  1423.    LDAP version 3 allows adding a subtype specification to an attribute
  1424.    name. "cn;lang-ja", for example, indicates a Japanese language sub-
  1425.    type of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype of
  1426.    "cn;lang-ja". This feature may be used to provide multiple localiza-
  1427.    tions in the same Directory. For attributes which do not vary among
  1428.    localizations, only the base attribute may be stored, whereas for
  1429.    others there may be varying degrees of specialization.
  1430.  
  1431.    getAttribute(attrName,lang) returns the subtype that matches attrName
  1432.    and that best matches lang. If there are subtypes other than "lang"
  1433.    subtypes included in attrName, e.g. "cn;binary", only attributes with
  1434.    all of those subtypes are returned. If lang is null or empty, the
  1435.  
  1436.  
  1437.  
  1438. Expires 3/98                                                   [Page 24]
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444. JAVA LDAP API                                             September 1997
  1445.  
  1446.  
  1447.    method behaves as getAttribute(attrName). If there are no matching
  1448.    attributes, null is returned.
  1449.  
  1450.    Example:
  1451.       Assume the entry contains only the following attributes:
  1452.          cn;lang-en
  1453.          cn;lang-ja-JP-kanji
  1454.          sn
  1455.       getAttribute( "cn" ) returns null.
  1456.       getAttribute( "sn" ) returns the "sn" attribute.
  1457.       getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute.
  1458.       getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute.
  1459.       getAttribute( "cn", "lang-ja" ) returns null.
  1460.       getAttribute( "sn", "lang-en" ) returns the "sn" attribute.
  1461.  
  1462.    Parameters are:
  1463.  
  1464.    attrName        The name of an attribute to retrieve, with or without
  1465.                    subtype specification(s). "cn", "cn;phonetic", and
  1466.                    "cn;binary" are valid attribute names.
  1467.  
  1468.    lang            A language specification as in [14], with optional
  1469.                    subtypes appended using "-" as separator. "lang-en",
  1470.                    "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are
  1471.                    valid language specification.
  1472.  
  1473.  
  1474. 5.7.3.  getAttributeSet
  1475.  
  1476.    public LDAPAttributeSet getAttributeSet()
  1477.  
  1478.    Returns the attribute set of the entry. All base and subtype variants
  1479.    of all attributes are returned. The LDAPAttributeSet returned may be
  1480.    empty if there are no attributes in the entry.
  1481.  
  1482.  
  1483.    public LDAPAttributeSet getAttributeSet(String subtype)
  1484.  
  1485.    Returns an attribute set from the entry, consisting of only those
  1486.    attributes matching the specified subtype(s). This may be used to
  1487.    extract only a particular language variant subtype of each attribute,
  1488.    if it exists. "subtype" may be, for example, "lang-ja", "binary", or
  1489.    "lang-ja;phonetic". If more than one subtype is specified, separated
  1490.    with a semicolon, only those attributes with all of the named sub-
  1491.    types will be returned.  The LDAPAttributeSet returned may be empty
  1492.    if there are no matching attributes in the entry.
  1493.  
  1494.    Parameters are:
  1495.  
  1496.  
  1497.  
  1498. Expires 3/98                                                   [Page 25]
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504. JAVA LDAP API                                             September 1997
  1505.  
  1506.  
  1507.    subtype         One or more subtype specification(s), separated with
  1508.                    semicolons.  "lang-ja" and "lang-en;phonetic" are
  1509.                    valid subtype specifications.
  1510.  
  1511.  
  1512. 5.7.4.  getDN
  1513.  
  1514.    public String getDN()
  1515.  
  1516.    Returns the distinguished name of the entry.
  1517.  
  1518.  
  1519. 5.8.  public class LDAPExtendedOperation
  1520.  
  1521. An LDAPExtendedOperation encapsulates an ID which uniquely identifies a
  1522. particular extended operation, known to a particular server, and the
  1523. data associated with the operation.
  1524.  
  1525.  
  1526. 5.8.1.  Constructors
  1527.  
  1528.    public LDAPExtendedOperation(String oid,
  1529.                                 byte[] vals)
  1530.  
  1531.    Constructs a new object with the specified object ID and data.
  1532.  
  1533.    Parameters are:
  1534.  
  1535.    oid             The unique identifier of the operation.
  1536.  
  1537.    vals            The operation-specific data of the operation/
  1538.  
  1539.  
  1540. 5.8.2.  getID
  1541.  
  1542.    public String getID()
  1543.  
  1544.    Returns the unique identifier of the operation.
  1545.  
  1546.  
  1547.  
  1548. 5.8.3.  getValue
  1549.  
  1550.    public byte[] getValue()
  1551.  
  1552.    Returns the operation-specific data (not a copy, a reference).
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558. Expires 3/98                                                   [Page 26]
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564. JAVA LDAP API                                             September 1997
  1565.  
  1566.  
  1567. 5.9.  public interface LDAPEntryComparator
  1568.  
  1569. An object of this class can implement arbitrary sorting algorithms for
  1570. search results.
  1571.  
  1572.  
  1573. 5.9.1.  isGreater
  1574.  
  1575.    public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2)
  1576.  
  1577.    Returns true if entry1 is to be considered greater than or equal to
  1578.    entry2, for the purpose of sorting.
  1579.  
  1580.    Parameters are:
  1581.  
  1582.    entry1          Target entry for comparison.
  1583.  
  1584.    entry2          Entry to be compared to.
  1585.  
  1586.  
  1587. 5.10.  public class LDAPException extends Exception
  1588.  
  1589. Thrown to indicate that an error has occurred. An LDAPException can
  1590. result from physical problems (such as network errors) as well as prob-
  1591. lems with LDAP operations (for example, if the LDAP add operation fails
  1592. because of a duplicate entry).
  1593.  
  1594. Most errors that occur throw this type of exception.  The
  1595. getLDAPResultCode() method returns the specific result code, which can
  1596. be compared against standard LDAP result codes as defined in [11], sec-
  1597. tion 4.
  1598.  
  1599.  
  1600. 5.10.1.  Constructors
  1601.  
  1602.    public LDAPException()
  1603.  
  1604.    Constructs a default exception with no specific error information.
  1605.  
  1606.  
  1607.    public LDAPException(String message,
  1608.                         int resultCode)
  1609.  
  1610.    Constructs an exception with an error code and a specified string as
  1611.    additional information.
  1612.  
  1613.    Parameters are:
  1614.  
  1615.  
  1616.  
  1617.  
  1618. Expires 3/98                                                   [Page 27]
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624. JAVA LDAP API                                             September 1997
  1625.  
  1626.  
  1627.    message         The additional error information.
  1628.  
  1629.    resultCode      The result code returned
  1630.  
  1631.  
  1632. 5.10.2.  getLDAPErrorMessage
  1633.  
  1634.    public String getLDAPErrorMessage()
  1635.  
  1636.    Returns the error message, if this message is available (that is, if
  1637.    this message was set). If the message was not set, this method
  1638.    returns null.
  1639.  
  1640.  
  1641. 5.10.3.  getLDAPResultCode
  1642.  
  1643.    public int getLDAPResultCode()
  1644.  
  1645.    Returns the result code from the exception. The codes are defined as
  1646.    public final static int members of this class. If the exception is a
  1647.    result of error information returned from a directory operation, the
  1648.    code will be one of those defined in [11]. Otherwise, a local error
  1649.    code is returned (see "Error codes" below).
  1650.  
  1651. 5.10.4.  getMatchedDN
  1652.  
  1653.    public String getMatchedDN()
  1654.  
  1655.    Returns the part of a submitted distinguished name which could be
  1656.    matched by the server. If the exception was caused by a local error,
  1657.    such as no server available, the return value is null. If the excep-
  1658.    tion resulted from an operation being executed on a server, the value
  1659.    is an empty String except when the result of the operation was one of
  1660.    the following:
  1661.  
  1662.       NO_SUCH_OBJECT
  1663.       ALIAS_PROBLEM
  1664.       INVALID_DN_SYNTAX
  1665.       ALIAS_DEREFERENCING_PROBLEM
  1666.  
  1667.  
  1668. 5.10.5.  Error codes
  1669.  
  1670. See [11] and [7] for a discussion of the meanings of the codes.
  1671.  
  1672.      ADMIN_LIMIT_EXCEEDED
  1673.      AFFECTS_MULTIPLE_DSAS
  1674.      ALIAS_DEREFERENCING_PROBLEM
  1675.  
  1676.  
  1677.  
  1678. Expires 3/98                                                   [Page 28]
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684. JAVA LDAP API                                             September 1997
  1685.  
  1686.  
  1687.      ALIAS_PROBLEM
  1688.      ATTRIBUTE_OR_VALUE_EXISTS
  1689.      AUTH_METHOD_NOT_SUPPORTED
  1690.      BUSY
  1691.      COMPARE_FALSE
  1692.      COMPARE_TRUE
  1693.      CONFIDENTIALITY_REQUIRED
  1694.      CONSTRAINT_VIOLATION
  1695.      ENTRY_ALREADY_EXISTS
  1696.      INAPPROPRIATE_AUTHENTICATION
  1697.      INAPPROPRIATE_MATCHING
  1698.      INSUFFICIENT_ACCESS_RIGHTS
  1699.      INVALID_ATTRIBUTE_SYNTAX
  1700.      INVALID_CREDENTIALS
  1701.      INVALID_DN_SYNTAX
  1702.      IS_LEAF
  1703.      LDAP_PARTIAL_RESULTS
  1704.      LOOP_DETECT
  1705.      NAMING_VIOLATION
  1706.      NO_SUCH_ATTRIBUTE
  1707.      NO_SUCH_OBJECT
  1708.      NOT_ALLOWED_ON_NONLEAF
  1709.      NOT_ALLOWED_ON_RDN
  1710.      OBJECT_CLASS_MODS_PROHIBITED
  1711.      OBJECT_CLASS_VIOLATION
  1712.      OPERATIONS_ERROR
  1713.      OTHER
  1714.      PROTOCOL_ERROR
  1715.      REFERRAL
  1716.      SIZE_LIMIT_EXCEEDED
  1717.      STRONG_AUTH_NOT_SUPPORTED
  1718.      STRONG_AUTH_REQUIRED
  1719.      SUCCESS
  1720.      TIME_LIMIT_EXCEEDED
  1721.      UNAVAILABLE
  1722.      UNAVAILABLE_CRITICAL_EXTENSION
  1723.      UNDEFINED_ATTRIBUTE_TYPE
  1724.      UNWILLING_TO_PERFORM
  1725.  
  1726.    Local errors, resulting from actions other than an operation on a
  1727.    server, are among the following:
  1728.  
  1729.      CONNECT_ERROR
  1730.      PARAM_ERROR
  1731.      SERVER_DOWN
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738. Expires 3/98                                                   [Page 29]
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744. JAVA LDAP API                                             September 1997
  1745.  
  1746.  
  1747. 5.11.  public class LDAPModification
  1748.  
  1749. A single change specification for an LDAPAttribute.
  1750.  
  1751.  
  1752. 5.11.1.  Constructors
  1753.  
  1754.    public LDAPModification(int op,
  1755.                            LDAPAttribute attr)
  1756.  
  1757.    Specifies a modification to be made to an attribute.
  1758.  
  1759.    Parameters are:
  1760.  
  1761.    op              The type of modification to make, which can be one of
  1762.                    the following:
  1763.  
  1764.       LDAPModification.ADD     The value should be added to the attri-
  1765.                                bute
  1766.  
  1767.       LDAPModification.DELETE  The value should be removed from the
  1768.                                attribute
  1769.  
  1770.       LDAPModification.REPLACE The value should replace all existing
  1771.                                values of the attribute
  1772.  
  1773.    attr            The attribute (possibly with values) to be modified.
  1774.  
  1775.  
  1776. 5.11.2.  getAttribute
  1777.  
  1778.    public LDAPAttribute getAttribute()
  1779.  
  1780.    Returns the attribute (possibly with values) to be modified.
  1781.  
  1782.  
  1783. 5.11.3.  getOp
  1784.  
  1785.    public int getOp()
  1786.  
  1787.    Returns the type of modification specified by this object.
  1788.  
  1789.  
  1790. 5.12.  public class LDAPModificationSet
  1791.  
  1792. A collection of modifications to be made to the attributes of a single
  1793. entry.
  1794.  
  1795.  
  1796.  
  1797.  
  1798. Expires 3/98                                                   [Page 30]
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804. JAVA LDAP API                                             September 1997
  1805.  
  1806.  
  1807. 5.12.1.  Constructors
  1808.  
  1809.    public LDAPModificationSet()
  1810.  
  1811.    Constructs a new, empty set of modifications.
  1812.  
  1813.  
  1814. 5.12.2.  add
  1815.  
  1816.    public synchronized void add(int op,
  1817.                                 LDAPAttribute attr)
  1818.  
  1819.    Specifies another modification to be added to the set of modifica-
  1820.    tions.
  1821.  
  1822.    Parameters are:
  1823.  
  1824.    op              The type of modification to make, as described for
  1825.                    LDAPModification.
  1826.  
  1827.    attr            The attribute (possibly with values) to be modified.
  1828.  
  1829.  
  1830. 5.12.3.  elementAt
  1831.  
  1832.    public LDAPModification elementAt(int index)
  1833.                                throws ArrayIndexOutOfBoundsException
  1834.  
  1835.    Retrieves a particular LDAPModification object at the position speci-
  1836.    fied by the index.
  1837.  
  1838.    Parameters are:
  1839.  
  1840.    index           Index of the modification to get.
  1841.  
  1842.  
  1843. 5.12.4.  remove
  1844.  
  1845.    public synchronized void remove(String name)
  1846.  
  1847.    Removes the first attribute with the specified name in the set of
  1848.    modifications.
  1849.  
  1850.    Parameters are:
  1851.  
  1852.    name            Name of the attribute to be removed.
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858. Expires 3/98                                                   [Page 31]
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864. JAVA LDAP API                                             September 1997
  1865.  
  1866.  
  1867. 5.12.5.  removeElementAt
  1868.  
  1869.    public void removeElementAt(int index)
  1870.                                throws ArrayIndexOutOfBoundsException
  1871.  
  1872.    Removes a particular LDAPModification object at the position speci-
  1873.    fied by the index.
  1874.  
  1875.  
  1876. index           Index of the modification to remove.
  1877.  
  1878.  
  1879. 5.12.6.  size
  1880.  
  1881.    public int size()
  1882.  
  1883.    Retrieves the number of LDAPModification objects in this set.
  1884.  
  1885.  
  1886. 5.13.  public class LDAPRebindAuth
  1887.  
  1888. Represents information used to authenticate the client in cases where
  1889. the client follows referrals automatically.
  1890.  
  1891.  
  1892. 5.13.1.  Constructors
  1893.  
  1894.    public LDAPRebindAuth(String dn,
  1895.                          String password)
  1896.  
  1897.    Constructs information that is used by the client for authentication
  1898.    when following referrals automatically.
  1899.  
  1900.  
  1901. 5.13.2.  getDN
  1902.  
  1903.    public String getDN()
  1904.  
  1905.    Returns the distinguished name to be used for reauthentication on
  1906.    automatic referral following.
  1907.  
  1908.  
  1909. 5.13.3.  getPassword
  1910.  
  1911.    public String getPassword()
  1912.  
  1913.    Returns the password to be used for reauthentication on automatic
  1914.    referral following.
  1915.  
  1916.  
  1917.  
  1918. Expires 3/98                                                   [Page 32]
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924. JAVA LDAP API                                             September 1997
  1925.  
  1926.  
  1927. 5.14.  public class LDAPReferralException extends LDAPException
  1928.  
  1929. This exception, derived from LDAPException, is thrown when a server
  1930. returns a referral and automatic referral following has not been
  1931. enabled.
  1932.  
  1933.  
  1934. 5.14.1.  Constructors
  1935.  
  1936.    public LDAPReferralException()
  1937.  
  1938.    Constructs a default exception with no specific error information.
  1939.  
  1940.  
  1941.    public LDAPReferralException(String message)
  1942.  
  1943.    Constructs a default exception with a specified string as additional
  1944.    information. This form is used for lower-level errors.
  1945.  
  1946.  
  1947.    public LDAPReferralException(String message,
  1948.                                 int resultCode,
  1949.                                 String serverMessage)
  1950.  
  1951.    Parameters are:
  1952.  
  1953.    message         The additional error information.
  1954.  
  1955.    resultCode      The result code returned
  1956.  
  1957.    serverMessage   Error message specifying additional information from
  1958.                    the server.
  1959.  
  1960.  
  1961. 5.14.2.  getURLs
  1962.  
  1963.    public LDAPUrl[] getURLs()
  1964.  
  1965.    Gets the list of referrals (LDAP URLs to other servers) returned by
  1966.    the LDAP server. This exception is only thrown, and therefor the URL
  1967.    list only available, if automatic referral following is not enabled.
  1968.    The referrals may include URLs of a type other than ones for an LDAP
  1969.    server (i.e. a referral URL other than ldap://something).
  1970.  
  1971.  
  1972. 5.15.  public class LDAPSearchConstraints
  1973.  
  1974. A set of options to control a search operation. There is always an
  1975.  
  1976.  
  1977.  
  1978. Expires 3/98                                                   [Page 33]
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984. JAVA LDAP API                                             September 1997
  1985.  
  1986.  
  1987. LDAPSearchConstraints associated with an LDAPConnection object; its
  1988. values can be changed with LDAPConnection.setOption, or overridden by
  1989. passing an LDAPSearchConstraints object to the search operation.
  1990.  
  1991.  
  1992. 5.15.1.  Constructors
  1993.  
  1994.    public LDAPSearchConstraints()
  1995.  
  1996.    Constructs an LDAPSearchConstraints object that specifies the default
  1997.    set of search constraints.
  1998.  
  1999.  
  2000.    public LDAPSearchConstraints(int msLimit,
  2001.                                 int dereference,
  2002.                                 int maxResults,
  2003.                                 boolean doReferrals,
  2004.                                 int batchSize,
  2005.                                 LDAPRebind rebind_proc,
  2006.                                 int hop_limit)
  2007.  
  2008.    Constructs a new LDAPSearchConstraints object and allows specifying
  2009.    the search constraints in that object.
  2010.  
  2011.    Parameters are:
  2012.  
  2013.    msLimit         Maximum time in milliseconds to wait for results (0
  2014.                    by default, which means that there is no maximum time
  2015.                    limit).
  2016.  
  2017.    dereference     Specifies when aliases should be dereferenced. Must
  2018.                    be either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING,
  2019.                    LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from
  2020.                    LDAPv2 (LDAPv2.LDAP_DEREF_NEVER by default).
  2021.  
  2022.    maxResults      Maximum number of search results to return (1000 by
  2023.                    default).
  2024.  
  2025.    doReferrals     Specify true to follow referrals automatically, or
  2026.                    false to throw an LDAPReferralException error if the
  2027.                    server sends back a referral (false by default)
  2028.  
  2029.    batchSize       Specify the number of results to block on during
  2030.                    enumeration. 0 means to block until all results are
  2031.                    in (1 by default).
  2032.  
  2033.    rebind_proc     Specifies an object of the class that implements the
  2034.                    LDAPRebind interface. The object will be used when
  2035.  
  2036.  
  2037.  
  2038. Expires 3/98                                                   [Page 34]
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044. JAVA LDAP API                                             September 1997
  2045.  
  2046.  
  2047.                    the client follows referrals automatically. The
  2048.                    object provides a method for getting the dis-
  2049.                    tinguished name and password used to authenticate to
  2050.                    another LDAP server during a referral. This field is
  2051.                    null by default.
  2052.  
  2053.    hop_limit       Maximum number of referrals to follow in a sequence
  2054.                    when attempting to resolve a request, when doing
  2055.                    automatic referral following.
  2056.  
  2057.  
  2058. 5.15.2.  getBatchSize
  2059.  
  2060.    public int getBatchSize()
  2061.  
  2062.    Returns the number of results to block on during enumeration of
  2063.    search results. This should be 0 if intermediate results are not
  2064.    needed, and 1 if results are to be processed as they come in.
  2065.  
  2066.  
  2067. 5.15.3.  getDereference
  2068.  
  2069.    public int getDereference()
  2070.  
  2071.    Specifies when aliases should be dereferenced. Returns either
  2072.    LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or
  2073.    LDAP_DEREF_ALWAYS from LDAPv2.
  2074.  
  2075.  
  2076. 5.15.4.  getHopLimit
  2077.  
  2078.    public int getHopLimit()
  2079.  
  2080.    Returns the maximum number of hops to follow during automatic refer-
  2081.    ral following.
  2082.  
  2083.  
  2084. 5.15.5.  getMaxResults
  2085.  
  2086.    public int getMaxResults()
  2087.  
  2088.    Returns the maximum number of search results to be returned; 0 means
  2089.    no limit.
  2090.  
  2091.  
  2092. 5.15.6.  getRebindProc
  2093.  
  2094.    public LDAPRebind getRebindProc()
  2095.  
  2096.  
  2097.  
  2098. Expires 3/98                                                   [Page 35]
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104. JAVA LDAP API                                             September 1997
  2105.  
  2106.  
  2107.    Returns the object that provides the method for getting authentica-
  2108.    tion information.
  2109.  
  2110.  
  2111. 5.15.7.  getReferrals
  2112.  
  2113.    public boolean getReferrals()
  2114.  
  2115.    Specifies whether nor not referrals are followed automatically.
  2116.    Returns true if referrals are to be followed automatically, or false
  2117.    if referrals throw an LDAPReferralException.
  2118.  
  2119.  
  2120. 5.15.8.  getTimeLimit
  2121.  
  2122.    public int getTimeLimit()
  2123.  
  2124.    Returns the maximum number of milliseconds to wait for any operation
  2125.    under these search constraints. If 0, there is no maximum time limit
  2126.    on waiting for the operation results. The actual granularity of the
  2127.    timeout depends on the implementation.
  2128.  
  2129.  
  2130. 5.15.9.  setBatchSize
  2131.  
  2132.    public void setBatchSize(int batchSize)
  2133.  
  2134.    Sets the suggested number of results to block on during enumeration
  2135.    of search results. This should be 0 if intermediate results are not
  2136.    needed, and 1 if results are to be processed as they come in.  The
  2137.    default is 1.
  2138.  
  2139.    Parameters are:
  2140.  
  2141.    batchSize       Blocking size on search enumerations.
  2142.  
  2143.  
  2144. 5.15.10.  setDereference
  2145.  
  2146.    public void setDereference(int dereference)
  2147.  
  2148.    Sets a preference indicating whether or not aliases should be
  2149.    dereferenced, and if so, when.
  2150.  
  2151.    Parameters are:
  2152.  
  2153.    dereference     Either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING,
  2154.                    LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from
  2155.  
  2156.  
  2157.  
  2158. Expires 3/98                                                   [Page 36]
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164. JAVA LDAP API                                             September 1997
  2165.  
  2166.  
  2167.                    LDAPv2.
  2168.  
  2169.  
  2170. 5.15.11.  setHopLimit
  2171.  
  2172.    public void setHopLimit(int hop_limit)
  2173.  
  2174.    Sets the maximum number of hops to follow in sequence during
  2175.    automatic referral following. The default is 5.
  2176.  
  2177.    Parameters are:
  2178.  
  2179.    hop_limit       Maximum number of chained referrals to follow
  2180.                    automatically.
  2181.  
  2182.  
  2183. 5.15.12.  setMaxResults
  2184.  
  2185.    public void setMaxResults(int maxResults)
  2186.  
  2187.    Sets the maximum number of search results to be returned; 0 means no
  2188.    limit.  The default is 1000.
  2189.  
  2190.    Parameters are:
  2191.  
  2192.    maxResults      Maxumum number of search results to return.
  2193.  
  2194.  
  2195. 5.15.13.  setRebindProc
  2196.  
  2197.    public void setRebindProc(LDAPRebind rebind_proc)
  2198.  
  2199.    Specifies the object that provides the method for getting authentica-
  2200.    tion information. The default is null. If referrals is set to true,
  2201.    and the rebindProc is null, referrals will be followed with anonymous
  2202.    (= no) authentication.
  2203.  
  2204.    Parameters are:
  2205.  
  2206.    rebind_proc     An object that implements LDAPRebind.
  2207.  
  2208.  
  2209. 5.15.14.  setReferrals
  2210.  
  2211.    public void setReferrals(boolean doReferrals)
  2212.  
  2213.    Specifies whether nor not referrals are followed automatically, or if
  2214.    referrals throw an LDAPReferralException.  Referrals of any type
  2215.  
  2216.  
  2217.  
  2218. Expires 3/98                                                   [Page 37]
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224. JAVA LDAP API                                             September 1997
  2225.  
  2226.  
  2227.    other to an LDAP server (i.e. a referral URL other than
  2228.    ldap://something) are ignored on automatic referral following. The
  2229.    default is false.
  2230.  
  2231.    Parameters are:
  2232.  
  2233.    doReferrals     True to follow referrals automatically.
  2234.  
  2235.  
  2236. 5.15.15.  setTimeLimit
  2237.  
  2238.    public void setTimeLimit(int msLimit)
  2239.  
  2240.    Sets the maximum number of milliseconds to wait for any operation
  2241.    under these search constraints. If 0, there is no maximum time limit
  2242.    on waiting for the operation results. The actual granularity of the
  2243.    timeout depends on the implementation.
  2244.  
  2245.    Parameters are:
  2246.  
  2247.    msLimit         Maximum milliseconds to wait.
  2248.  
  2249.  
  2250. 5.16.  public class LDAPSearchResults
  2251.  
  2252. An LDAPSearchResults object is returned from a search operation. It
  2253. implements Enumeration, thereby providing access to all entries
  2254. retrieved during the operation.
  2255.  
  2256.  
  2257. 5.16.1.  hasMoreElements
  2258.  
  2259.    public boolean hasMoreElements()
  2260.  
  2261.    Specifies whether or not there are more search results in the
  2262.    enumeration. If true, there are more search results.
  2263.  
  2264.  
  2265. 5.16.2.  next
  2266.  
  2267.    public LDAPEntry next() throws LDAPException
  2268.  
  2269.    Returns the next result in the enumeration as an LDAPEntry. If
  2270.    automatic referral following is disabled, and there are one or more
  2271.    referrals among the search results, next() will throw an LDAPRefer-
  2272.    ralException the last time it is called, after all other results have
  2273.    been returned.
  2274.  
  2275.  
  2276.  
  2277.  
  2278. Expires 3/98                                                   [Page 38]
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284. JAVA LDAP API                                             September 1997
  2285.  
  2286.  
  2287. 5.16.3.  nextElement
  2288.  
  2289.    public Object nextElement()
  2290.  
  2291.    Returns the next result in the enumeration as an Object. This the
  2292.    default implementation of Enumeration.nextElement(). The returned
  2293.    value may be an LDAPEntry or an LDAPReferralException.
  2294.  
  2295.  
  2296. 5.16.4.  sort
  2297.  
  2298.    public void sort(LDAPEntryComparator comp)
  2299.  
  2300.    Sorts all entries in the results using the provided comparison
  2301.    object. If the object has been partially or completely enumerated,
  2302.    only remaining elements are sorted. Sorting the results requires that
  2303.    they all be present. This implies that
  2304.    LDAPSearchResults.nextElement() will always block until all results
  2305.    have been retrieved, after a sort operation.
  2306.  
  2307.    The LDAPCompareAttrNames class is provided to support the common need
  2308.    to collate by a single or multiple attribute values, in ascending or
  2309.    descending order.  Examples are:
  2310.  
  2311.        res.sort(new LDAPCompareAttrNames("cn"));
  2312.  
  2313.        res.sort(new LDAPCompareAttrNames("cn", false));
  2314.  
  2315.        String[] attrNames = { "sn", "givenname" };
  2316.        res.sort(new LDAPCompareAttrNames(attrNames));
  2317.  
  2318.    Parameters are:
  2319.  
  2320.    comp            An object that implements the LDAPEntryComparator
  2321.                    interface to compare two objects of type LDAPEntry.
  2322.  
  2323.  
  2324. 5.17.  public interface LDAPSocketFactory
  2325.  
  2326. Used to construct a socket connection for use in an LDAPConnection.  An
  2327. implementation of this interface may, for example, provide a TLSSocket
  2328. connected to a secure server.
  2329.  
  2330.  
  2331. 5.17.1.  makeSocket
  2332.  
  2333.    public Socket makeSocket(String host, int port)
  2334.                             throws IOException, UnknownHostException
  2335.  
  2336.  
  2337.  
  2338. Expires 3/98                                                   [Page 39]
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344. JAVA LDAP API                                             September 1997
  2345.  
  2346.  
  2347.    Returns a socket connected using the provided host name and port
  2348.    number.
  2349.  
  2350.    There may be additional makeSocket methods defined when interfaces to
  2351.    establish TLS and SASL authentication in the java environment have
  2352.    been standardized.
  2353.  
  2354.    Parameters are:
  2355.  
  2356.    host            Contains a hostname or dotted string representing the
  2357.                    IP address of a host running an LDAP server to con-
  2358.                    nect to.
  2359.  
  2360.    port            Contains the TCP or UDP port number to connect to or
  2361.                    contact. The default LDAP port is 389.
  2362.  
  2363.  
  2364. 5.18.  public class LDAPSortKey
  2365.  
  2366. Encapsulates parameters for sorting search results.
  2367.  
  2368. 5.18.1.  Constructors
  2369.  
  2370.  
  2371.    public LDAPSortKey( String keyDescription )
  2372.  
  2373.    Constructs a new LDAPSortKey object using a, possibly complex, sort-
  2374.    ing specification.
  2375.  
  2376.  
  2377.    public LDAPSortKey( String key, boolean reverse)
  2378.  
  2379.    Constructs a new LDAPSortKey object using an attribute name and a
  2380.    sort order.
  2381.  
  2382.  
  2383.    public LDAPSortKey( String key, boolean reverse, String matchRule)
  2384.  
  2385.    Constructs a new LDAPSortKey object using an attribute name, a sort
  2386.    order, and a matching rule.
  2387.  
  2388.    Parameters are:
  2389.  
  2390.    keyDescription  A single attribute specification to sort by. If pre-
  2391.                    fixed with "-", reverse order sorting is requested. A
  2392.                    matching rule OID may be appended following ":".
  2393.                    Examples:
  2394.                       "cn"
  2395.  
  2396.  
  2397.  
  2398. Expires 3/98                                                   [Page 40]
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404. JAVA LDAP API                                             September 1997
  2405.  
  2406.  
  2407.                       "-cn"
  2408.                       "-cn:1.2.3.4.5"
  2409.  
  2410.    key             An attribute name, e.g. "cn".
  2411.  
  2412.    reverse         True to sort in reverse collation order.
  2413.  
  2414.    matchRule       The object ID (OID) of a matching rule used for col-
  2415.                    lation. If the object will be used to request
  2416.                    server-side sorting of search results, it should be
  2417.                    the OID of a matching rule known to be supported by
  2418.                    that server.
  2419.  
  2420.  
  2421. 5.18.2.  getKey
  2422.  
  2423.  
  2424.    public String getKey()
  2425.  
  2426.    Returns the attribute to be used for collation.
  2427.  
  2428.  
  2429. 5.18.3.  getReverse
  2430.  
  2431.    public boolean getReverse()
  2432.  
  2433.    Returns true if the sort key specifies reverse-order sorting.
  2434.  
  2435.  
  2436. 5.18.4.  getMatchRule
  2437.  
  2438.    public String getMatchRule()
  2439.  
  2440.    Returns the OID to be used as matching rule, or null if none is to be
  2441.    used.
  2442.  
  2443.  
  2444. 5.19.  public class LDAPUrl
  2445.  
  2446. Encapsulates parameters of an LDAP Url query, as defined in [8].  An
  2447. LDAPUrl object can be passed to LDAPConnection.search to retrieve search
  2448. results.
  2449.  
  2450.  
  2451. 5.19.1.  Constructors
  2452.  
  2453.    public LDAPUrl(String url) throws MalformedURLException
  2454.  
  2455.  
  2456.  
  2457.  
  2458. Expires 3/98                                                   [Page 41]
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464. JAVA LDAP API                                             September 1997
  2465.  
  2466.  
  2467.    Constructs a URL object with the specified string as URL.
  2468.  
  2469.  
  2470.    public LDAPUrl(String host,
  2471.                   int port,
  2472.                   String dn)
  2473.  
  2474.    Constructs with the specified host, port, and DN. This form is used
  2475.    to create URL references to a particular object in the directory.
  2476.  
  2477.  
  2478.    public LDAPUrl(String host,
  2479.                   int port,
  2480.                   String dn,
  2481.                   String attrNames[],
  2482.                   int scope,
  2483.                   String filter)
  2484.  
  2485.    Constructs a full-blown LDAP URL to specify an LDAP search operation.
  2486.  
  2487.    Parameters are:
  2488.  
  2489.    url             An explicit URL string, e.g.
  2490.                    "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn,sn?sub?
  2491.                    (objectclass=inetOrgPerson)".
  2492.  
  2493.    host            Host name of LDAP server, or null for "nearest
  2494.                    X.500/LDAP".
  2495.  
  2496.    port            Port number for LDAP server (use
  2497.                    LDAPConnection.DEFAULT_PORT for default port).
  2498.  
  2499.    dn              Distinguished name of object to fetch.
  2500.  
  2501.    attrNames       Names of attributes to retrieve. null for all attri-
  2502.                    butes.
  2503.  
  2504.    scope           Depth of search (in DN namespace). Use one of
  2505.                    SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPv2.
  2506.  
  2507.  
  2508. 5.19.2.  decode
  2509.  
  2510.    public static String decode(String URLEncoded) throws MalformedURLEx-
  2511.    ception
  2512.  
  2513.    Decodes a URL-encoded string. Any occurences of %HH are decoded to
  2514.    the hex value represented. However, this routine does NOT decode "+"
  2515.  
  2516.  
  2517.  
  2518. Expires 3/98                                                   [Page 42]
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524. JAVA LDAP API                                             September 1997
  2525.  
  2526.  
  2527.    into " ". See [10] for details on URL encoding/decoding.
  2528.  
  2529.    Parameters are:
  2530.  
  2531.    URLEncoded      String to decode.
  2532.  
  2533.  
  2534. 5.19.3.  encode
  2535.  
  2536.    public static String encode(String toEncode)
  2537.  
  2538.    Encodes an arbitrary string. Any illegal characters are encoded as
  2539.    %HH.  However, this routine does NOT encode " " into "+".
  2540.  
  2541.    Parameters are:
  2542.  
  2543.    toEncode        String to encode.
  2544.  
  2545.  
  2546. 5.19.4.  getAttributes
  2547.  
  2548.    public String[] getAttributeArray()
  2549.  
  2550.    Return an array of attribute names specified in the URL
  2551.  
  2552.  
  2553. 5.19.5.  getAttributes
  2554.  
  2555.    public Enumeration getAttributes()
  2556.  
  2557.    Return an Enumerator for the attribute names specified in the URL
  2558.  
  2559.  
  2560. 5.19.6.  getDN
  2561.  
  2562.    public String getDN()
  2563.  
  2564.    Return the distinguished name encapsulated in the URL.
  2565.  
  2566.  
  2567. 5.19.7.  getFilter
  2568.  
  2569.    public String getFilter()
  2570.  
  2571.    Returns the search filter [8], or the default filter -
  2572.    (objectclass=*) - if none was specified.
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578. Expires 3/98                                                   [Page 43]
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584. JAVA LDAP API                                             September 1997
  2585.  
  2586.  
  2587. 5.19.8.  getHost
  2588.  
  2589.    public String getHost()
  2590.  
  2591.    Returns the host name of the LDAP server to connect to.
  2592.  
  2593. 5.19.9.  getPort
  2594.  
  2595.    public int getPort()
  2596.  
  2597.    Returns the port number of the LDAP server to connect to.
  2598.  
  2599.  
  2600. 5.19.10.  getUrl
  2601.  
  2602.    public String getUrl()
  2603.  
  2604.    Returns a valid string representation of this LDAP URL.
  2605.  
  2606.  
  2607. 5.20.  public interface LDAPv2
  2608.  
  2609. As a mechanism to support planned and future LDAP protocol extensions,
  2610. functionality is defined in an interface - LDAPv2, corresponding to ver-
  2611. sion 2 of the LDAP protocol. LDAPConnection must implement at least
  2612. LDAPv2, and may implement LDAPv3.  Applications can test for support of
  2613. these protocol levels in a given package with the instanceof operator.
  2614.  
  2615. 5.20.1.  add
  2616.  
  2617.    public void add(LDAPEntry entry) throws LDAPException
  2618.  
  2619.    Adds an entry to the directory.
  2620.  
  2621.    Parameters are:
  2622.  
  2623.    entry           LDAPEntry object specifying the distinguished name
  2624.                    and attributes of the new entry.
  2625.  
  2626.  
  2627. 5.20.2.  authenticate
  2628.  
  2629.    public void authenticate(String dn,
  2630.                             String passwd)
  2631.                             throws LDAPException
  2632.  
  2633.    Authenticates to the LDAP server (that the object is currently con-
  2634.    nected to) using the specified name and password.  If the object has
  2635.  
  2636.  
  2637.  
  2638. Expires 3/98                                                   [Page 44]
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644. JAVA LDAP API                                             September 1997
  2645.  
  2646.  
  2647.    been disconnected from an LDAP server, this method attempts to recon-
  2648.    nect to the server. If the object had already authenticated, the old
  2649.    authentication is discarded.
  2650.  
  2651.    Parameters are:
  2652.  
  2653.    dn              If non-null and non-empty, specifies that the connec-
  2654.                    tion and all operations through it should be authen-
  2655.                    ticated with dn as the distinguished name.
  2656.  
  2657.    passwd          If non-null and non-empty, specifies that the connec-
  2658.                    tion and all operations through it should be authen-
  2659.                    ticated with dn as the distinguished name and passwd
  2660.                    as password.
  2661.  
  2662.  
  2663. 5.20.3.  compare
  2664.  
  2665.    public boolean compare(String dn,
  2666.                           LDAPAttribute attr)
  2667.                           throws LDAPException
  2668.  
  2669.    Checks to see if an entry contains an attribute with a specified
  2670.    value.  Returns true if the entry has the value, and false if the
  2671.    entry does not have the value or the attribute.
  2672.  
  2673.    Parameters are:
  2674.  
  2675.    dn              The distinguished name of the entry to use in the
  2676.                    comparison.
  2677.  
  2678.    attr            The attribute to compare against the entry. The
  2679.                    method checks to see if the entry has an attribute
  2680.                    with the same name and value as this attribute.
  2681.  
  2682.  
  2683. 5.20.4.  connect
  2684.  
  2685.    public void connect(String host,
  2686.                        int port)
  2687.                        throws LDAPException
  2688.  
  2689.    Connects to the specified host and port. If this LDAPConnection
  2690.    object represents an open connection, the connection is closed first
  2691.    before the new connection is opened.  At this point there is no
  2692.    authentication, and any operations will be conducted as an anonymous
  2693.    client.
  2694.  
  2695.  
  2696.  
  2697.  
  2698. Expires 3/98                                                   [Page 45]
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704. JAVA LDAP API                                             September 1997
  2705.  
  2706.  
  2707.    public void connect(String host,
  2708.                        int port,
  2709.                        String dn,
  2710.                        String passwd)
  2711.                        throws LDAPException
  2712.  
  2713.    Connects to the specified host and port and uses the specified DN and
  2714.    password to authenticate to the server. If this LDAPConnection object
  2715.    represents an open connection, the connection is closed first before
  2716.    the new connection is opened. This is equivalent to connect(host,
  2717.    port) followed by authenticate(dn, passwd).
  2718.  
  2719.    Parameters are:
  2720.  
  2721.    host            Contains a hostname or dotted string representing the
  2722.                    IP address of a host running an LDAP server to con-
  2723.                    nect to. Alternatively, it may contain a list of host
  2724.                    names, space-delimited.  Each host name may include a
  2725.                    trailing colon and port number.  In the case where
  2726.                    more than one host name is specified, each host name
  2727.                    in turn will be contacted until a connection can be
  2728.                    established. Examples:
  2729.  
  2730.       "directory.knowledge.com"
  2731.       "199.254.1.2"
  2732.       "directory.knowledge.com:1050 people.catalog.com 199.254.1.2"
  2733.  
  2734.    port            Contains the TCP or UDP port number to connect to or
  2735.                    contact. The default LDAP port is 389. "port" is
  2736.                    ignored for any host name which includes a colon and
  2737.                    port number.
  2738.  
  2739.    dn              If non-null and non-empty, specifies that the connec-
  2740.                    tion and all operations through it should be authen-
  2741.                    ticated with dn as the distinguished name.
  2742.  
  2743.    passwd          If non-null and non-empty, specifies that the connec-
  2744.                    tion and all operations through it should be authen-
  2745.                    ticated with dn as the distinguished name and passwd
  2746.                    as password.
  2747.  
  2748.  
  2749. 5.20.5.  delete
  2750.  
  2751.    public void delete(String dn) throws LDAPException
  2752.  
  2753.    Deletes the entry for the specified DN from the directory.
  2754.  
  2755.  
  2756.  
  2757.  
  2758. Expires 3/98                                                   [Page 46]
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764. JAVA LDAP API                                             September 1997
  2765.  
  2766.  
  2767.    Parameters are:
  2768.  
  2769.    dn              Distinguished name of the entry to modify.
  2770.  
  2771.  
  2772. 5.20.6.  disconnect
  2773.  
  2774.    public synchronized void disconnect() throws LDAPException
  2775.  
  2776.    Disconnects from the LDAP server. Before the object can perform LDAP
  2777.    operations again, it must reconnect to the server by calling connect.
  2778.  
  2779.  
  2780. 5.20.7.  getOption
  2781.  
  2782.    public Object getOption(int option) throws LDAPException
  2783.  
  2784.    Returns the value of the specified option for this object.
  2785.  
  2786.    Parameters are:
  2787.  
  2788.  
  2789.    option          See LDAPConnection.setOption for a description of
  2790.                    valid options.
  2791.  
  2792.  
  2793. 5.20.8.  modify
  2794.  
  2795.    public void modify(String dn,
  2796.                       LDAPModification mod)
  2797.                       throws LDAPException
  2798.  
  2799.    Makes a single change to an existing entry in the directory (for
  2800.    example, changes the value of an attribute, adds a new attribute
  2801.    value, or removes an existing attribute value).
  2802.  
  2803.    The LDAPModification object specifies both the change to be made and
  2804.    the LDAPAttribute value to be changed.
  2805.  
  2806.  
  2807.    public void modify(String dn,
  2808.                       LDAPModificationSet mods)
  2809.                       throws LDAPException
  2810.  
  2811.    Makes a set of changes to an existing entry in the directory (for
  2812.    example, changes attribute values, adds new attribute values, or
  2813.    removes existing attribute values).
  2814.  
  2815.  
  2816.  
  2817.  
  2818. Expires 3/98                                                   [Page 47]
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824. JAVA LDAP API                                             September 1997
  2825.  
  2826.  
  2827.    Parameters are:
  2828.  
  2829.    dn              Distinguished name of the entry to modify.
  2830.  
  2831.    mod             A single change to be made to the entry.
  2832.  
  2833.    mods            A set of changes to be made to the entry.
  2834.  
  2835.  
  2836. 5.20.9.  read
  2837.  
  2838.    public LDAPEntry read(String dn) throws LDAPException
  2839.  
  2840.    Reads the entry for the specified distiguished name (DN) and
  2841.    retrieves all attributes for the entry.
  2842.  
  2843.  
  2844.    public LDAPEntry read(String dn,
  2845.                          String attrs[])
  2846.                          throws LDAPException
  2847.  
  2848.    Reads the entry for the specified distinguished name (DN) and
  2849.    retrieves only the specified attributes from the entry.
  2850.  
  2851.    Parameters are:
  2852.  
  2853.    dn              Distinguished name of the entry to retrieve.
  2854.  
  2855.    attrs           Names of attributes to retrieve.
  2856.  
  2857.  
  2858. 5.20.10.  rename
  2859.  
  2860.    public void rename(String dn,
  2861.                       String newRdn,
  2862.                       boolean deleteOldRdn)
  2863.                       throws LDAPException
  2864.  
  2865.    Renames an existing entry in the directory.
  2866.  
  2867.    Parameters are:
  2868.  
  2869.    dn              Current distinguished name of the entry.
  2870.  
  2871.    newRdn          New relative distinguished name for the entry.
  2872.  
  2873.    deleteOldRdn    If true, the old name is not retained as an attribute
  2874.                    value.
  2875.  
  2876.  
  2877.  
  2878. Expires 3/98                                                   [Page 48]
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884. JAVA LDAP API                                             September 1997
  2885.  
  2886.  
  2887. 5.20.11.  search
  2888.  
  2889.    public LDAPSearchResults search(String base,
  2890.                                    int scope,
  2891.                                    String filter,
  2892.                                    String attrs[],
  2893.                                    boolean attrsOnly)
  2894.                                    throws LDAPException
  2895.  
  2896.    Performs the search specified by the parameters.
  2897.  
  2898.  
  2899.    public LDAPSearchResults search(String base,
  2900.                                    int scope,
  2901.                                    String filter,
  2902.                                    String attrs[],
  2903.                                    boolean attrsOnly,
  2904.                                    LDAPSearchConstraints cons)
  2905.                                    throws LDAPException
  2906.  
  2907.    Performs the search specified by the parameters, also allowing
  2908.    specification of constraints for the search (such as the maximum
  2909.    number of entries to find or the maximum time to wait for search
  2910.    results).
  2911.  
  2912.    As part of the search constraints, the function allows specifying
  2913.    whether or not the results are to be delivered all at once or in
  2914.    smaller batches. If specified that the results are to be delivered in
  2915.    smaller batches, each iteration blocks only until the next batch of
  2916.    results is returned.
  2917.  
  2918.    Parameters are:
  2919.  
  2920.    base            The base distinguished name to search from.
  2921.  
  2922.    scope           The scope of the entries to search. The following are
  2923.                    the valid options:
  2924.  
  2925.  
  2926.                    LDAPv2.SCOPE_BASE Search only the base DN
  2927.  
  2928.                    LDAPv2.SCOPE_ONE  Search only entries under the base
  2929.                                      DN
  2930.  
  2931.                    LDAPv2.SCOPE_SUB  Search the base DN and all entries
  2932.                                      within its subtree
  2933.  
  2934.    filter          Search filter specifying the search criteria, as
  2935.  
  2936.  
  2937.  
  2938. Expires 3/98                                                   [Page 49]
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944. JAVA LDAP API                                             September 1997
  2945.  
  2946.  
  2947.                    defined in [3].
  2948.  
  2949.    attrs           Names of attributes to retrieve.
  2950.  
  2951.    attrsOnly       If true, returns the names but not the values of the
  2952.                    attributes found.  If false, returns the names and
  2953.                    values for attributes found
  2954.  
  2955.    cons            Constraints specific to the search.
  2956.  
  2957.  
  2958. 5.20.12.  setOption
  2959.  
  2960.    public void setOption(int option,
  2961.                          Object value)
  2962.                          throws LDAPException
  2963.  
  2964.    Sets the value of the specified option for this LDAPConnection
  2965.    object.
  2966.  
  2967.    See LDAPConnection.setOption for an implementation.
  2968.  
  2969.  
  2970. 5.21.  public interface LDAPv3 extends LDAPv2
  2971.  
  2972. LDAPv3 extends LDAPv2 by adding support for features of version 3 of the
  2973. LDAP protocol. LDAPConnection implements at least LDAPv2, and may also
  2974. implement LDAPv3. Applications can test for support of these protocol
  2975. levels in a given package with the instanceof operator.
  2976.  
  2977. 5.21.1.  Preferred Language
  2978.  
  2979. A preferred language, specified as in [14], can be set using setOption.
  2980. A Preferred Language Server Control is constructed and sent to the
  2981. server with all operations. If the server supports the control, results
  2982. returned on search() or read() will be filtered using the control, as
  2983. per [15], e.g.
  2984.  
  2985.       ld.setOption( LDAPv3.PREFERRED_LANGUAGE, "lang-en" );
  2986.  
  2987.  
  2988. 5.21.2.  authenticate
  2989.  
  2990.    public void authenticate(int version,
  2991.                             String dn,
  2992.                             String passwd)
  2993.                             throws LDAPException
  2994.  
  2995.  
  2996.  
  2997.  
  2998. Expires 3/98                                                   [Page 50]
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004. JAVA LDAP API                                             September 1997
  3005.  
  3006.  
  3007.    Authenticates to the LDAP server (that the object is currently con-
  3008.    nected to) using the specified name and password, with the specified
  3009.    LDAP protocol version. If the server does not support the requested
  3010.    protocol version, an exception is thrown.  If the object has been
  3011.    disconnected from an LDAP server, this method attempts to reconnect
  3012.    to the server. If the object had already authenticated, the old
  3013.    authentication is discarded.
  3014.  
  3015.    Parameters are:
  3016.  
  3017.    version         LDAP protocol version requested: currently 2 or 3.
  3018.  
  3019.    dn              If non-null and non-empty, specifies that the connec-
  3020.                    tion and all operations through it should be authen-
  3021.                    ticated with dn as the distinguished name.
  3022.  
  3023.    passwd          If non-null and non-empty, specifies that the connec-
  3024.                    tion and all operations through it should be authen-
  3025.                    ticated with dn as the distinguished name and passwd
  3026.                    as password.
  3027.  
  3028.  
  3029. 5.21.3.  authenticate
  3030.  
  3031.    public void authenticate(String dn,
  3032.                             byte[] credentials,
  3033.                             String[] mechanisms,
  3034.                             Properties props,
  3035.                             SaslAuthenticationCallback authCb)
  3036.                             throws LDAPException
  3037.  
  3038.    Authenticates to the LDAP server using SASL authentication mechan-
  3039.    isms. Mechanisms will be tried in the order provided.  If a mechanism
  3040.    requires additional information (e.g.  credentials) to procede, and
  3041.    authCb is not null, authCb's request() method will be called. An
  3042.    LDAPException is thrown if authentication fails for all specified
  3043.    mechanisms.
  3044.  
  3045.    Parameters are:
  3046.  
  3047.    dn              Distinguished name to authenticate as
  3048.  
  3049.    credentials     Initial credentials to use on first authentication
  3050.                    request. The contents are specific to a SASL mechan-
  3051.                    ism.
  3052.  
  3053.    props           Properties to be used for authentication. Some are
  3054.                    only meaningful to a subset of all SASL mechanisms.
  3055.  
  3056.  
  3057.  
  3058. Expires 3/98                                                   [Page 51]
  3059.  
  3060.  
  3061.  
  3062.  
  3063.  
  3064. JAVA LDAP API                                             September 1997
  3065.  
  3066.  
  3067.                    The following is a partial list of properties and
  3068.                    sample values:
  3069.  
  3070.       security.userid                         "default"
  3071.  
  3072.       security.policy.encryption              "true"
  3073.  
  3074.       security.policy.sign_without_encryption "false"
  3075.  
  3076.       security.policy.no_encryption           "false"
  3077.  
  3078.       security.policy.encryption.minimum      "40"
  3079.  
  3080.       security.policy.encryption.maximum      "128"
  3081.  
  3082.       security.policy.server_authentication   "true"
  3083.  
  3084.       security.server.fqdn                    "safe.mcom.com"
  3085.  
  3086.       security.maxbuffer                      "4096"
  3087.  
  3088.       security.ip.local                       "192.68.1.10"
  3089.  
  3090.       security.ip.remote                      "192.68.1.50"
  3091.  
  3092.  
  3093. authCb          An object implementing the SaslAuthenticationCallback
  3094.                 interface, capable of returning additional information
  3095.                 to a SASL mechanism driver if necessary. This may or may
  3096.                 not involve interactively prompting the user for this
  3097.                 information. The parameter may be null, indicating that
  3098.                 the application will not provide additional information.
  3099.  
  3100.  
  3101. 5.21.4.  extendedOperation
  3102.  
  3103.    public LDAPExtendedOperation extendedOperation(
  3104.                                    LDAPExtendedOperation op )
  3105.                                    throws LDAPException
  3106.  
  3107.    Provides a means to access extended, non-mandatory operations offered
  3108.    by a particular LDAP version 3 compliant server.
  3109.  
  3110.    Returns an operation-specific object, containing an ID and an Octet
  3111.    String or BER-encoded value(s).
  3112.  
  3113.    Parameters are:
  3114.  
  3115.  
  3116.  
  3117.  
  3118. Expires 3/98                                                   [Page 52]
  3119.  
  3120.  
  3121.  
  3122.  
  3123.  
  3124. JAVA LDAP API                                             September 1997
  3125.  
  3126.  
  3127.    op              Object which contains an identifier of the extended
  3128.                    operation, which should be one recognized by the par-
  3129.                    ticular server this client is connected to, and an
  3130.                    operation-specific sequence of Octet String or BER-
  3131.                    encoded value(s).
  3132.  
  3133.  
  3134. 5.21.5.  getResponseControls
  3135.  
  3136.    public LDAPControl[] getResponseControls()
  3137.  
  3138.    Returns the latest Server Controls returned by a Directory Server
  3139.    with a response to an LDAP request from the current thread, or null
  3140.    if the latest response contained no Server Controls.
  3141.  
  3142.  
  3143. 5.21.6.  rename
  3144.  
  3145.    public void rename(String dn,
  3146.                       String newRdn,
  3147.                       String newParentdn,
  3148.                       boolean deleteOldRdn)
  3149.                       throws LDAPException
  3150.  
  3151.    Renames an existing entry in the directory, possibly repositioning it
  3152.    in the directory tree.
  3153.  
  3154.    Parameters are:
  3155.  
  3156.    dn              Current distinguished name of the entry.
  3157.  
  3158.    newRdn          New relative distinguished name for the entry.
  3159.  
  3160.    newParentdn     Distinguished name of the existing entry which is to
  3161.                    be the new parent of the entry.
  3162.  
  3163.    deleteOldRdn    If true, the old name is not retained as an attribute
  3164.                    value.
  3165.  
  3166.  
  3167. 5.22.  public interface SaslAuthenticationCallback
  3168.  
  3169. Note: this interface is not part of the LDAP classes. It is presented
  3170. here to clarify use of SASL mechanisms in authentication using the LDAP
  3171. classes.
  3172.  
  3173. An application may implement this interface to allow a SASL mechanism
  3174. driver to obtain additional information (e.g. credentials) as needed
  3175.  
  3176.  
  3177.  
  3178. Expires 3/98                                                   [Page 53]
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184. JAVA LDAP API                                             September 1997
  3185.  
  3186.  
  3187. during authentication. The implementation may or may not include
  3188. interactively prompting a user.
  3189.  
  3190. 5.22.1.  request
  3191.  
  3192.    public byte[] request(String prompt,
  3193.                          String type)
  3194.                          throws SaslException
  3195.  
  3196.    Parameters are:
  3197.  
  3198.    prompt          A prompt that may be presented to a user as a guide
  3199.                    to entering the requested information, or may be used
  3200.                    as a key to forming the user interface for requesting
  3201.                    the information, or may be ignored.
  3202.  
  3203.    type            An identifier of type of information requested by the
  3204.                    SASL mechanism driver, e.g. "password".
  3205.  
  3206.  
  3207. 5.23.  Client and Server Controls
  3208.  
  3209. LDAPv3 operations can be extended through the use of controls. Controls
  3210. may be sent to a server or returned to the client with any LDAP message.
  3211. These controls are referred to as server controls. The LDAP API also
  3212. supports a client-side extension mechanism through the use of client
  3213. controls (these controls affect the behavior of the LDAP API only and
  3214. are never sent to a server). A common class is used to represent both
  3215. types of controls - LDAPControl.
  3216.  
  3217. Controls are set and retrieved in LDAPConnection with the setOption and
  3218. getOption methods, using the keys LDAPv3.SERVERCONTROLS and
  3219. LDAPv3.CLIENTCONTROLS.  Either a single LDAPControl or an array may be
  3220. passed, e.g.
  3221.  
  3222.       LDAPControl control = new LDAPControl( type, critical, vals );
  3223.       ld.setOption( LDAPv3.SERVERCONTROLS, control );
  3224.    or
  3225.       LDAPControl[] controls = new LDAPControl[2];
  3226.       controls[0] = new LDAPControl( type0, critical0, vals0 );
  3227.       controls[1] = new LDAPControl( type1, critical1, vals1 );
  3228.       ld.setOption( LDAPv3.SERVERCONTROLS, controls );
  3229.  
  3230. Server controls returned to a client as part of the response to an
  3231. operation can be obtained with LDAPv3.getResponseControls().
  3232.  
  3233. Support for specific controls is defined in a package "controls" subor-
  3234. dinate to the main LDAP package.
  3235.  
  3236.  
  3237.  
  3238. Expires 3/98                                                   [Page 54]
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244. JAVA LDAP API                                             September 1997
  3245.  
  3246.  
  3247. 6.  Security Considerations
  3248.  
  3249. LDAP supports security through protocol-level authentication, using
  3250. clear-text passwords or other more secure mechanisms.  It also supports
  3251. running over TLS, which provides strong security at the transport layer.
  3252. This draft does not cover TLS implementations, although it identifies a
  3253. mechanism for supplying one, through the LDAPSocketFactory interface. An
  3254. interface is defined for using protocol-independent SASL mechanism
  3255. drivers for authentication.
  3256.  
  3257. 7.  Acknowledgements
  3258.  
  3259. The proposed API builds on earlier work done in collaboration with Tho-
  3260. mas Kwan and Stephan Gudmundson, then of of NCware Technologies Corp.
  3261.  
  3262. 8.  Bibliography
  3263.  
  3264. [1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
  3265.      X.520.
  3266.  
  3267. [2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
  3268.      Access Protocol: Standard and Pilot Attribute Definitions", Inter-
  3269.      net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996
  3270.  
  3271. [3]  T. Howes, "A String Representation of LDAP Search Filters," RFC
  3272.      1960, June 1996.
  3273.  
  3274. [4]  S. Kille, "A String Representation of Distinguished Names," RFC
  3275.      1779, March 1995.
  3276.  
  3277. [5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
  3278.      ing," RFC 1781, March 1995.
  3279.  
  3280. [7]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
  3281.      (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt, March
  3282.      1997.
  3283.  
  3284. [8]  T. Howes, M. Smith, "An LDAP URL Format", RFC 1959, June 1996.
  3285.  
  3286. [9]  T. Howes, M. Smith, "The LDAP Application Program Interface", RFC
  3287.      1823, August 1995.
  3288.  
  3289. [10] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource Loca-
  3290.      tors (URL)", RFC 1738, December 1994.
  3291.  
  3292. [11] W. Yeong, T. Howes, S. Kille, "Lightweight Directory Access Proto-
  3293.      col", RFC 1777, March 1995.
  3294.  
  3295.  
  3296.  
  3297.  
  3298. Expires 3/98                                                   [Page 55]
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304. JAVA LDAP API                                             September 1997
  3305.  
  3306.  
  3307. [12] R. Weltman, "The Java LDAP Application Program Interface", Internet
  3308.      Draft draft-weltman-java-ldap-01.txt, April 1997.
  3309.  
  3310. [13] R. Weltman, T. Howes, M. Smith, "The Java LDAP Application Program
  3311.      Interface", Internet Draft draft-ietf-asid-ldap-java-api-00.txt,
  3312.      July 1997.
  3313.  
  3314. [14] H. Alvestrans, "Tags for the Identification of Languages", Request
  3315.      for Comments 1766, March 1995.
  3316.  
  3317. [15] M. Wahl, T. Howes, "Use of Language Codes in LDAPv3", Internet
  3318.      Draft draft-ietf-asid-ldapv3-lang-02.txt, June 1997.
  3319.  
  3320. 9.  Authors' Addresses
  3321.  
  3322.    Rob Weltman
  3323.    Netscape Communications Corp.
  3324.    501 E. Middlefield Rd.
  3325.    Mountain View, CA 94043
  3326.    USA
  3327.    +1 650 937-3301
  3328.    rweltman@netscape.com
  3329.  
  3330.    Tim Howes
  3331.    Netscape Communications Corp.
  3332.    501 E. Middlefield Rd.
  3333.    Mountain View, CA 94043
  3334.    USA
  3335.    +1 650 937-3419
  3336.    howes@netscape.com
  3337.  
  3338.    Mark Smith
  3339.    Netscape Communications Corp.
  3340.    501 E. Middlefield Rd.
  3341.    Mountain View, CA 94043
  3342.    USA
  3343.    +1 650 937-3477
  3344.    mcs@netscape.com
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358. Expires 3/98                                                   [Page 56]
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364. JAVA LDAP API                                             September 1997
  3365.  
  3366.  
  3367. 10.  Appendix A - Sample java LDAP programs
  3368.  
  3369.    import netscape.ldap.*;
  3370.    import java.util.*;
  3371.  
  3372.    public class SearchJensen {
  3373.        public static void main( String[] args )
  3374.        {
  3375.            try {
  3376.                LDAPConnection ld = new LDAPConnection();
  3377.                /* Connect to server */
  3378.                String MY_HOST = "localhost";
  3379.                int MY_PORT = 389;
  3380.                ld.connect( MY_HOST, MY_PORT );
  3381.  
  3382.                /* authenticate to the directory as nobody */
  3383.                /* This is not really necessary if explicit authentication
  3384.                   is not desired, because there is already anonymous
  3385.                   authentication at connect time */
  3386.                ld.authenticate( "", "" );
  3387.  
  3388.                /* search for all entries with surname of Jensen */
  3389.                String MY_FILTER = "sn=Jensen";
  3390.                String MY_SEARCHBASE = "o=Ace Industry, c=US";
  3391.  
  3392.                LDAPSearchConstraints cons = ld.getSearchConstraints();
  3393.                /* Setting the batchSize to one will cause the result
  3394.                   enumeration below to block on one result at a time,
  3395.                   allowing us to update a list or do other things as
  3396.                   results come in. */
  3397.                /* We could set it to 0 if we just wanted to get all
  3398.                   results and were willing to block until then */
  3399.                cons.setBatchSize( 1 );
  3400.                LDAPSearchResults res = ld.search( MY_SEARCHBASE,
  3401.                                                    LDAPConnection.SCOPE_ONE,
  3402.                                                    MY_FILTER,
  3403.                                                    null,
  3404.                                                    false,
  3405.                                                    cons );
  3406.  
  3407.                /* Loop on results until finished */
  3408.                while ( res.hasMoreElements() ) {
  3409.  
  3410.                    /* Next directory entry */
  3411.                    LDAPEntry findEntry = (LDAPEntry)res.nextElement();
  3412.                    System.out.println( findEntry.getDN() );
  3413.  
  3414.                    /* Get the attributes of the entry */
  3415.  
  3416.  
  3417.  
  3418. Expires 3/98                                                   [Page 57]
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424. JAVA LDAP API                                             September 1997
  3425.  
  3426.  
  3427.                    LDAPAttributeSet findAttrs = findEntry.getAttributeSet();
  3428.                    Enumeration enumAttrs = findAttrs.getAttributes();
  3429.                    System.out.println( "Attributes: " );
  3430.                    /* Loop on attributes */
  3431.                    while ( enumAttrs.hasMoreElements() ) {
  3432.                        LDAPAttribute anAttr =
  3433.                            (LDAPAttribute)enumAttrs.nextElement();
  3434.                        String attrName = anAttr.getName();
  3435.                        System.out.println( "" + attrName );
  3436.                        /* Loop on values for this attribute */
  3437.                        Enumeration enumVals = anAttr.getStringValues();
  3438.                        while ( enumVals.hasMoreElements() ) {
  3439.                            String aVal = ( String )enumVals.nextElement();
  3440.                            System.out.println( "" + aVal );
  3441.                        }
  3442.                    }
  3443.                }
  3444.            }
  3445.            catch( LDAPException e ) {
  3446.                System.out.println( "Error: " + e.toString() );
  3447.            }
  3448.            /* Done, so disconnect */
  3449.            if ( ld.isConnected() )
  3450.                ld.disconnect();
  3451.        }
  3452.    }
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478. Expires 3/98                                                   [Page 58]
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484. JAVA LDAP API                                             September 1997
  3485.  
  3486.  
  3487.    import netscape.ldap.*;
  3488.    import java.util.*;
  3489.  
  3490.    public class ModifyEmail {
  3491.        public static void main( String[] args )
  3492.        {
  3493.            try {
  3494.                LDAPConnection ld = new LDAPConnection();
  3495.                /* Connect to server */
  3496.                String MY_HOST = "localhost";
  3497.                int MY_PORT = 389;
  3498.                ld.connect( MY_HOST, MY_PORT );
  3499.  
  3500.                /* authenticate to the directory as Bab Jensen */
  3501.                String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US";
  3502.                String MY_PASSWORD = "MysteryLady";
  3503.                ld.authenticate( MY_NAME, MY_PASSWORD );
  3504.  
  3505.                /* Prepare to change my email address */
  3506.                LDAPAttribute attrEmail =
  3507.                        new LDAPAttribute( "mail", "babs@ace.com" );
  3508.                LDAPModification mod =
  3509.                        new LDAPModification( LDAPModification.REPLACE,
  3510.                                              attrEmail );
  3511.  
  3512.                /* Now modify the entry in the directory */
  3513.                ld.modify( MY_NAME, mod );
  3514.                System.out.println( "Entry modified"  );
  3515.  
  3516.            }
  3517.            catch( LDAPException e ) {
  3518.                System.out.println( "Error: " + e.toString() );
  3519.            }
  3520.            /* Done, so disconnect */
  3521.            if ( ld.isConnected() )
  3522.                ld.disconnect();
  3523.        }
  3524.    }
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538. Expires 3/98                                                   [Page 59]
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544. JAVA LDAP API                                             September 1997
  3545.  
  3546.  
  3547. 11.  Appendix B - Changes from draft-ietf-asid-ldap-java-api-00.txt
  3548.  
  3549.  
  3550. 11.1.  LDAPConnection
  3551.  
  3552. The method setProperty() throws an LDAPException if the specified pro-
  3553. perty is not supported.
  3554.  
  3555. 11.2.  Controls
  3556.  
  3557. A section was added with support for currently defined LDAP controls.
  3558.  
  3559. 11.3.  LDAPException
  3560.  
  3561. Constructors LDAPException(String) and LDAPException(String,int,String)
  3562. were removed, and the constructor LDAPException(String,int) was added.
  3563. The description stating that the resultCode is no longer valid was
  3564. removed.
  3565.  
  3566. 11.4.  LDAPSearchResults
  3567.  
  3568. The method next() throws an LDAPReferralException if automatic referral
  3569. following is not enabled.
  3570.  
  3571. The getBaseAttribute() method was removed.
  3572.  
  3573. The getAttribute(attrName) method was redefined to return only an exact
  3574. match, and a new method getAttribute(attrName, lang) was added to pro-
  3575. vide language-sensitive best-match functionality. Neither method throws
  3576. an exception.
  3577.  
  3578. 11.5.  LDAPSecurityException
  3579.  
  3580. The class was removed.
  3581.  
  3582. 11.6.  LDAPSortKey
  3583.  
  3584. The class was added, to support server-side sorting.
  3585.  
  3586. 11.7.  LDAPv3
  3587.  
  3588. The PREFERRED_LANGUAGE option was added to setOption().
  3589.  
  3590. 11.8.  Examples
  3591.  
  3592. The disconnect() was moved to after the exception catcher.  An example
  3593. of using paged sort controls was added.
  3594.  
  3595.  
  3596.  
  3597.  
  3598. Expires 3/98                                                   [Page 60]
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604. JAVA LDAP API                                             September 1997
  3605.  
  3606.  
  3607. 12.  Appendix C - Changes from draft-weltman-java-ldap-00.txt
  3608.  
  3609.  
  3610. 12.1.  LDAPv3
  3611.  
  3612. This interface is new. It adds support for features of LDAP protocol
  3613. version 3.
  3614.  
  3615. 12.2.  SSL -> TLS
  3616.  
  3617. References to the Secure Socket Layer (SSL) have been replaced with
  3618. references to Transport Layer Security (TLS).
  3619.  
  3620. 12.3.  LDAPAttributeSet
  3621.  
  3622. Methods getAttribute(String name) and getBaseAttribute(String name) were
  3623. added.
  3624.  
  3625. 12.4.  LDAPCompareAttrNames
  3626.  
  3627. Constructors were added to allow specifying sorting in descending, and
  3628. not just ascending, order.
  3629.  
  3630. 12.5.  LDAPCompareAttrNames
  3631.  
  3632. Constructors were added to allow specifying sorting in descending, and
  3633. not just ascending, order.
  3634.  
  3635. 12.6.  LDAPControl
  3636.  
  3637. This is a new class to support the LDAPv3 protocol extension, where
  3638. Server or Client Controls may be specified for LDAP operations.
  3639.  
  3640. 12.7.  LDAPEntry
  3641.  
  3642. Methods getAttribute(String name) and getBaseAttribute(String name) were
  3643. added.
  3644.  
  3645. 12.8.  LDAPException
  3646.  
  3647. The method getMatchedDN was added.
  3648.  
  3649. 12.9.  LDAPExtendedOperation
  3650.  
  3651. New class to pass extended operations back and forth to/from the server,
  3652. for LDAPv3.
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658. Expires 3/98                                                   [Page 61]
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664. JAVA LDAP API                                             September 1997
  3665.  
  3666.  
  3667. 12.10.  LDAPv2
  3668.  
  3669. For connect(), the "host" parameter may be a space-delimited list of
  3670. hosts to attempt to connect to. Each one may have a colon and a port
  3671. number attached.
  3672.  
  3673. 12.11.  Dereferencing aliases
  3674.  
  3675. LDAPConnection.setOption(), the LDAPSearchConstraints constructor,
  3676. LDAPSearchConstraints.getDereference(), and
  3677. LDAPSearchConstraints.setDereference() were changed so that the option
  3678. specifying how to dereference aliases is now an integer instead of a
  3679. boolean, and the legal values are declared.
  3680.  
  3681. 12.12.  Default referral hop limit
  3682.  
  3683. The default referral hop limit in LDAPConnection.setOption() was changed
  3684. from 5 to 10.
  3685.  
  3686. 12.13.  Examples
  3687.  
  3688. An example of how to modify an existing Directory entry was added to
  3689. appendix A.
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.  
  3718. Expires 3/98                                                   [Page 62]
  3719.  
  3720.  
  3721.  
  3722.  
  3723.  
  3724. JAVA LDAP API                                             September 1997
  3725.  
  3726.  
  3727. 13.  Appendix D - Outstanding issues
  3728.  
  3729.  
  3730. 13.1.  Support for SASL authentication
  3731.  
  3732. The framework suggested in the LDAPv3 interface for SASL authentication
  3733. is tentative. It will need to be extended to and integrated into the
  3734. automatic referral-processing architecture, so that an LDAPRebindProc
  3735. can initiate new authentication procedures with servers that are
  3736. referred to by a search. The current specification only allows for sim-
  3737. ple authentication on automatic referral following.
  3738.  
  3739. If referrals are handled explicitly rather than automatically, by catch-
  3740. ing LDAPReferralException, the caller may use the LDAPv3 SASL framework.
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.  
  3777.  
  3778. Expires 3/98                                                   [Page 63]
  3779.  
  3780.  
  3781.  
  3782.  
  3783.  
  3784. 1.     Introduction...................................................1
  3785. 2.     Overview of the LDAP model.....................................2
  3786. 3.     Overview of the LDAP classes...................................3
  3787. 3.1.      Interfaces..................................................3
  3788. 3.2.      Classes.....................................................4
  3789. 3.3.      Exceptions..................................................5
  3790. 4.     Overview of LDAP API use.......................................6
  3791. 5.     The java LDAP classes..........................................6
  3792. 5.1.     LDAPAttribute................................................6
  3793. 5.1.1.       Constructors.............................................6
  3794. 5.1.2.       addValue.................................................7
  3795. 5.1.3.       getByteValues............................................8
  3796. 5.1.4.       getStringValues..........................................8
  3797. 5.1.5.       getName..................................................8
  3798. 5.1.6.       removeValue..............................................8
  3799. 5.1.7.       size.....................................................8
  3800. 5.2.     LDAPAttributeSet.............................................9
  3801. 5.2.1.       Constructors.............................................9
  3802. 5.2.2.       add......................................................9
  3803. 5.2.3.       elementAt................................................9
  3804. 5.2.4.       getAttribute.............................................9
  3805. 5.2.5.       getAttributes............................................10
  3806. 5.2.6.       remove...................................................11
  3807. 5.2.7.       removeElementAt..........................................11
  3808. 5.2.8.       size.....................................................11
  3809. 5.3.     LDAPCompareAttrNames.........................................11
  3810. 5.3.1.       Constructors.............................................11
  3811. 5.3.2.       isGreater................................................12
  3812. 5.4.     LDAPConnection...............................................13
  3813. 5.4.1.       Constructors.............................................13
  3814. 5.4.2.       clone....................................................13
  3815. 5.4.3.       getAuthenticationDN......................................14
  3816. 5.4.4.       getAuthenticationPassword................................14
  3817. 5.4.5.       getHost..................................................14
  3818. 5.4.6.       getPort..................................................14
  3819. 5.4.7.       getProperty..............................................14
  3820. 5.4.8.       getSearchConstraints.....................................15
  3821. 5.4.9.       getSocketFactory.........................................15
  3822. 5.4.10.      isAuthenticated..........................................15
  3823. 5.4.11.      isConnected..............................................16
  3824. 5.4.12.      read.....................................................16
  3825. 5.4.13.      search...................................................16
  3826. 5.4.14.      setOption................................................17
  3827. 5.4.15.      setProperty..............................................20
  3828. 5.4.16.      setSocketFactory.........................................21
  3829. 5.5.     LDAPControl..................................................21
  3830. 5.5.1.       Constructors.............................................22
  3831. 5.5.2.       getID....................................................22
  3832. 5.5.3.       isCritical...............................................22
  3833. 5.5.4.       getValue.................................................22
  3834. 5.6.     LDAPDN.......................................................22
  3835. 5.6.1.       explodeDN................................................23
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841. 5.6.2.       explodeRDN...............................................23
  3842. 5.7.     LDAPEntry....................................................23
  3843. 5.7.1.       Constructors.............................................23
  3844. 5.7.2.       getAttribute.............................................24
  3845. 5.7.3.       getAttributeSet..........................................25
  3846. 5.7.4.       getDN....................................................26
  3847. 5.8.     LDAPExtendedOperation........................................26
  3848. 5.8.1.       Constructors.............................................26
  3849. 5.8.2.       getID....................................................26
  3850. 5.8.3.       getValue.................................................26
  3851. 5.9.     LDAPEntryComparator..........................................27
  3852. 5.9.1.       isGreater................................................27
  3853. 5.10.    LDAPException................................................27
  3854. 5.10.1.      Constructors.............................................27
  3855. 5.10.2.      getLDAPErrorMessage......................................28
  3856. 5.10.3.      getLDAPResultCode........................................28
  3857. 5.10.4.      getMatchedDN.............................................28
  3858. 5.10.5.      Error codes..............................................28
  3859. 5.11.    LDAPModification.............................................30
  3860. 5.11.1.      Constructors.............................................30
  3861. 5.11.2.      getAttribute.............................................30
  3862. 5.11.3.      getOp....................................................30
  3863. 5.12.    LDAPModificationSet..........................................30
  3864. 5.12.1.      Constructors.............................................31
  3865. 5.12.2.      add......................................................31
  3866. 5.12.3.      elementAt................................................31
  3867. 5.12.4.      remove...................................................31
  3868. 5.12.5.      removeElementAt..........................................32
  3869. 5.12.6.      size.....................................................32
  3870. 5.13.    LDAPRebindAuth...............................................32
  3871. 5.13.1.      Constructors.............................................32
  3872. 5.13.2.      getDN....................................................32
  3873. 5.13.3.      getPassword..............................................32
  3874. 5.14.    LDAPReferralException........................................33
  3875. 5.14.1.      Constructors.............................................33
  3876. 5.14.2.      getURLs..................................................33
  3877. 5.15.    LDAPSearchConstraints........................................33
  3878. 5.15.1.      Constructors.............................................34
  3879. 5.15.2.      getBatchSize.............................................35
  3880. 5.15.3.      getDereference...........................................35
  3881. 5.15.4.      getHopLimit..............................................35
  3882. 5.15.5.      getMaxResults............................................35
  3883. 5.15.6.      getRebindProc............................................35
  3884. 5.15.7.      getReferrals.............................................36
  3885. 5.15.8.      getTimeLimit.............................................36
  3886. 5.15.9.      setBatchSize.............................................36
  3887. 5.15.10.     setDereference...........................................36
  3888. 5.15.11.     setHopLimit..............................................37
  3889. 5.15.12.     setMaxResults............................................37
  3890. 5.15.13.     setRebindProc............................................37
  3891. 5.15.14.     setReferrals.............................................37
  3892. 5.15.15.     setTimeLimit.............................................38
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898. 5.16.    LDAPSearchResults............................................38
  3899. 5.16.1.      hasMoreElements..........................................38
  3900. 5.16.2.      next.....................................................38
  3901. 5.16.3.      nextElement..............................................39
  3902. 5.16.4.      sort.....................................................39
  3903. 5.17.    LDAPSocketFactory............................................39
  3904. 5.17.1.      makeSocket...............................................39
  3905. 5.18.    LDAPSortKey..................................................40
  3906. 5.18.1.      Constructors.............................................40
  3907. 5.18.2.      getKey...................................................41
  3908. 5.18.3.      getReverse...............................................41
  3909. 5.18.4.      getMatchRule.............................................41
  3910. 5.19.    LDAPUrl......................................................41
  3911. 5.19.1.      Constructors.............................................41
  3912. 5.19.2.      decode...................................................42
  3913. 5.19.3.      encode...................................................43
  3914. 5.19.4.      getAttributes............................................43
  3915. 5.19.5.      getAttributes............................................43
  3916. 5.19.6.      getDN....................................................43
  3917. 5.19.7.      getFilter................................................43
  3918. 5.19.8.      getHost..................................................44
  3919. 5.19.9.      getPort..................................................44
  3920. 5.19.10.     getUrl...................................................44
  3921. 5.20.    LDAPv2.......................................................44
  3922. 5.20.1.      add......................................................44
  3923. 5.20.2.      authenticate.............................................44
  3924. 5.20.3.      compare..................................................45
  3925. 5.20.4.      connect..................................................45
  3926. 5.20.5.      delete...................................................46
  3927. 5.20.6.      disconnect...............................................47
  3928. 5.20.7.      getOption................................................47
  3929. 5.20.8.      modify...................................................47
  3930. 5.20.9.      read.....................................................48
  3931. 5.20.10.     rename...................................................48
  3932. 5.20.11.     search...................................................49
  3933. 5.20.12.     setOption................................................50
  3934. 5.21.    LDAPv3.......................................................50
  3935. 5.21.1.      Preferred Language.......................................50
  3936. 5.21.2.      authenticate.............................................50
  3937. 5.21.3.      authenticate.............................................51
  3938. 5.21.4.      extendedOperation........................................52
  3939. 5.21.5.      getResponseControls......................................53
  3940. 5.21.6.      rename...................................................53
  3941. 5.22.    SaslAuthenticationCallback...................................53
  3942. 5.22.1.      request..................................................54
  3943. 5.23.     Client and Server Controls..................................54
  3944. 6.     Security Considerations........................................55
  3945. 7.     Acknowledgements...............................................55
  3946. 8.     Bibliography...................................................55
  3947. 9.     Authors' Addresses.............................................56
  3948. 10.    Appendix A - Sample java LDAP programs.........................57
  3949. 11.    Appendix B - Changes from draft-ietf-asid-ldap-java-api-00.txt.60
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955. 11.1.     LDAPConnection..............................................60
  3956. 11.2.     Controls....................................................60
  3957. 11.3.     LDAPException...............................................60
  3958. 11.4.     LDAPSearchResults...........................................60
  3959. 11.5.     LDAPSecurityException.......................................60
  3960. 11.6.     LDAPSortKey.................................................60
  3961. 11.7.     LDAPv3......................................................60
  3962. 11.8.     Examples....................................................60
  3963. 12.    Appendix C - Changes from draft-weltman-java-ldap-00.txt.......61
  3964. 12.1.     LDAPv3......................................................61
  3965. 12.2.     SSL -> TLS..................................................61
  3966. 12.3.     LDAPAttributeSet............................................61
  3967. 12.4.     LDAPCompareAttrNames........................................61
  3968. 12.5.     LDAPCompareAttrNames........................................61
  3969. 12.6.     LDAPControl.................................................61
  3970. 12.7.     LDAPEntry...................................................61
  3971. 12.8.     LDAPException...............................................61
  3972. 12.9.     LDAPExtendedOperation.......................................61
  3973. 12.10.    LDAPv2......................................................62
  3974. 12.11.    Dereferencing aliases.......................................62
  3975. 12.12.    Default referral hop limit..................................62
  3976. 12.13.    Examples....................................................62
  3977. 13.    Appendix D - Outstanding issues................................63
  3978. 13.1.     Support for SASL authentication.............................63
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.