home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_s_z / draft-weltman-java-ldap-00.txt < prev    next >
Text File  |  1997-04-23  |  72KB  |  2,701 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                         Rob Weltman
  8. INTERNET-DRAFT                              Netscape Communications Corp.
  9.                                                            April 22, 1997
  10.  
  11.  
  12.               The Java LDAP Application Program Interface
  13.  
  14.  
  15. Status of this Memo
  16.  
  17. This draft document, draft-weltman-java-ldap-00.txt, will be submitted
  18. to the RFC Editor as an informational document. Distribution of this
  19. memo is unlimited. Please send comments to the authors.
  20.  
  21. This document is an Internet-Draft.  Internet-Drafts are working docu-
  22. ments of the Internet Engineering Task Force (IETF), its areas, and its
  23. working groups.  Note that other groups may also distribute working
  24. documents as Internet-Drafts.
  25.  
  26. Internet-Drafts are draft documents valid for a maximum of six months
  27. and may be updated, replaced, or obsoleted by other documents at any
  28. time.  It is inappropriate to use Internet-Drafts as reference material
  29. or to cite them other than as ``work in progress.''
  30.  
  31. To learn the current status of any Internet-Draft, please check the
  32. ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
  33. Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
  34. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  35.  
  36. Abstract
  37.  
  38. This document defines a java language application program interface to
  39. the lightweight directory access protocol (LDAP), in the form of a class
  40. library. It complements but does not replace RFC 1823 ([9]), which
  41. describes a C language application program interface.
  42.  
  43.  
  44. 1.  Introduction
  45.  
  46. The LDAP class library is designed to provide powerful, yet simple,
  47. access to an LDAP directory services.  It defines a synchronous inter-
  48. face to LDAP, with support for partial results on searching, to suit a
  49. wide variety of applications. This document gives a brief overview of
  50. the LDAP model, then an overview of the constituents of the class
  51. library.  The public class methods are described in detail, followed by
  52. an appendix that provides some example code demonstrating the use of the
  53. classes. This document provides information to the Internet community.
  54. It does not specify any standard.
  55.  
  56.  
  57.  
  58. Expires 10/97                                                   [Page 1]
  59.  
  60.  
  61.  
  62.  
  63.  
  64. JAVA LDAP API                                                 April 1997
  65.  
  66.  
  67. 2.  Overview of the LDAP Model
  68.  
  69. LDAP is the lightweight directory access protocol, described in [2] and
  70. [7]. It can provide a lightweight frontend to the X.500 directory [1],
  71. or to an LDAP server, to which it sends requests and receives responses.
  72. LDAPv3 can also be used over UDP transport.
  73.  
  74. The LDAP information model is based on the entry, which contains infor-
  75. mation about some object (e.g., a person).  Entries are composed of
  76. attributes, which have a type and one or more values. Each attribute has
  77. a syntax that determines what kinds of values are allowed in the attri-
  78. bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
  79. values behave during directory operations (e.g., is case significant
  80. during comparisons).
  81.  
  82. Entries may be organized in a tree structure, usually based on politi-
  83. cal, geographical, and organizational boundaries. Each entry is uniquely
  84. named relative to its sibling entries by its relative distinguished name
  85. (RDN) consisting of one or more distinguished attribute values from the
  86. entry.  At most one value from each attribute may be used in the RDN.
  87. For example, the entry for the person Babs Jensen might be named with
  88. the "Barbara Jensen" value from the commonName attribute.
  89.  
  90. A globally unique name for an entry, called a distinguished name or DN,
  91. is constructed by concatenating the sequence of RDNs from the entry up
  92. to the root of the tree. For example, if Babs worked for the University
  93. of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
  94. o=University of Michigan, c=US". The DN format used by LDAP is defined
  95. in [4].
  96.  
  97. Operations are provided to authenticate, search for and retrieve infor-
  98. mation, modify information, and add and delete entries from the tree.
  99.  
  100. An LDAP server may return referrals if it cannot completely service a
  101. request, for example if the request specifies a directory base outside
  102. of the tree managed by the server. The LDAP class library offers the
  103. programmer the option of catching such referrals as exceptions and
  104. explicitly issuing new requests to the referred-to servers, or having
  105. referrals followed automatically by the library. In the latter case, the
  106. programmer may also provide a reauthentication object, allowing
  107. automatic referrals to procede with appropriate (non-anonymous) creden-
  108. tials for each referred-to server.
  109.  
  110. The next sections give an overview of how the class library is used and
  111. detailed descriptions of the LDAP class methods that implement all of
  112. these functions.
  113.  
  114.  
  115.  
  116.  
  117.  
  118. Expires 10/97                                                   [Page 2]
  119.  
  120.  
  121.  
  122.  
  123.  
  124. JAVA LDAP API                                                 April 1997
  125.  
  126.  
  127. 3.  Overview of the LDAP classes
  128.  
  129.  
  130. 3.1.  Interfaces
  131.  
  132.  
  133. LDAPEntryComparator   An interface to support arbitrary sorting algo-
  134.                       rithms for entries returned by a search operation.
  135.                       At least one implementation must be provided:
  136.                       LDAPCompareAttrNames, to sort in ascending order
  137.                       based on one or more attribute names.
  138.  
  139.  
  140. LDAPRebind            A programmer desiring reauthentication on automat-
  141.                       ically following referrals must implement this
  142.                       interface. Without it, automatically followed
  143.                       referrals will use anonymous authentication.
  144.  
  145.  
  146. LDAPSocketFactory     Programmers needing to provide or use specialized
  147.                       socket connections, including Secure Socket Layer
  148.                       (SSL) based ones, can provide an object construc-
  149.                       tor to implement them.
  150.  
  151.  
  152. LDAPv2                This interface defines the functionality of the
  153.                       LDAP version 2 protocol. It is implemented by
  154.                       LDAPConnection.
  155.  
  156.  
  157. 3.2.  Classes
  158.  
  159.  
  160. LDAPAttribute         Represents the name and values of one attribute of
  161.                       a directory entry.
  162.  
  163.  
  164. LDAPAttributeSet      A collection of LDAPAttributes.
  165.  
  166.  
  167. LDAPCompareAttrNames  An implementation of LDAPEntryComparator, to sup-
  168.                       port sorting of search results by one or more
  169.                       attributes.
  170.  
  171.  
  172. LDAPConnection        Implements LDAPv2 and is the central point for
  173.                       interactions with a directory.
  174.  
  175.  
  176.  
  177.  
  178. Expires 10/97                                                   [Page 3]
  179.  
  180.  
  181.  
  182.  
  183.  
  184. JAVA LDAP API                                                 April 1997
  185.  
  186.  
  187. LDAPDN                A utility class to facilitate composition and
  188.                       decomposition of distinguished names (DNs).
  189.  
  190.  
  191. LDAPEntry             Represents a single entry in a directory.
  192.  
  193.  
  194. LDAPModification      A single add/delete/replace operation to an
  195.                       LDAPAttribute.
  196.  
  197.  
  198. LDAPModificationSet   A collection of LDAPModifications
  199.  
  200.  
  201. LDAPRebindAuth        An implementation of LDAPRebind must be able to
  202.                       provide an LDAPRebindAuth at the time of a refer-
  203.                       ral. The class encapsulates reauthentication
  204.                       credentials.
  205.  
  206.  
  207. LDAPSearchConstraints Defines the options controlling search operations.
  208.  
  209.  
  210. LDAPSearchResults     The enumerable results of a search operation.
  211.  
  212.  
  213. LDAPUrl               Encapsulates parameters of an LDAP Url query, as
  214.                       defined in [8].
  215.  
  216.  
  217. 3.3.  Exceptions
  218.  
  219.  
  220. LDAPException         General exception, comprising a code and textual
  221.                       context.
  222.  
  223.  
  224. LDAPReferralException Derived from LDAPException, contains a list of
  225.                       LDAPUrls corresponding to referrals received on an
  226.                       LDAP operation.
  227.  
  228.  
  229. LDAPSecurityException Derived from LDAPException, thrown on security
  230.                       mismatches.
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238. Expires 10/97                                                   [Page 4]
  239.  
  240.  
  241.  
  242.  
  243.  
  244. JAVA LDAP API                                                 April 1997
  245.  
  246.  
  247. 4.  Overview of LDAP API Use
  248.  
  249. An application generally uses the LDAP API in four steps.
  250.  
  251. -    Construct an LDAPConnection.  Initialize an LDAP session with a
  252.      directory server. The LDAPConnection.connect() call establishes a
  253.      handle to the session, allowing multiple sessions to be open at
  254.      once, on different instances of LDAPConnection.
  255.  
  256. -    Authenticate to the LDAP server with LDAPConnection.authenticate().
  257.  
  258. -    Perform some LDAP operations and obtain some results.
  259.      LDAPConnection.search() returns an LDAPSearchResults, which can be
  260.      enumerated to access all entries found. LDAPConnection.read()
  261.      returns a single entry.
  262.  
  263. -    Close the connection. The LDAPConnection.disconnect() call closes
  264.      the connection.
  265.  
  266. All operations are synchronous - they do not return until the operation
  267. has completed. In the java environment, it is appropriate to create a
  268. thread for the operation rather than providing parallel synchronous and
  269. asynchronous operations, as is the case in the C language API described
  270. in [9]. A special accomodation is made for providing intermediate
  271. results on searching, to facilitate user feedback: the number of entries
  272. to return at a time can be specified.
  273.  
  274. Standard java Enumerations are used to parse search results. Errors
  275. result in the throwing of an LDAPException, with a specific error code
  276. and context-specific textual information available.  The following sec-
  277. tions describe the LDAP classes in more detail.
  278.  
  279. 5.  The java LDAP classes
  280.  
  281.  
  282. 5.1.  public class LDAPAttribute extends Object
  283.  
  284. The LDAPAttribute class represents the name and values of an attribute
  285. in an entry.
  286.  
  287.  
  288. 5.1.1.  Constructors
  289.  
  290.    public LDAPAttribute(String attrName)
  291.  
  292.    Constructs an attribute with no values.
  293.  
  294.  
  295.  
  296.  
  297.  
  298. Expires 10/97                                                   [Page 5]
  299.  
  300.  
  301.  
  302.  
  303.  
  304. JAVA LDAP API                                                 April 1997
  305.  
  306.  
  307.    public LDAPAttribute(String attrName,
  308.                         byte attrBytes[])
  309.  
  310.    Constructs an attribute with a byte-formatted value.
  311.  
  312.  
  313.    public LDAPAttribute(String attrName,
  314.                         String attrString)
  315.  
  316.    Constructs an attribute that has a single string value.
  317.  
  318.  
  319.    public LDAPAttribute(String attrName,
  320.                         String attrStrings[])
  321.  
  322.    Constructs an attribute that has an array of string values.
  323.  
  324.    Parameters are:
  325.  
  326.    attrName      Name of the attribute.
  327.  
  328.    attrBytes     Value of the attribute as raw bytes.
  329.  
  330.    attrString    Value of the attribute as a String.
  331.  
  332.    attrStrings   Array of values as Strings.
  333.  
  334.  
  335. 5.1.2.  addValue
  336.  
  337.    public synchronized void addValue(String attrString)
  338.  
  339.    Adds a string value to the attribute.
  340.  
  341.  
  342.    public synchronized void addValue(byte attrBytes[])
  343.  
  344.    Adds a byte[]-formatted value to the attribute.
  345.  
  346.    Parameters are:
  347.  
  348.    attrString    Value of the attribute as a String.
  349.  
  350.    attrBytes     Value of the attribute as raw bytes.
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358. Expires 10/97                                                   [Page 6]
  359.  
  360.  
  361.  
  362.  
  363.  
  364. JAVA LDAP API                                                 April 1997
  365.  
  366.  
  367. 5.1.3.  getByteValues
  368.  
  369.    public Enumeration getByteValues()
  370.  
  371.    Returns an enumerator for the values of the attribute in byte[] for-
  372.    mat.
  373.  
  374.  
  375. 5.1.4.  getStringValues
  376.  
  377.    public Enumeration getStringValues()
  378.  
  379.    Returns an enumerator for the string values of an attribute.
  380.  
  381.  
  382. 5.1.5.  getName
  383.  
  384.    public String getName()
  385.  
  386.    Returns the name of the attribute.
  387.  
  388.  
  389. 5.1.6.  removeValue
  390.  
  391.    public synchronized void removeValue(String attrString)
  392.  
  393.    Removes a string value from the attribute.
  394.  
  395.  
  396.    public synchronized void removeValue(byte attrValue[])
  397.  
  398.    Removes a byte[]-formatted value from the attribute.
  399.  
  400.    Parameters are:
  401.  
  402.    attrString    Value of the attribute as a String.
  403.  
  404.    attrBytes     Value of the attribute as raw bytes.
  405.  
  406.  
  407. 5.1.7.  size
  408.  
  409.    public int size()
  410.  
  411.    Returns the number of values of the attribute.
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418. Expires 10/97                                                   [Page 7]
  419.  
  420.  
  421.  
  422.  
  423.  
  424. JAVA LDAP API                                                 April 1997
  425.  
  426.  
  427. 5.2.  public class LDAPAttributeSet extends Object
  428.  
  429. An LDAPAttributeSet is a collection of LDAPAttributes, as returned in an
  430. entry on a search or read operation, or used to construct an entry to be
  431. added to a directory.
  432.  
  433.  
  434. 5.2.1.  Constructors
  435.  
  436.    public LDAPAttributeSet()
  437.  
  438.    Constructs a new set of attributes. This set is initially empty.
  439.  
  440.  
  441. 5.2.2.  add
  442.  
  443.    public synchronized void add(LDAPAttribute attr)
  444.  
  445.    Adds the specified attribute to this attribute set.
  446.  
  447.    Parameters are:
  448.  
  449.    attr          Attribute to add to this set.
  450.  
  451.  
  452. 5.2.3.  elementAt
  453.  
  454.    public LDAPAttribute elementAt(int index)
  455.                                throws ArrayIndexOutOfBoundsException
  456.  
  457.    Returns the attribute at the position specified by the index.  The
  458.    index is 0-based.
  459.  
  460.    Parameters are:
  461.  
  462.    index         Index of the attribute to get.
  463.  
  464.  
  465. 5.2.4.  getAttributes
  466.  
  467.    public Enumeration getAttributes()
  468.  
  469.    Returns an enumeration of the attributes in this attribute set.
  470.  
  471. 5.2.5.  remove
  472.  
  473.    public synchronized void remove(String name)
  474.  
  475.  
  476.  
  477.  
  478. Expires 10/97                                                   [Page 8]
  479.  
  480.  
  481.  
  482.  
  483.  
  484. JAVA LDAP API                                                 April 1997
  485.  
  486.  
  487.    Removes the specified attribute from the set.
  488.  
  489.    Parameters are:
  490.  
  491.    name          Name of the attribute to remove from this set. To
  492.                  remove an LDAPAttribute by object, the
  493.                  LDAPAttribute.getName method can be used:
  494.  
  495.                  LDAPAttributeSet.remove( attr.getName() );
  496.  
  497.  
  498. 5.2.6.  removeElementAt
  499.  
  500.    public void removeElementAt(int index)
  501.                                throws ArrayIndexOutOfBoundsException
  502.  
  503.    Removes the attribute at the position specified by the index.  The
  504.    index is 0-based.
  505.  
  506.    Parameters are:
  507.  
  508.    index         Index of the attribute to remove.
  509.  
  510.  
  511. 5.2.7.  size
  512.  
  513.    public int size()
  514.  
  515.    Returns the number of attributes in this set.
  516.  
  517.  
  518. 5.3.  public class LDAPCompareAttrNames extends Object implements
  519. LDAPEntryComparator
  520.  
  521. An object of this class supports sorting search results by attribute
  522. name, in ascending order
  523.  
  524.  
  525. 5.3.1.  Constructors
  526.  
  527.    public LDAPCompareAttrNames(String attrName)
  528.  
  529.    Constructs an object that will sort results by a single attribute, in
  530.    ascending order.
  531.  
  532.  
  533.    public LDAPCompareAttrNames(String[] attrNames)
  534.  
  535.  
  536.  
  537.  
  538. Expires 10/97                                                   [Page 9]
  539.  
  540.  
  541.  
  542.  
  543.  
  544. JAVA LDAP API                                                 April 1997
  545.  
  546.  
  547.    Constructs an object that will sort by one or more attributes, in the
  548.    order provided, in ascending order.
  549.  
  550.    Parameters are:
  551.  
  552.    attrName      Name of an attribute to sort by.
  553.  
  554.    attrNames     Array of names of attributes to sort by.
  555.  
  556.  
  557. 5.3.2.  isGreater
  558.  
  559.    public boolean isGreater (LDAPEntry e1, LDAPEntry e2)
  560.  
  561.    Returns true if entry1 is to be considered greater than or equal to
  562.    entry2, for the purpose of sorting, based on the attribute name or
  563.    names provided on object construction.
  564.  
  565.    Parameters are:
  566.  
  567.    entry1        Target entry for comparison.
  568.  
  569.    entry2        Entry to be compared to.
  570.  
  571.  
  572. 5.4.  public class LDAPConnection extends Object implements LDAPv2,
  573. Cloneable
  574.  
  575. LDAPConnection is the central class that encapsulates the connection to
  576. a Directory Server through the LDAP protocol. It implements the LDAPv2
  577. interface, and will in future releases implement additional LDAP proto-
  578. col level interfaces. An LDAPConnection object is not connected on con-
  579. struction, and may only be connected to one server at one port. Multiple
  580. threads may share this single connection, and an application may have
  581. more than one LDAPConnection object, connected to the same or different
  582. Directory Servers.
  583.  
  584. Besides the methods described for LDAPv2 above, LDAPConnection provides
  585. the following methods.
  586.  
  587. 5.4.1.  Constructors
  588.  
  589.    public LDAPConnection()
  590.  
  591.    Constructs a new LDAPConnection object, which represents a connection
  592.    to an LDAP server.
  593.  
  594.    Calling the constructor does not actually establish the connection.
  595.  
  596.  
  597.  
  598. Expires 10/97                                                  [Page 10]
  599.  
  600.  
  601.  
  602.  
  603.  
  604. JAVA LDAP API                                                 April 1997
  605.  
  606.  
  607.    To connect to the LDAP server, use the connect method.
  608.  
  609.  
  610.    public LDAPConnection(LDAPSocketFactory factory)
  611.  
  612.    Constructs a new LDAPConnection object, which will use the supplied
  613.    class factory to construct a socket connection during
  614.    LDAPConnection.connect().
  615.  
  616.  
  617. 5.4.2.  clone
  618.  
  619.    public LDAPConnection clone()
  620.  
  621.    Returns a copy of the object with a private context, but sharing the
  622.    network connection if there is one. The network connection remains
  623.    open until all clones have disconnected or gone out of scope.
  624.  
  625.  
  626. 5.4.3.  getAuthenticationDN
  627.  
  628.    public String getAuthenticationDN()
  629.  
  630.    Returns the distinguished name (DN) used for authentication by this
  631.    object.
  632.  
  633.  
  634. 5.4.4.  getAuthenticationPassword
  635.  
  636.    public String getAuthenticationPassword()
  637.  
  638.    Returns the password used for authentication by this object.
  639.  
  640.  
  641. 5.4.5.  getHost
  642.  
  643.    public String getHost()
  644.  
  645.    Returns the host name of the LDAP server to which the object is or
  646.    was last connected.
  647.  
  648.  
  649. 5.4.6.  getPort
  650.  
  651.    public int getPort()
  652.  
  653.    Returns the port number of the LDAP server to which the object is or
  654.    was last connected.
  655.  
  656.  
  657.  
  658. Expires 10/97                                                  [Page 11]
  659.  
  660.  
  661.  
  662.  
  663.  
  664. JAVA LDAP API                                                 April 1997
  665.  
  666.  
  667. 5.4.7.  getProperty
  668.  
  669.    public Object getProperty(String name) throws LDAPException
  670.  
  671.    Gets a property of a connection object.
  672.  
  673.    The following read-only properties are available for any given con-
  674.    nection:
  675.  
  676.  
  677.       LDAP_PROPERTY_SDK             The version of this SDK, as a Float
  678.                                     data type.
  679.  
  680.  
  681.       LDAP_PROPERTY_PROTOCOL        The highest supported version of the
  682.                                     LDAP protocol, as a Float data type.
  683.  
  684.  
  685.       LDAP_PROPERTY_SECURITY        A comma-separated list of the types
  686.                                     of authentication supported, as a
  687.                                     String.
  688.  
  689.    Other properties may be available in particular implementations of
  690.    the class, and used to modify operations such as search.
  691.  
  692.    An LDAPException is thrown if the requested property is not avail-
  693.    able.
  694.  
  695. 5.4.8.  getSearchConstraints
  696.  
  697.    public LDAPSearchConstraints getSearchConstraints()
  698.  
  699.    Returns the set of search constraints that apply to all searches per-
  700.    formed through this connection (unless a different set of search con-
  701.    straints is specified when calling the search method).
  702.  
  703.    Note that the getOption method can be used to get individual con-
  704.    straints (rather than getting the entire set of constraints).
  705.  
  706.    Typically, the getSearchConstraints method is used to create a
  707.    slightly different set of search constraints to apply to a particular
  708.    search.
  709.  
  710.  
  711. 5.4.9.  getSocketFactory
  712.  
  713.    public static LDAPSocketFactory getSocketFactory()
  714.  
  715.  
  716.  
  717.  
  718. Expires 10/97                                                  [Page 12]
  719.  
  720.  
  721.  
  722.  
  723.  
  724. JAVA LDAP API                                                 April 1997
  725.  
  726.  
  727.    Returns the default LDAPSocketFactory used to establish a connection
  728.    to a server.
  729.  
  730.  
  731. 5.4.10.  isAuthenticated
  732.  
  733.    public boolean isAthenticated()
  734.  
  735.    Indicates whether the object has authenticated to the connected LDAP
  736.    server.
  737.  
  738.  
  739. 5.4.11.  isConnected
  740.  
  741.    public boolean isConnected()
  742.  
  743.    Indicates whether the connection represented by this object is open
  744.    at this time.
  745.  
  746.  
  747. 5.4.12.  read
  748.  
  749.    public static LDAPEntry read(LDAPUrl toGet) throws LDAPException
  750.  
  751.    Reads the entry specified by the LDAP URL.
  752.  
  753.    When this method is called, a new connection is created automati-
  754.    cally, using the host and port specified in the URL. After finding
  755.    the entry, the method closes the connection (in other words, it
  756.    disconnects from the LDAP server).
  757.  
  758.    If the URL specifies a filter and scope, these are not used. Of the
  759.    information specified in the URL, this method only uses the LDAP host
  760.    name and port number, the base distinguished name (DN), and the list
  761.    of attributes to return.
  762.  
  763.    The method returns the entry specified by the base DN.
  764.  
  765.    Parameters are:
  766.  
  767.    toGet         LDAP URL specifying the entry to read.
  768.  
  769.  
  770. 5.4.13.  search
  771.  
  772.    public static LDAPSearchResults search(LDAPUrl toGet) throws LDAPEx-
  773.    ception
  774.  
  775.  
  776.  
  777.  
  778. Expires 10/97                                                  [Page 13]
  779.  
  780.  
  781.  
  782.  
  783.  
  784. JAVA LDAP API                                                 April 1997
  785.  
  786.  
  787.    Performs the search specified by the LDAP URL, returning an enumer-
  788.    able LDAPSearchResults object.
  789.  
  790.  
  791.    public static LDAPSearchResults search(LDAPUrl toGet,
  792.                                           LDAPSearchConstraints cons)
  793.                                           throws LDAPException
  794.  
  795.    Perfoms the search specified by the LDAP URL. This method also allows
  796.    specifying constraints for the search (such as the maximum number of
  797.    entries to find or the maximum time to wait for search results).
  798.  
  799.    As part of the search constraints, a choice can be made as to whether
  800.    to have the results delivered all at once or in smaller batches. If
  801.    the results are to be delivered in smaller batches, each iteration
  802.    blocks only until the next batch of results is returned.
  803.  
  804.    Parameters are:
  805.  
  806.    toGet         LDAP URL specifying the entry to read.
  807.  
  808.  
  809. 5.4.14.  setOption
  810.  
  811.    public void setOption(int option,
  812.                          Object value)
  813.                          throws LDAPException
  814.  
  815.    Sets the value of the specified option for this LDAPConnection
  816.    object.
  817.  
  818.    These options represent the default search constraints for the
  819.    current connection. Some of these options are also propagated through
  820.    the LDAPSearchConstraints, which can be obtained from the connection
  821.    object with the getSearchConstraints method.
  822.  
  823.    The option that is set here applies to all subsequent searches per-
  824.    formed through the current connection, unless it is overridden with
  825.    an LDAPSearchConstraints at the time of search.
  826.  
  827.    To set a constraint only for a particular search, create an LDAPSear-
  828.    chConstraints object with the new constraints and pass it to the
  829.    LDAPConnection.search method.
  830.  
  831.    Parameters are:
  832.  
  833.  
  834.    option        One of the following options:
  835.  
  836.  
  837.  
  838. Expires 10/97                                                  [Page 14]
  839.  
  840.  
  841.  
  842.  
  843.  
  844. JAVA LDAP API                                                 April 1997
  845.  
  846.  
  847.       Option                        Type        Description
  848.  
  849.  
  850.       LDAPv2.DEREF                  Boolean     Specifies whether or not
  851.                                                 the object dereferences
  852.                                                 aliases.  If true, it
  853.                                                 dereferences aliases. By
  854.                                                 default, the value of
  855.                                                 this option is true.
  856.  
  857.  
  858.       LDAPv2.SIZELIMIT              Integer     Specifies the maximum
  859.                                                 number of search results
  860.                                                 to return. If this
  861.                                                 option is set to 0,
  862.                                                 there is no maximum
  863.                                                 limit.
  864.  
  865.                                                 By default, the value of
  866.                                                 this option is 1000.
  867.  
  868.  
  869.       LDAPv2.TIMELIMIT              Integer     Specifies the maximum
  870.                                                 number of milliseconds
  871.                                                 to wait for results
  872.                                                 before timing out. If
  873.                                                 this option is set to 0,
  874.                                                 there is no maximum time
  875.                                                 limit.
  876.  
  877.                                                 By default, the value of
  878.                                                 this option is 0.
  879.  
  880.  
  881.       LDAPv2.REFERRALS              Boolean     Specifies whether or not
  882.                                                 the client follows
  883.                                                 referrals automatically.
  884.                                                 If true, the client fol-
  885.                                                 lows referrals automati-
  886.                                                 cally.  If false, an
  887.                                                 LDAPReferralException is
  888.                                                 raised when a referral
  889.                                                 is detected.
  890.  
  891.                                                 By default, the value of
  892.                                                 this option is false.
  893.  
  894.  
  895.  
  896.  
  897.  
  898. Expires 10/97                                                  [Page 15]
  899.  
  900.  
  901.  
  902.  
  903.  
  904. JAVA LDAP API                                                 April 1997
  905.  
  906.  
  907.       LDAPv2.REFERRALS_REBIND_PROC  LDAPRebind  Specifies an object that
  908.                                                 implements the LDAPRe-
  909.                                                 bind interface.  A user
  910.                                                 of the class library
  911.                                                 must define this class
  912.                                                 and the getRebindAuthen-
  913.                                                 tication method that
  914.                                                 will be used to get the
  915.                                                 distinguished name and
  916.                                                 password to use for
  917.                                                 authentication. If this
  918.                                                 value is null and REFER-
  919.                                                 RALS is true, referrals
  920.                                                 will be followed with
  921.                                                 anonymous (= no) authen-
  922.                                                 tication.
  923.  
  924.                                                 By default, the value of
  925.                                                 this option is null.
  926.  
  927.  
  928.       LDAPv2.REFERRALS_HOP_LIMIT     Integer    Specifies the maximum
  929.                                                 number of referrals in a
  930.                                                 sequence that the client
  931.                                                 will follow. For exam-
  932.                                                 ple, if
  933.                                                 REFERRALS_HOP_LIMIT is
  934.                                                 5, the client will fol-
  935.                                                 low no more than 5
  936.                                                 referrals in a row when
  937.                                                 resolving a single LDAP
  938.                                                 request.
  939.  
  940.                                                 The default value of
  941.                                                 this option is 5.
  942.  
  943.  
  944.       LDAPv2.BATCHSIZE               Integer    Specifies the number of
  945.                                                 search results to return
  946.                                                 at a time. For example,
  947.                                                 if BATCHSIZE is 1,
  948.                                                 enumerating an LDAPSear-
  949.                                                 chResults will block
  950.                                                 only until one entry is
  951.                                                 available. If it is 0,
  952.                                                 enumerating will block
  953.                                                 until all entries have
  954.                                                 been retrieved from the
  955.  
  956.  
  957.  
  958. Expires 10/97                                                  [Page 16]
  959.  
  960.  
  961.  
  962.  
  963.  
  964. JAVA LDAP API                                                 April 1997
  965.  
  966.  
  967.                                                 server.
  968.  
  969.                                                 The default value of
  970.                                                 this option is 1.
  971.  
  972.  
  973.    value         The value to assign to the option. The value must be
  974.                  the java.lang object wrapper for the appropriate param-
  975.                  eter (e.g. boolean->Boolean, int->Integer) .
  976.  
  977.  
  978. 5.4.15.  setProperty
  979.  
  980.    public void setProperty(String name, Object value)
  981.  
  982.    Sets a property of a connection object.
  983.  
  984.    No property names have been defined at this time, but the mechanism
  985.    is in place in order to support revisional as well as dynamic exten-
  986.    sions to operation modifiers.
  987.  
  988. 5.4.16.  setSocketFactory
  989.  
  990.    public static void setSocketFactory(LDAPSocketFactory factory)
  991.  
  992.    Establishes the default LDAPSocketFactory used to establish a connec-
  993.    tion to a server.
  994.  
  995.    This method is implemented as once-only. It is useful to be able to
  996.    change the run-time connection behavior of a whole application with a
  997.    single instruction, but the results would be confusing, and the
  998.    side-effects dangerous, if the global default factory could be
  999.    changed at arbitrary times by different threads.
  1000.  
  1001.    A typical usage would be:
  1002.  
  1003.        if (usingSSL) {
  1004.            LDAPConnection.setSocketFactory(mySSLFactory);
  1005.        }
  1006.        ...
  1007.        LDAPConnection conn = new LDAPConnection();
  1008.        conn.connect(myHost, myPort);
  1009.  
  1010.    In this example, connections are constructed with the default LDAP-
  1011.    SocketFactory.  At application start-up time, the default may be set
  1012.    to use a particular provided SSL socket factory.
  1013.  
  1014.    Parameters are:
  1015.  
  1016.  
  1017.  
  1018. Expires 10/97                                                  [Page 17]
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024. JAVA LDAP API                                                 April 1997
  1025.  
  1026.  
  1027.    factory       A factory object which can construct socket connections
  1028.                  for an LDAPConnection.
  1029.  
  1030.  
  1031. 5.5.  public class LDAPDN extends Object
  1032.  
  1033. A utility class representing a distinguished name (DN).
  1034.  
  1035.  
  1036. 5.5.1.  explodeDN
  1037.  
  1038.    public static String[] explodeDN(String dn,
  1039.                                     boolean noTypes)
  1040.  
  1041.    Returns the individual components of a distinguished name (DN).
  1042.  
  1043.    Parameters are:
  1044.  
  1045.    dn            Distinguished name, e.g. "cn=Babs
  1046.                  Jensen,ou=Accounting,o=Acme,c=us"
  1047.  
  1048.    noTypes       If true, returns only the values of the components, and
  1049.                  not the names, e.g. "Babs Jensen", "Accounting",
  1050.                  "Acme", "us" - instead of "cn=Babs Jensen",
  1051.                  "ou=Accounting", "o=Acme", and "c=us".
  1052.  
  1053.  
  1054. 5.5.2.  explodeRDN
  1055.  
  1056.    public static String[] explodeRDN(String rdn,
  1057.                                      boolean noTypes)
  1058.  
  1059.    Returns the individual components of a relative distinguished name
  1060.    (RDN).
  1061.  
  1062.    Parameters are:
  1063.  
  1064.    rdn           Relative distinguished name, i.e. only those components
  1065.                  of a distinguished name which are unique to an entry at
  1066.                  its position in a directory tree.
  1067.  
  1068.    noTypes       If true, returns only the values of the components, and
  1069.                  not the names.
  1070.  
  1071.  
  1072. 5.6.  public class LDAPEntry extends Object
  1073.  
  1074. An LDAPEntry represents a single entry in a directory, consisting of a
  1075.  
  1076.  
  1077.  
  1078. Expires 10/97                                                  [Page 18]
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084. JAVA LDAP API                                                 April 1997
  1085.  
  1086.  
  1087. distinguished name (DN) and zero or more attributes.
  1088.  
  1089.  
  1090. 5.6.1.  Constructors
  1091.  
  1092.    public LDAPEntry()
  1093.  
  1094.    Constructs an empty entry.
  1095.  
  1096.  
  1097.    public LDAPEntry(String dn)
  1098.  
  1099.    Constructs a new entry with the specified distinguished name and with
  1100.    an empty attribute set.
  1101.  
  1102.  
  1103.    public LDAPEntry(String dn
  1104.                     LDAPAttributeSet attrs)
  1105.  
  1106.    Constructs a new entry with the specified distinguished name and set
  1107.    of attributes.
  1108.  
  1109.    Parameters are:
  1110.  
  1111.    dn            The distinguished name of the new entry.
  1112.  
  1113.    attrs         The initial set of attributes assigned to the entry.
  1114.  
  1115.  
  1116. 5.6.2.  getAttributeSet
  1117.  
  1118.    public LDAPAttributeSet getAttributeSet()
  1119.  
  1120.    Returns the attribute set of the entry.
  1121.  
  1122.  
  1123. 5.6.3.  getDN
  1124.  
  1125.    public String getDN()
  1126.  
  1127.    Returns the distinguished name of the current entry.
  1128.  
  1129.  
  1130. 5.7.  public interface LDAPEntryComparator
  1131.  
  1132. An object of this class can implement arbitrary sorting algorithms for
  1133. search results.
  1134.  
  1135.  
  1136.  
  1137.  
  1138. Expires 10/97                                                  [Page 19]
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144. JAVA LDAP API                                                 April 1997
  1145.  
  1146.  
  1147. 5.7.1.  isGreater
  1148.  
  1149.    public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2)
  1150.  
  1151.    Returns true if entry1 is to be considered greater than or equal to
  1152.    entry2, for the purpose of sorting.
  1153.  
  1154.    Parameters are:
  1155.  
  1156.    entry1        Target entry for comparison.
  1157.  
  1158.    entry2        Entry to be compared to.
  1159.  
  1160.  
  1161. 5.8.  public class LDAPException extends Exception
  1162.  
  1163. Thrown to indicate that an error has occurred. An LDAPException can
  1164. result from physical problems (such as network errors) as well as prob-
  1165. lems with LDAP operations (for example, if the LDAP add operation fails
  1166. because of duplicate entry).
  1167.  
  1168. Most errors that occur throw this type of exception. In order to The
  1169. getLDAPResultCode() method returns the specific result code, which can
  1170. be compared against standard LDAP result codes as defined in [11], sec-
  1171. tion 4.
  1172.  
  1173.  
  1174. 5.8.1.  Constructors
  1175.  
  1176.    public LDAPException()
  1177.  
  1178.    Constructs a default exception with no specific error information.
  1179.  
  1180.  
  1181.    public LDAPException(String message)
  1182.  
  1183.    Constructs a default exception with a specified string as additional
  1184.    information. This form is used for lower-level errors.
  1185.  
  1186.  
  1187.    public LDAPException(String message,
  1188.                         int resultCode,
  1189.                         String serverMessage)
  1190.  
  1191.    Constructs a default exception with a specified string as additional
  1192.    information. This form is used for higher-level LDAP operational
  1193.    errors.
  1194.  
  1195.  
  1196.  
  1197.  
  1198. Expires 10/97                                                  [Page 20]
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204. JAVA LDAP API                                                 April 1997
  1205.  
  1206.  
  1207.    Parameters are:
  1208.  
  1209.    message       The additional error information.
  1210.  
  1211.    resultCode    The result code returned
  1212.  
  1213.    serverMessage Error message specifying additional information from
  1214.                  the server.
  1215.  
  1216.  
  1217. 5.8.2.  getLDAPErrorMessage
  1218.  
  1219.    public String getLDAPErrorMessage()
  1220.  
  1221.    Returns the error message from the last error, if this message is
  1222.    available (that is, if this message was set). If the message was not
  1223.    set, this method returns null.
  1224.  
  1225.  
  1226. 5.8.3.  getLDAPResultCode
  1227.  
  1228.    public int getLDAPResultCode()
  1229.  
  1230.    Returns the result code from the last error. The codes are defined as
  1231.    public final static int members of this class. Note that this value
  1232.    is not always valid; -1 indicates this situation.
  1233.  
  1234.  
  1235. 5.8.4.  Error codes
  1236.  
  1237. See [11] and [7] for a discussion of the meanings of the codes.
  1238.  
  1239.      ADMIN_LIMIT_EXCEEDED
  1240.      AFFECTS_MULTIPLE_DSAS
  1241.      ALIAS_DEREFERENCING_PROBLEM
  1242.      ALIAS_PROBLEM
  1243.      ATTRIBUTE_OR_VALUE_EXISTS
  1244.      AUTH_METHOD_NOT_SUPPORTED
  1245.      BUSY
  1246.      COMPARE_FALSE
  1247.      COMPARE_TRUE
  1248.      CONSTRAINT_VIOLATION
  1249.      ENTRY_ALREADY_EXISTS
  1250.      INAPPROPRIATE_AUTHENTICATION
  1251.      INAPPROPRIATE_MATCHING
  1252.      INSUFFICIENT_ACCESS_RIGHTS
  1253.      INVALID_ATTRIBUTE_SYNTAX
  1254.      INVALID_CREDENTIALS
  1255.  
  1256.  
  1257.  
  1258. Expires 10/97                                                  [Page 21]
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264. JAVA LDAP API                                                 April 1997
  1265.  
  1266.  
  1267.      INVALID_DN_SYNTAX
  1268.      IS_LEAF
  1269.      LDAP_PARTIAL_RESULTS
  1270.      LOOP_DETECT
  1271.      NAMING_VIOLATION
  1272.      NO_SUCH_ATTRIBUTE
  1273.      NO_SUCH_OBJECT
  1274.      NOT_ALLOWED_ON_NONLEAF
  1275.      NOT_ALLOWED_ON_RDN
  1276.      OBJECT_CLASS_MODS_PROHIBITED
  1277.      OBJECT_CLASS_VIOLATION
  1278.      OPERATION_ERROR
  1279.      OTHER
  1280.      PROTOCOL_ERROR
  1281.      REFERRAL
  1282.      SIZE_LIMIT_EXCEEDED
  1283.      STRONG_AUTH_REQUIRED
  1284.      SUCCESS
  1285.      TIME_LIMIT_EXCEEDED
  1286.      UNAVAILABLE
  1287.      UNAVAILABLE_CRITICAL_EXTENSION
  1288.      UNDEFINED_ATTRIBUTE_TYPE
  1289.      UNWILLING_TO_PERFORM
  1290.  
  1291.  
  1292. 5.9.  public class LDAPModification extends Object
  1293.  
  1294. A single change specification for an LDAPAttribute.
  1295.  
  1296.  
  1297. 5.9.1.  Constructors
  1298.  
  1299.    public LDAPModification(int op,
  1300.                            LDAPAttribute attr)
  1301.  
  1302.    Specifies a modification to be made to an attribute.
  1303.  
  1304.    Parameters are:
  1305.  
  1306.    op            The type of modification to make, which can be one of
  1307.                  the following:
  1308.  
  1309.       LDAPModification.ADD     The value should be added to the attri-
  1310.                                bute
  1311.  
  1312.       LDAPModification.DELETE  The value should be removed from the
  1313.                                attribute
  1314.  
  1315.  
  1316.  
  1317.  
  1318. Expires 10/97                                                  [Page 22]
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. JAVA LDAP API                                                 April 1997
  1325.  
  1326.  
  1327.       LDAPModification.REPLACE The value should replace all existing
  1328.                                values of the attribute
  1329.  
  1330.       For a binary value (not a string value), the operation should be
  1331.       Or'd (|) with LDAPModification.BVALUES.
  1332.  
  1333.    attr          The attribute (possibly with values) to be modified.
  1334.  
  1335.  
  1336. 5.9.2.  getAttribute
  1337.  
  1338.    public LDAPAttribute getAttribute()
  1339.  
  1340.    Returns the attribute (possibly with values) to be modified.
  1341.  
  1342.  
  1343. 5.9.3.  getOp
  1344.  
  1345.    public int getOp()
  1346.  
  1347.    Returns the type of modification specified by this object.
  1348.  
  1349.  
  1350. 5.10.  public class LDAPModificationSet extends Object
  1351.  
  1352. A collection of modifications to be made to the attributes of a single
  1353. entry.
  1354.  
  1355.  
  1356. 5.10.1.  Constructors
  1357.  
  1358.    public LDAPModificationSet()
  1359.  
  1360.    Constructs a new, empty set of modifications.
  1361.  
  1362.  
  1363. 5.10.2.  add
  1364.  
  1365.    public synchronized void add(int op,
  1366.                                 LDAPAttribute attr)
  1367.  
  1368.    Specifies another modification to be added to the set of modifica-
  1369.    tions.
  1370.  
  1371.    Parameters are:
  1372.  
  1373.    op            The type of modification to make, as described for
  1374.                  LDAPModification.
  1375.  
  1376.  
  1377.  
  1378. Expires 10/97                                                  [Page 23]
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384. JAVA LDAP API                                                 April 1997
  1385.  
  1386.  
  1387.    attr          The attribute (possibly with values) to be modified.
  1388.  
  1389.  
  1390. 5.10.3.  elementAt
  1391.  
  1392.    public LDAPModification elementAt(int index)
  1393.                                throws ArrayIndexOutOfBoundsException
  1394.  
  1395.    Retrieves a particular LDAPModification object at the position speci-
  1396.    fied by the index.
  1397.  
  1398.    Parameters are:
  1399.  
  1400.    index         Index of the modification to get.
  1401.  
  1402.  
  1403. 5.10.4.  remove
  1404.  
  1405.    public synchronized void remove(String name)
  1406.  
  1407.    Removes the first attribute with the specified name in the set of
  1408.    modifications.
  1409.  
  1410.    Parameters are:
  1411.  
  1412.    name          Name of the attribute to be removed.
  1413.  
  1414.  
  1415. 5.10.5.  removeElementAt
  1416.  
  1417.    public void removeElementAt(int index)
  1418.                                throws ArrayIndexOutOfBoundsException
  1419.  
  1420.    Removes a particular LDAPModification object at the position speci-
  1421.    fied by the index.
  1422.  
  1423.  
  1424. index         Index of the modification to remove.
  1425.  
  1426.  
  1427. 5.10.6.  size
  1428.  
  1429.    public int size()
  1430.  
  1431.    Retrieves the number of LDAPModification objects in this set.
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438. Expires 10/97                                                  [Page 24]
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444. JAVA LDAP API                                                 April 1997
  1445.  
  1446.  
  1447. 5.11.  public class LDAPRebindAuth extends Object
  1448.  
  1449. Represents information used to authenticate the client in cases where
  1450. the client follows referrals automatically.
  1451.  
  1452.  
  1453. 5.11.1.  Constructors
  1454.  
  1455.    public LDAPRebindAuth(String dn,
  1456.                          String password)
  1457.  
  1458.    Constructs information that is used by the client for authentication
  1459.    when following referrals automatically.
  1460.  
  1461.  
  1462. 5.11.2.  getDN
  1463.  
  1464.    public String getDN()
  1465.  
  1466.    Returns the distinguished name to be used for reauthentication on
  1467.    automatic referral following.
  1468.  
  1469.  
  1470. 5.11.3.  getPassword
  1471.  
  1472.    public String getPassword()
  1473.  
  1474.    Returns the password to be used for reauthentication on automatic
  1475.    referral following.
  1476.  
  1477.  
  1478. 5.12.  public class LDAPReferralException extends LDAPException
  1479.  
  1480. This exception, derived from LDAPException, is thrown when a server
  1481. returns a referral and automatic referral following has not been
  1482. enabled.
  1483.  
  1484.  
  1485. 5.12.1.  Constructors
  1486.  
  1487.    public LDAPReferralException()
  1488.  
  1489.    Constructs a default exception with no specific error information.
  1490.  
  1491.  
  1492.    public LDAPReferralException(String message)
  1493.  
  1494.    Constructs a default exception with a specified string as additional
  1495.  
  1496.  
  1497.  
  1498. Expires 10/97                                                  [Page 25]
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504. JAVA LDAP API                                                 April 1997
  1505.  
  1506.  
  1507.    information. This form is used for lower-level errors.
  1508.  
  1509.  
  1510.    public LDAPReferralException(String message,
  1511.                                 int resultCode,
  1512.                                 String serverMessage)
  1513.  
  1514.    Parameters are:
  1515.  
  1516.    message       The additional error information.
  1517.  
  1518.    resultCode    The result code returned
  1519.  
  1520.    serverMessage Error message specifying additional information from
  1521.                  the server.
  1522.  
  1523.  
  1524. 5.12.2.  getURLs
  1525.  
  1526.    public LDAPUrl[] getURLs()
  1527.  
  1528.    Gets the list of referrals (LDAP URLs to other servers) returned by
  1529.    the LDAP server. This exception is only thrown, and therefor the URL
  1530.    list only available, if automatic referral following is not enabled.
  1531.  
  1532.  
  1533. 5.13.  public class LDAPSearchConstraints extends Object
  1534.  
  1535. A set of options to control a search operation. There is always an LDAP-
  1536. SearchConstraints associated with an LDAPConnection object; it's values
  1537. can be changed with LDAPConnection.setOption, or overridden by passing
  1538. an LDAPSearchConstraints object to the search operation.
  1539.  
  1540.  
  1541. 5.13.1.  Constructors
  1542.  
  1543.    public LDAPSearchConstraints()
  1544.  
  1545.    Constructs an LDAPSearchConstraints object that specifies the default
  1546.    set of search constraints.
  1547.  
  1548.  
  1549.    public LDAPSearchConstraints(int msLimit,
  1550.                                 boolean dereference,
  1551.                                 int maxResults,
  1552.                                 boolean doReferrals,
  1553.                                 int batchSize,
  1554.                                 LDAPRebind rebind_proc,
  1555.  
  1556.  
  1557.  
  1558. Expires 10/97                                                  [Page 26]
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564. JAVA LDAP API                                                 April 1997
  1565.  
  1566.  
  1567.                                 int hop_limit)
  1568.  
  1569.    Constructs a new LDAPSearchConstraints object and allows specifying
  1570.    the search constraints in that object.
  1571.  
  1572.    Parameters are:
  1573.  
  1574.    msLimit       Maximum time in milliseconds to wait for results (0 by
  1575.                  default, which means that there is no maximum time
  1576.                  limit).
  1577.  
  1578.    dereference   Specify true to follow ("dereference") aliases, or
  1579.                  false to not follow aliases (true by default).
  1580.  
  1581.    maxResults    Maximum number of search results to return (1000 by
  1582.                  default).
  1583.  
  1584.    doReferrals   Specify true to follow referrals automatically, or
  1585.                  false to throw an LDAPReferralException error if the
  1586.                  server sends back a referral (false by default)
  1587.  
  1588.    batchSize     Specify the number of results to block on during
  1589.                  enumeration. 0 means to block until all results are in
  1590.                  (1 by default).
  1591.  
  1592.    rebind_proc   Specifies an object of the class that implements the
  1593.                  LDAPRebind interface. The object will be used when the
  1594.                  client follows referrals automatically. The object pro-
  1595.                  vides a method for getting the distinguished name and
  1596.                  password used to authenticate to another LDAP server
  1597.                  during a referral. This field is null by default.
  1598.  
  1599.    hop_limit     Maximum number of referrals to follow in a sequence
  1600.                  when attempting to resolve a request, when doing
  1601.                  automatic referral following.
  1602.  
  1603.  
  1604. 5.13.2.  getBatchSize
  1605.  
  1606.    public int getBatchSize()
  1607.  
  1608.    Returns the suggested number of results to block on during enumera-
  1609.    tion of serach results. This should be 0 if intermediate results are
  1610.    not needed, and 1 if results are to be processed as they come in.
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618. Expires 10/97                                                  [Page 27]
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624. JAVA LDAP API                                                 April 1997
  1625.  
  1626.  
  1627. 5.13.3.  getDereference
  1628.  
  1629.    public boolean getDereference()
  1630.  
  1631.    Specifies whether or not aliases should be dereferenced. Returns true
  1632.    if aliases are to be dereferenced for any operation, or false if
  1633.    aliases should not be dereferenced.
  1634.  
  1635. NH 3 getHopLimit
  1636.  
  1637.    public int getHopLimit()
  1638.  
  1639.    Returns the maximum number of hops to follow during automatic refer-
  1640.    ral following.
  1641.  
  1642.  
  1643. 5.13.4.  getMaxResults
  1644.  
  1645.    public int getMaxResults()
  1646.  
  1647.    Returns the maximum number of search results to be returned; 0 means
  1648.    no limit.
  1649.  
  1650.  
  1651. 5.13.5.  getRebindProc
  1652.  
  1653.    public LDAPRebind getRebindProc()
  1654.  
  1655.    Returns the object that provides the method for getting authentica-
  1656.    tion information.
  1657.  
  1658.  
  1659. 5.13.6.  getReferrals
  1660.  
  1661.    public boolean getReferrals()
  1662.  
  1663.    Specifies whether nor not referrals are followed automatically.
  1664.    Returns true if referrals are to be followed automatically, or false
  1665.    if referrals throw an LDAPReferralException.
  1666.  
  1667.  
  1668. 5.13.7.  getTimeLimit
  1669.  
  1670.    public int getTimeLimit()
  1671.  
  1672.    Returns the maximum number of milliseconds to wait for any operation
  1673.    under these search constraints. If 0, there is no maximum time limit
  1674.    on waiting for the operation results.
  1675.  
  1676.  
  1677.  
  1678. Expires 10/97                                                  [Page 28]
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684. JAVA LDAP API                                                 April 1997
  1685.  
  1686.  
  1687. 5.13.8.  setBatchSize
  1688.  
  1689.    public void setBatchSize(int batchSize)
  1690.  
  1691.    Sets the suggested number of results to block on during enumeration
  1692.    of search results. This should be 0 if intermediate results are not
  1693.    needed, and 1 if results are to be processed as they come in.  The
  1694.    default is 1.
  1695.  
  1696.    Parameters are:
  1697.  
  1698.    batchSize     Blocking size on search enumerations.
  1699.  
  1700.  
  1701. 5.13.9.  setDereference
  1702.  
  1703.    public void setDereference(boolean dereference)
  1704.  
  1705.    Sets a preference indicating whether or not aliases should be
  1706.    dereferenced.  true if aliases are to be dereferenced for any opera-
  1707.    tion, false if aliases should not be dereferenced.
  1708.  
  1709.    Parameters are:
  1710.  
  1711.    dereference   true to follow aliases.
  1712.  
  1713.  
  1714. 5.13.10.  setHopLimit
  1715.  
  1716.    public void setHopLimit(int hop_limit)
  1717.  
  1718.    Sets the maximum number of hops to follow in sequence during
  1719.    automatic referral following. The default is 5.
  1720.  
  1721.    Parameters are:
  1722.  
  1723.    hop_limit     Maximum number of chained referrals to follow automati-
  1724.                  cally.
  1725.  
  1726.  
  1727. 5.13.11.  setMaxResults
  1728.  
  1729.    public void setMaxResults(int maxResults)
  1730.  
  1731.    Sets the maximum number of search results to be returned; 0 means no
  1732.    limit.  The default is 1000.
  1733.  
  1734.    Parameters are:
  1735.  
  1736.  
  1737.  
  1738. Expires 10/97                                                  [Page 29]
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744. JAVA LDAP API                                                 April 1997
  1745.  
  1746.  
  1747.    maxResults    Maxumum number of search results to return.
  1748.  
  1749.  
  1750. 5.13.12.  setRebindProc
  1751.  
  1752.    public void setRebindProc(LDAPRebind rebind_proc)
  1753.  
  1754.    Specifies the object that provides the method for getting authentica-
  1755.    tion information. The default is null. If referrals is set to true,
  1756.    and the rebindProc is null, referrals will be followed with anonymous
  1757.    (= no) authentication.
  1758.  
  1759.    Parameters are:
  1760.  
  1761.    rebind_proc   An object that implements LDAPRebind.
  1762.  
  1763.  
  1764. 5.13.13.  setReferrals
  1765.  
  1766.    public void setReferrals(boolean doReferrals)
  1767.  
  1768.    Specifies whether nor not referrals are followed automatically, or if
  1769.    referrals throw an LDAPReferralException. The default is false.
  1770.  
  1771.    Parameters are:
  1772.  
  1773.    doReferrals   True to follow referrals automatically.
  1774.  
  1775.  
  1776. 5.13.14.  setTimeLimit
  1777.  
  1778.    public void setTimeLimit(int msLimit)
  1779.  
  1780.    Sets the maximum number of milliseconds to wait for any operation
  1781.    under these search constraints. If 0, there is no maximum time limit
  1782.    on waiting for the operation results.
  1783.  
  1784.    Parameters are:
  1785.  
  1786.    msLimit       Maximum milliseconds to wait.
  1787.  
  1788.  
  1789. 5.14.  public class LDAPSearchResults extends Object
  1790.  
  1791. An LDAPSearchResults object is returned from a search operation. It
  1792. implements Enumeration, thereby providing access to all entries
  1793. retrieved during the operation.
  1794.  
  1795.  
  1796.  
  1797.  
  1798. Expires 10/97                                                  [Page 30]
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804. JAVA LDAP API                                                 April 1997
  1805.  
  1806.  
  1807. 5.14.1.  hasMoreElements
  1808.  
  1809.    public boolean hasMoreElements()
  1810.  
  1811.    Specifies whether or not there are more search results in the
  1812.    enumeration. If true, there are more search results.
  1813.  
  1814.  
  1815. 5.14.2.  next
  1816.  
  1817.    public LDAPEntry next()
  1818.  
  1819.    Returns the next result in the enumeration as an LDAPEntry.
  1820.  
  1821.  
  1822. 5.14.3.  nextElement
  1823.  
  1824.    public Object nextElement()
  1825.  
  1826.    Returns the next result in the enumeration as an Object. This the
  1827.    default implementation of Enumeration.nextElement().
  1828.  
  1829.  
  1830. 5.14.4.  sort
  1831.  
  1832.    public void sort(LDAPEntryComparator comp)
  1833.  
  1834.    Sorts all entries in the results using the provided comparison
  1835.    object. If the object has been partially or completely enumerated,
  1836.    only remaining elements are sorted. Sorting the results requires that
  1837.    they all be present. This implies that
  1838.    LDAPSearchResults.nextElement() will always block until all results
  1839.    have been retrieved, after a sort operation.
  1840.  
  1841.    The LDAPCompareAttrNames class is provided to support the common need
  1842.    to collate by a single or multiple attribute values, in ascending
  1843.    order.  Examples are:
  1844.  
  1845.        res.sort(new LDAPCompareAttrNames("cn"));
  1846.  
  1847.        String[] attrNames = { "sn", "givenname" };
  1848.        res.sort(new LDAPCompareAttrNames(attrNames));
  1849.  
  1850.    Parameters are:
  1851.  
  1852.    comp          An object that implements the LDAPEntryComparator
  1853.                  interface to compare two objects of type LDAPEntry.
  1854.  
  1855.  
  1856.  
  1857.  
  1858. Expires 10/97                                                  [Page 31]
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864. JAVA LDAP API                                                 April 1997
  1865.  
  1866.  
  1867. 5.15.  public class LDAPSecurityException extends LDAPException
  1868.  
  1869. This exception, derived from LDAPException, is thrown when a server
  1870. returns an error indicating a security violation.
  1871.  
  1872.  
  1873. 5.15.1.  Constructors
  1874.  
  1875.    public LDAPSecurityException()
  1876.  
  1877.    Constructs a default exception with no specific error information.
  1878.  
  1879.  
  1880.    public LDAPSecurityException(String message)
  1881.  
  1882.    Constructs a default exception with a specified string as additional
  1883.    information. This form is used for lower-level errors.
  1884.  
  1885.  
  1886.    public LDAPSecurityException(String message,
  1887.                                 int resultCode,
  1888.                                 String serverMessage)
  1889.  
  1890.    Parameters are:
  1891.  
  1892.    message       The additional error information.
  1893.  
  1894.    resultCode    The result code returned
  1895.  
  1896.    serverMessage Error message specifying additional information from
  1897.                  the server.
  1898.  
  1899.  
  1900. 5.16.  public interface LDAPSocketFactory
  1901.  
  1902. Used to construct a socket connection for use in an LDAPConnection.  An
  1903. implementation of this interface may, for example, provide an SSLSocket
  1904. connected to a secure server.
  1905.  
  1906.  
  1907. 5.16.1.  makeSocket
  1908.  
  1909.    public Socket makeSocket(String host, int port)
  1910.                             throws IOException, UnknownHostException
  1911.  
  1912.    Returns a socket connected using the provided host name and port
  1913.    number.
  1914.  
  1915.  
  1916.  
  1917.  
  1918. Expires 10/97                                                  [Page 32]
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924. JAVA LDAP API                                                 April 1997
  1925.  
  1926.  
  1927.    There may be additional makeSocket methods defined when interfaces to
  1928.    establish SSL and SASL authentication in the java environment have
  1929.    been standardized.
  1930.  
  1931.    Parameters are:
  1932.  
  1933.    host          Contains a hostname or dotted string representing the
  1934.                  IP address of a host running an LDAP server to connect
  1935.                  to.
  1936.  
  1937.    port          Contains the TCP or UDP port number to connect to or
  1938.                  contact. The default LDAP port is 389.
  1939.  
  1940.  
  1941. 5.17.  public class LDAPUrl extends Object
  1942.  
  1943. Encapsulates parameters of an LDAP Url query, as defined in [8].  An
  1944. LDAPUrl object can be passed to LDAPConnection.search to retrieve search
  1945. results.
  1946.  
  1947.  
  1948. 5.17.1.  Constructors
  1949.  
  1950.    public LDAPUrl(String url) throws MalformedURLException
  1951.  
  1952.    Constructs a URL object with the specified string as URL.
  1953.  
  1954.  
  1955.    public LDAPUrl(String host,
  1956.                   int port,
  1957.                   String dn)
  1958.  
  1959.    Constructs with the specified host, port, and DN. This form is used
  1960.    to create URL references to a particular object in the directory.
  1961.  
  1962.  
  1963.    public LDAPUrl(String host,
  1964.                   int port,
  1965.                   String dn,
  1966.                   String attrNames[],
  1967.                   int scope,
  1968.                   String filter)
  1969.  
  1970.    Constructs a full-blown LDAP URL to specify an LDAP search operation.
  1971.  
  1972.    Parameters are:
  1973.  
  1974.    url           An explicit URL string, e.g.
  1975.  
  1976.  
  1977.  
  1978. Expires 10/97                                                  [Page 33]
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984. JAVA LDAP API                                                 April 1997
  1985.  
  1986.  
  1987.                  "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn,sn?sub?
  1988.                  (objectclass=inetOrgPerson)".
  1989.  
  1990.    host          Host name of LDAP server, or null for "nearest
  1991.                  X.500/LDAP".
  1992.  
  1993.    port          Port number for LDAP server (use
  1994.                  LDAPConnection.DEFAULT_PORT for default port).
  1995.  
  1996.    dn            Distinguished name of object to fetch.
  1997.  
  1998.    attrNames     Names of attributes to retrieve. null for all attri-
  1999.                  butes.
  2000.  
  2001.    scope         Depth of search (in DN namespace). Use one of
  2002.                  SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPv2.
  2003.  
  2004.  
  2005. 5.17.2.  decode
  2006.  
  2007.    public static String decode(String URLEncoded) throws MalformedURLEx-
  2008.    ception
  2009.  
  2010.    Decodes a URL-encoded string. Any occurences of %HH are decoded to
  2011.    the hex value represented. However, this routine does NOT decode "+"
  2012.    into " ". See [10] for details on URL encoding/decoding.
  2013.  
  2014.    Parameters are:
  2015.  
  2016.    URLEncoded    String to decode.
  2017.  
  2018.  
  2019. 5.17.3.  encode
  2020.  
  2021.    public static String encode(String toEncode)
  2022.  
  2023.    Encodes an arbitrary string. Any illegal characters are encoded as
  2024.    %HH.  However, this routine does NOT decode "+" into " ".
  2025.  
  2026.    Parameters are:
  2027.  
  2028.    toEncode      String to encode.
  2029.  
  2030.  
  2031. 5.17.4.  getAttributes
  2032.  
  2033.    public String[] getAttributeArray()
  2034.  
  2035.  
  2036.  
  2037.  
  2038. Expires 10/97                                                  [Page 34]
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044. JAVA LDAP API                                                 April 1997
  2045.  
  2046.  
  2047.    Return an array of attribute names specified in the URL
  2048.  
  2049.  
  2050. 5.17.5.  getAttributes
  2051.  
  2052.    public Enumeration getAttributes()
  2053.  
  2054.    Return an Enumerator for the attribute names specified in the URL
  2055.  
  2056.  
  2057. 5.17.6.  getDN
  2058.  
  2059.    public String getDN()
  2060.  
  2061.    Return the distinguished name encapsulated in the URL.
  2062.  
  2063.  
  2064. 5.17.7.  getFilter
  2065.  
  2066.    public String getFilter()
  2067.  
  2068.    Returns the search filter [8], or the default filter -
  2069.    (objectclass=*) - if none was specified.
  2070.  
  2071.  
  2072. 5.17.8.  getHost
  2073.  
  2074.    public String getHost()
  2075.  
  2076.    Returns the host name of the LDAP server to connect to.
  2077.  
  2078. 5.17.9.  getPort
  2079.  
  2080.    public int getPort()
  2081.  
  2082.    Returns the port number of the LDAP server to connect to.
  2083.  
  2084.  
  2085. 5.17.10.  getUrl
  2086.  
  2087.    public String getUrl()
  2088.  
  2089.    Returns a valid string representation of this LDAP URL.
  2090.  
  2091.  
  2092. 5.18.  public interface LDAPv2
  2093.  
  2094. As a mechanism to support planned and future LDAP protocol extensions,
  2095.  
  2096.  
  2097.  
  2098. Expires 10/97                                                  [Page 35]
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104. JAVA LDAP API                                                 April 1997
  2105.  
  2106.  
  2107. functionality is defined in an interface - LDAPv2, corresponding to ver-
  2108. sion 2 of the LDAP protocol. LDAPConnection implements LDAPv2, and will
  2109. in future releases also implement LDAPv3, which will define the addi-
  2110. tional functionality implied by version 3 of the LDAP protocol. Applica-
  2111. tions can test for support of these protocol levels in a given package
  2112. with the instanceof operator.
  2113.  
  2114. 5.18.1.  add
  2115.  
  2116.    public void add(LDAPEntry entry) throws LDAPException
  2117.  
  2118.    Adds an entry to the directory.
  2119.  
  2120.    Parameters are:
  2121.  
  2122.    entry         LDAPEntry object specifying the distinguished name and
  2123.                  attributes of the new entry.
  2124.  
  2125.  
  2126. 5.18.2.  authenticate
  2127.  
  2128.    public void authenticate(String dn,
  2129.                             String passwd)
  2130.                             throws LDAPException
  2131.  
  2132.    Authenticates to the LDAP server (that the object is currently con-
  2133.    nected to) using the specified name and password.  If the object has
  2134.    been disconnected from an LDAP server, this method attempts to recon-
  2135.    nect to the server. If the object had already authenticated, the old
  2136.    authentication is discarded.
  2137.  
  2138.    Parameters are:
  2139.  
  2140.    dn            If non-null and non-empty, specifies that the connec-
  2141.                  tion and all operations through it should be authenti-
  2142.                  cated with dn as the distinguished name.
  2143.  
  2144.    passwd        If non-null and non-empty, specifies that the connec-
  2145.                  tion and all operations through it should be authenti-
  2146.                  cated with dn as the distinguished name and passwd as
  2147.                  password.
  2148.  
  2149.  
  2150. 5.18.3.  compare
  2151.  
  2152.    public boolean compare(String dn,
  2153.                           LDAPAttribute attr)
  2154.                           throws LDAPException
  2155.  
  2156.  
  2157.  
  2158. Expires 10/97                                                  [Page 36]
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164. JAVA LDAP API                                                 April 1997
  2165.  
  2166.  
  2167.    Checks to see if an entry contains an attribute with a specified
  2168.    value.  Returns true if the entry has the value, and false if the
  2169.    entry does not have the value or the attribute.
  2170.  
  2171.    Parameters are:
  2172.  
  2173.    dn            The distinguished name of the entry to use in the com-
  2174.                  parison.
  2175.  
  2176.    attr          The attribute to compare against the entry. The method
  2177.                  checks to see if the entry has an attribute with the
  2178.                  same name and value as this attribute.
  2179.  
  2180.  
  2181. 5.18.4.  connect
  2182.  
  2183.    public void connect(String host,
  2184.                        int port)
  2185.                        throws LDAPException
  2186.  
  2187.    Connects to the specified host and port. If this LDAPConnection
  2188.    object represents an open connection, the connection is closed first
  2189.    before the new connection is opened.  At this point there is no
  2190.    authentication, and any operations will be conducted as an anonymous
  2191.    client.
  2192.  
  2193.  
  2194.    public void connect(String host,
  2195.                        int port,
  2196.                        String dn,
  2197.                        String passwd)
  2198.                        throws LDAPException
  2199.  
  2200.    Connects to the specified host and port and uses the specified DN and
  2201.    password to authenticate to the server. If this LDAPConnection object
  2202.    represents an open connection, the connection is closed first before
  2203.    the new connection is opened. This is equivalent to connect(host,
  2204.    port) followed by authenticate(dn, passwd).
  2205.  
  2206.    Parameters are:
  2207.  
  2208.    host          Contains a hostname or dotted string representing the
  2209.                  IP address of a host running an LDAP server to connect
  2210.                  to.
  2211.  
  2212.    port          Contains the TCP or UDP port number to connect to or
  2213.                  contact. The default LDAP port is 389.
  2214.  
  2215.  
  2216.  
  2217.  
  2218. Expires 10/97                                                  [Page 37]
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224. JAVA LDAP API                                                 April 1997
  2225.  
  2226.  
  2227.    dn            If non-null and non-empty, specifies that the connec-
  2228.                  tion and all operations through it should be authenti-
  2229.                  cated with dn as the distinguished name.
  2230.  
  2231.    passwd        If non-null and non-empty, specifies that the connec-
  2232.                  tion and all operations through it should be authenti-
  2233.                  cated with dn as the distinguished name and passwd as
  2234.                  password.
  2235.  
  2236.  
  2237. 5.18.5.  delete
  2238.  
  2239.    public void delete(String dn) throws LDAPException
  2240.  
  2241.    Deletes the entry for the specified DN from the directory.
  2242.  
  2243.    Parameters are:
  2244.  
  2245.    dn            Distinguished name of the entry to modify.
  2246.  
  2247.  
  2248. 5.18.6.  disconnect
  2249.  
  2250.    public synchronized void disconnect() throws LDAPException
  2251.  
  2252.    Disconnects from the LDAP server. Before the object can perform LDAP
  2253.    operations again, it must reconnect to the server by calling connect.
  2254.  
  2255.  
  2256. 5.18.7.  getOption
  2257.  
  2258.    public Object getOption(int option) throws LDAPException
  2259.  
  2260.    Returns the value of the specified option for this object.
  2261.  
  2262.    Parameters are:
  2263.  
  2264.  
  2265.    option        See LDAPConnection.setOption for a description of valid
  2266.                  options.
  2267.  
  2268.  
  2269. 5.18.8.  modify
  2270.  
  2271.    public void modify(String dn,
  2272.                       LDAPModification mod)
  2273.                       throws LDAPException
  2274.  
  2275.  
  2276.  
  2277.  
  2278. Expires 10/97                                                  [Page 38]
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284. JAVA LDAP API                                                 April 1997
  2285.  
  2286.  
  2287.    Makes a single change to an existing entry in the directory (for
  2288.    example, changes the value of an attribute, adds a new attribute
  2289.    value, or removes an existing attribute value).
  2290.  
  2291.    The LDAPModification object specifies both the change to be made and
  2292.    the LDAPAttribute value to be changed.
  2293.  
  2294.  
  2295.    public void modify(String dn,
  2296.                       LDAPModificationSet mods)
  2297.                       throws LDAPException
  2298.  
  2299.    Makes a set of changes to an existing entry in the directory (for
  2300.    example, changes attribute values, adds new attribute values, or
  2301.    removes existing attribute values).
  2302.  
  2303.    Parameters are:
  2304.  
  2305.    dn            Distinguished name of the entry to modify.
  2306.  
  2307.    mod           A single change to be made to the entry.
  2308.  
  2309.    mods          A set of changes to be made to the entry.
  2310.  
  2311.  
  2312. 5.18.9.  read
  2313.  
  2314.    public LDAPEntry read(String dn) throws LDAPException
  2315.  
  2316.    Reads the entry for the specified distiguished name (DN) and
  2317.    retrieves all attributes for the entry.
  2318.  
  2319.  
  2320.    public LDAPEntry read(String dn,
  2321.                          String attrs[])
  2322.                          throws LDAPException
  2323.  
  2324.    Reads the entry for the specified distinguished name (DN) and
  2325.    retrieves only the specified attributes from the entry.
  2326.  
  2327.    Parameters are:
  2328.  
  2329.    dn            Distinguished name of the entry to retrieve.
  2330.  
  2331.    attrs         Names of attributes to retrieve.
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338. Expires 10/97                                                  [Page 39]
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344. JAVA LDAP API                                                 April 1997
  2345.  
  2346.  
  2347. 5.18.10.  rename
  2348.  
  2349.    public void rename(String dn,
  2350.                       String newRdn,
  2351.                       boolean deleteOldRdn)
  2352.                       throws LDAPException
  2353.  
  2354.    Renames an existing entry in the directory.
  2355.  
  2356.    Parameters are:
  2357.  
  2358.    dn            Current distinguished name of the entry.
  2359.  
  2360.    newRdn        New relative distinguished name for the entry.
  2361.  
  2362.    deleteOldRdn  If true, the old name is not retained as an attribute
  2363.                  value.
  2364.  
  2365.  
  2366. 5.18.11.  search
  2367.  
  2368.    public LDAPSearchResults search(String base,
  2369.                                    int scope,
  2370.                                    String filter,
  2371.                                    String attrs[],
  2372.                                    boolean attrsOnly)
  2373.                                    throws LDAPException
  2374.  
  2375.    Performs the search specified by the parameters.
  2376.  
  2377.  
  2378.    public LDAPSearchResults search(String base,
  2379.                                    int scope,
  2380.                                    String filter,
  2381.                                    String attrs[],
  2382.                                    boolean attrsOnly,
  2383.                                    LDAPSearchConstraints cons)
  2384.                                    throws LDAPException
  2385.  
  2386.    Performs the search specified by the parameters, also allowing
  2387.    specification of constraints for the search (such as the maximum
  2388.    number of entries to find or the maximum time to wait for search
  2389.    results).
  2390.  
  2391.    As part of the search constraints, the function allows specifying
  2392.    whether or not the results are to be delivered all at once or in
  2393.    smaller batches. If specified that the results are to be delivered in
  2394.    smaller batches, each iteration blocks only until the next batch of
  2395.  
  2396.  
  2397.  
  2398. Expires 10/97                                                  [Page 40]
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404. JAVA LDAP API                                                 April 1997
  2405.  
  2406.  
  2407.    results is returned.
  2408.  
  2409.    Parameters are:
  2410.  
  2411.    base          The base distinguished name to search from.
  2412.  
  2413.    scope         The scope of the entries to search. The following are
  2414.                  the valid options:
  2415.  
  2416.  
  2417.                  LDAPv2.SCOPE_BASE Search only the base DN
  2418.  
  2419.                  LDAPv2.SCOPE_ONE  Search only entries under the base DN
  2420.  
  2421.                  LDAPv2.SCOPE_SUB  Search the base DN and all entries
  2422.                                    within its subtree
  2423.  
  2424.    filter        Search filter specifying the search criteria, as
  2425.                  defined in [3].
  2426.  
  2427.    attrs         Names of attributes to retrieve.
  2428.  
  2429.    attrsOnly     If true, returns the names but not the values of the
  2430.                  attributes found.  If false, returns the names and
  2431.                  values for attributes found
  2432.  
  2433.    cons          Constraints specific to the search.
  2434.  
  2435.  
  2436. 5.18.12.  setOption
  2437.  
  2438.    public void setOption(int option,
  2439.                          Object value)
  2440.                          throws LDAPException
  2441.  
  2442.    Sets the value of the specified option for this LDAPConnection
  2443.    object.
  2444.  
  2445.    See LDAPConnection.setOption for an implementation.
  2446.  
  2447.  
  2448. 6.  Security Considerations
  2449.  
  2450. LDAP supports security through protocol-level authentication, using
  2451. clear-text passwords or other more secure mechanisms.  It also supports
  2452. running over SSL, which provides strong security at the transport layer.
  2453. This draft does not cover SSL implementations, although it identifies a
  2454. mechanism for supplying one, through the LDAPSocketFactory interface.
  2455.  
  2456.  
  2457.  
  2458. Expires 10/97                                                  [Page 41]
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464. JAVA LDAP API                                                 April 1997
  2465.  
  2466.  
  2467. 7.  Acknowledgements
  2468.  
  2469. The proposed API was defined in collaboration with Tim Howes and Mark
  2470. Smith of Netscape Communications Corp., and Thomas Kwan and Stephan Gud-
  2471. mundson of NCware Technologies Corp.
  2472.  
  2473. 8.  Bibliography
  2474.  
  2475. [1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
  2476.      X.520.
  2477.  
  2478. [2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
  2479.      Access Protocol: Standard and Pilot Attribute Definitions", Inter-
  2480.      net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996
  2481.  
  2482. [3]  T. Howes, "A String Representation of LDAP Search Filters," RFC
  2483.      1960, June 1996.
  2484.  
  2485. [4]  S. Kille, "A String Representation of Distinguished Names," RFC
  2486.      1779, March 1995.
  2487.  
  2488. [5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
  2489.      ing," RFC 1781, March 1995.
  2490.  
  2491. [7]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
  2492.      (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt, March
  2493.      1997.
  2494.  
  2495. [8]  T. Howes, M. Smith, "An LDAP URL Format", RFC 1959, June 1996.
  2496.  
  2497. [9]  T. Howes, M. Smith, "The LDAP Application Program Interface", RFC
  2498.      1823, August 1995.
  2499.  
  2500. [10] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource Loca-
  2501.      tors (URL)", RFC 1738, December 1994.
  2502.  
  2503. [11] W. Yeong, T. Howes, S. Kille, "Lightweight Directory Access Proto-
  2504.      col", RFC 1777, March 1995.
  2505.  
  2506. 9.  Authors' Addresses
  2507.  
  2508.    Rob Weltman
  2509.    Netscape Communications Corp.
  2510.    501 E. Middlefield Rd.
  2511.    Mountain View, CA 94043
  2512.    USA
  2513.    +1 415 937-3301
  2514.    rweltman@netscape.com
  2515.  
  2516.  
  2517.  
  2518. Expires 10/97                                                  [Page 42]
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524. JAVA LDAP API                                                 April 1997
  2525.  
  2526.  
  2527.    Tim Howes
  2528.    Netscape Communications Corp.
  2529.    501 E. Middlefield Rd.
  2530.    Mountain View, CA 94043
  2531.    USA
  2532.    +1 415 937-3419
  2533.    howes@netscape.com
  2534.  
  2535.    Mark Smith
  2536.    Netscape Communications Corp.
  2537.    501 E. Middlefield Rd.
  2538.    Mountain View, CA 94043
  2539.    USA
  2540.    +1 313 937-3477
  2541.    mcs@netscape.com
  2542.  
  2543.    Thomas Kwan
  2544.    NCware Technologies Corp.
  2545.    15600 NE 8th Suite B1#118
  2546.    Bellevue WA 98008
  2547.    USA
  2548.    +1 206 323-5579
  2549.    thomask@ncware.com
  2550.  
  2551.    Stephan Gudmundson
  2552.    NCware Technologies Corp.
  2553.    15600 NE 8th Suite B1#118
  2554.    Bellevue WA 98008
  2555.    USA
  2556.    +1 206 323-5579
  2557.    stephang@ncware.com
  2558.  
  2559. 10.  Appendix A - Sample java LDAP program
  2560.  
  2561.    import netscape.ldap.*;
  2562.    import java.util.*;
  2563.  
  2564.    public class Search {
  2565.        public static void main( String[] args )
  2566.        {
  2567.            try {
  2568.                LDAPConnection ld = new LDAPConnection();
  2569.                /* Connect to server */
  2570.                String MY_HOST = "localhost";
  2571.                int MY_PORT = 389;
  2572.                ld.connect( MY_HOST, MY_PORT );
  2573.  
  2574.                /* authenticate to the directory as nobody */
  2575.  
  2576.  
  2577.  
  2578. Expires 10/97                                                  [Page 43]
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584. JAVA LDAP API                                                 April 1997
  2585.  
  2586.  
  2587.                /* This is not really necessary if explicit authentication
  2588.                   is not desired, because there is already anonymous
  2589.                   authentication at connect time */
  2590.                ld.authenticate( "", "" );
  2591.  
  2592.                /* search for all entries with surname of Jensen */
  2593.                String MY_FILTER = "sn=Jensen";
  2594.                String MY_SEARCHBASE = "o=Ace Industry, c=US";
  2595.  
  2596.                LDAPSearchConstraints cons = ld.getSearchConstraints();
  2597.                /* Setting the batchSize to one will cause the result
  2598.                   enumeration below to block on one result at a time,
  2599.                   allowing us to update a list or do other things as
  2600.                   results come in. */
  2601.                /* We could set it to 0 if we just wanted to get all
  2602.                   results and were willing to block until then */
  2603.                cons.setBatchSize( 1 );
  2604.                LDAPSearchResults res = ld.search( MY_SEARCHBASE,
  2605.                                                    LDAPConnection.SCOPE_ONE,
  2606.                                                    MY_FILTER,
  2607.                                                    null,
  2608.                                                    false,
  2609.                                                    cons );
  2610.  
  2611.                /* Loop on results until finished */
  2612.                while ( res.hasMoreElements() ) {
  2613.  
  2614.                    /* Next directory entry */
  2615.                    LDAPEntry findEntry = (LDAPEntry)res.nextElement();
  2616.                    System.out.println( findEntry.getDN() );
  2617.  
  2618.                    /* Get the attributes of the entry */
  2619.                    LDAPAttributeSet findAttrs = findEntry.getAttributeSet();
  2620.                    Enumeration enumAttrs = findAttrs.getAttributes();
  2621.                    System.out.println( "Attributes: " );
  2622.                    /* Loop on attributes */
  2623.                    while ( enumAttrs.hasMoreElements() ) {
  2624.                        LDAPAttribute anAttr =
  2625.                            (LDAPAttribute)enumAttrs.nextElement();
  2626.                        String attrName = anAttr.getName();
  2627.                        System.out.println( "" + attrName );
  2628.                        /* Loop on values for this attribute */
  2629.                        Enumeration enumVals = anAttr.getStringValues();
  2630.                        while ( enumVals.hasMoreElements() ) {
  2631.                            String aVal = ( String )enumVals.nextElement();
  2632.                            System.out.println( "" + aVal );
  2633.                        }
  2634.                    }
  2635.  
  2636.  
  2637.  
  2638. Expires 10/97                                                  [Page 44]
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644. JAVA LDAP API                                                 April 1997
  2645.  
  2646.  
  2647.                }
  2648.                /* Done, so disconnect */
  2649.                ld.disconnect();
  2650.            }
  2651.            catch( LDAPException e ) {
  2652.                System.out.println( "Error: " + e.toString() );
  2653.            }
  2654.        }
  2655.    }
  2656.  
  2657.  
  2658.  
  2659.  
  2660.  
  2661.  
  2662.  
  2663.  
  2664.  
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698. Expires 10/97                                                  [Page 45]
  2699.  
  2700.  
  2701.